API de Arquivos

A API de Arquivos permite que você faça upload e gerencie arquivos para usar com a API da Anthropic sem precisar reenviar o conteúdo a cada solicitaçã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 API de Arquivos para evitar ter que reenviar continuamente documentos e imagens frequentemente usados em várias chamadas de API.

​

Modelos suportados

Referenciar um file_id em uma solicitação de Mensagens é suportado em todos os modelos que suportam o tipo de arquivo em questão. 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 arquivos para a ferramenta de execução de código no Claude 3.5 Haiku e em todos os modelos Claude 3.7+.

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

​

Como funciona a API de Arquivos

A API de Arquivos 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 pela ferramenta de execução de código
• Referencie arquivos em solicitações de Mensagens 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 API de Arquivos

​

Fazendo upload de um arquivo

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

curl -X POST 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" \
  -F "file=@/path/to/document.pdf"

​

Tipos de arquivos e blocos de conteúdo

A API de Arquivos suporta diferentes tipos de arquivos que correspondem a diferentes tipos de blocos de conteúdo:

​

Blocos de documento

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

{
  "type": "document",
  "source": {
    "type": "file",
    "file_id": "file_abc123"
  },
  "title": "Título do Documento", // Opcional
  "context": "Contexto sobre o documento", // 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_xyz789"
  }
}

​

Gerenciando arquivos

​

Listar arquivos

Recupere uma lista dos seus arquivos carregados:

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_abc123 \
  -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 espaço de trabalho:

curl -X DELETE https://api.anthropic.com/v1/files/file_abc123 \
  -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 pela ferramenta de execução de código:

curl -X GET "https://api.anthropic.com/v1/files/file_abc123/content" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  --output downloaded_file.txt

​

Armazenamento de arquivos e limites

​

Limites de armazenamento

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

​

Ciclo de vida do arquivo

• Os arquivos são limitados ao espaço de trabalho da chave de API. Outras chaves de API podem usar arquivos criados por qualquer outra chave de API associada ao mesmo espaço de trabalho
• 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

​

Tratamento de erros

Erros comuns ao usar a API de Arquivos 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)
• Arquivo muito grande (413): O arquivo excede o limite de 500 MB
• Limite de armazenamento excedido (403): Sua organização atingiu o limite de armazenamento de 100 GB
• 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)

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

​

Uso e faturamento

Operações da API de Arquivos 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 solicitações de Messages é cobrado como tokens de entrada. Você só pode baixar arquivos criados 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 solicitações por minuto
• Entre em contato conosco se você precisar de limites mais altos para seu caso de uso