Files API

A Files API permite que você faça upload e gerencie arquivos para usar com a API do Claude sem precisar reenviar o conteúdo a cada requisição. Isso é particularmente útil ao usar a ferramenta de execução de código para fornecer entradas (por exemplo, conjuntos de dados e documentos) e depois baixar saídas (por exemplo, gráficos). Você também pode usar a Files API para evitar ter que reenviar continuamente documentos e imagens frequentemente usados em múltiplas chamadas de API. Você pode explorar a referência da API diretamente, além deste guia.

Modelos suportados

Referenciar um file_id em uma requisição de Messages é suportado em todos os modelos que suportam o tipo de arquivo fornecido. Por exemplo, imagens são suportadas em todos os modelos Claude 3+, PDFs em todos os modelos Claude 3.5+, e vários outros tipos de arquivo para a ferramenta de execução de código no Claude Haiku 4.5 mais todos os modelos Claude 3.7+.

A Files API atualmente não é suportada no Amazon Bedrock ou Google Vertex AI.

Como a Files API funciona

A Files API fornece uma abordagem simples de criar uma vez e usar muitas vezes para trabalhar com arquivos:

• Faça upload de arquivos para nosso armazenamento seguro e receba um file_id único
• Baixe arquivos que são criados por skills ou pela ferramenta de execução de código
• Referencie arquivos em requisições de Messages usando o file_id em vez de reenviar o conteúdo
• Gerencie seus arquivos com operações de listar, recuperar e excluir

Como usar a Files API

Fazendo upload de um arquivo

Faça upload de um arquivo para ser referenciado em chamadas de API futuras:

A resposta do upload de um arquivo incluirá:

{
  "id": "file_011CNha8iCJcU1wXNR6q4V8w",
  "type": "file",
  "filename": "document.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 1024000,
  "created_at": "2025-01-01T00:00:00Z",
  "downloadable": false
}

Usando um arquivo em mensagens

Uma vez feito o upload, referencie o arquivo usando seu file_id:

Tipos de arquivo e blocos de conteúdo

A Files API suporta diferentes tipos de arquivo que correspondem a diferentes tipos de blocos de conteúdo:

Trabalhando com outros formatos de arquivo

Para tipos de arquivo que não são suportados como blocos document (.csv, .txt, .md, .docx, .xlsx), converta os arquivos para texto simples e inclua o conteúdo diretamente em sua mensagem:

Blocos de documento

Para PDFs e arquivos de texto, use o bloco de conteúdo document:

{
  "type": "document",
  "source": {
    "type": "file",
    "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
  },
  "title": "Document Title", // Opcional
  "context": "Context about the document", // Opcional
  "citations": { "enabled": true } // Opcional, habilita citações
}

Blocos de imagem

Para imagens, use o bloco de conteúdo image:

{
  "type": "image",
  "source": {
    "type": "file",
    "file_id": "file_011CPMxVD3fHLUhvTqtsQA5w"
  }
}

Gerenciando arquivos

Listar arquivos

Recupere uma lista dos seus arquivos enviados:

curl https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

Obter metadados do arquivo

Recupere informações sobre um arquivo específico:

curl https://api.anthropic.com/v1/files/file_011CNha8iCJcU1wXNR6q4V8w \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

Excluir um arquivo

Remova um arquivo do seu workspace:

curl -X DELETE https://api.anthropic.com/v1/files/file_011CNha8iCJcU1wXNR6q4V8w \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

Baixando um arquivo

Baixe arquivos que foram criados por skills ou pela ferramenta de execução de código:

Armazenamento e limites de arquivos

Limites de armazenamento

• Tamanho máximo de arquivo: 500 MB por arquivo
• Armazenamento total: 100 GB por organização

Ciclo de vida dos arquivos

• Os arquivos têm escopo para o workspace da chave de API. Outras chaves de API podem usar arquivos criados por qualquer outra chave de API associada ao mesmo workspace
• Os arquivos persistem até que você os exclua
• Arquivos excluídos não podem ser recuperados
• Os arquivos ficam inacessíveis via API logo após a exclusão, mas podem persistir em chamadas ativas da API Messages e usos de ferramentas associados
• Os arquivos que os usuários excluírem serão deletados de acordo com nossa política de retenção de dados.

Retenção de dados

Os arquivos enviados via Files API são retidos até serem explicitamente excluídos usando o endpoint DELETE /v1/files/{file_id}. Os arquivos são armazenados para reutilização em múltiplas requisições de API.

Para elegibilidade ZDR em todos os recursos, consulte API e Retenção de Dados.

Tratamento de erros

Erros comuns ao usar a Files API incluem:

• Arquivo não encontrado (404): O file_id especificado não existe ou você não tem acesso a ele
• Tipo de arquivo inválido (400): O tipo de arquivo não corresponde ao tipo de bloco de conteúdo (por exemplo, usar um arquivo de imagem em um bloco de documento)
• Excede o tamanho da janela de contexto (400): O arquivo é maior que o tamanho da janela de contexto (por exemplo, usar um arquivo de texto simples de 500 MB em uma requisição /v1/messages)
• Nome de arquivo inválido (400): O nome do arquivo não atende aos requisitos de comprimento (1-255 caracteres) ou contém caracteres proibidos (<, >, :, ", |, ?, *, \, /, ou caracteres unicode 0-31)
• O arquivo excede o limite de 500 MB

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "File not found: file_011CNha8iCJcU1wXNR6q4V8w"
  }
}

Uso e faturamento

As operações da Files API são gratuitas:

• Upload de arquivos
• Download de arquivos
• Listagem de arquivos
• Obtenção de metadados de arquivos
• Exclusão de arquivos

O conteúdo de arquivos usado em requisições Messages é cobrado como tokens de entrada. Você só pode baixar arquivos criados por skills ou pela ferramenta de execução de código.

Limites de taxa

Durante o período beta:

• Chamadas de API relacionadas a arquivos são limitadas a aproximadamente 100 requisições por minuto
• Entre em contato conosco se precisar de limites mais altos para seu caso de uso