API de Arquivos

A API de Arquivos permite que você carregue e gerencie arquivos para usar com a API Claude sem fazer upload novamente do 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 fazer upload continuamente de documentos e imagens frequentemente usados em várias chamadas de API. Você pode explorar a referência da API diretamente, além deste guia.

Modelos suportados

Referenciar um file_id em uma solicitação de Mensagens é 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 e em todos os modelos Claude 3.7+.

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

Como a API de Arquivos funciona

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

• Carregue arquivos em nosso armazenamento seguro e receba um file_id único
• Baixe arquivos que são criados a partir de habilidades ou da ferramenta de execução de código
• Referencie arquivos em solicitações de Mensagens usando o file_id em vez de fazer upload novamente do conteúdo
• Gerencie seus arquivos com operações de listagem, recuperação e exclusão

Como usar a API de Arquivos

Carregando um arquivo

Carregue um arquivo para ser referenciado em futuras chamadas de API:

A resposta do carregamento 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 carregado, referencie o arquivo usando seu file_id:

Tipos de arquivo e blocos de conteúdo

A API de Arquivos 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 de 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_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 habilidades ou pela ferramenta de execução de código:

Armazenamento de arquivo e limites

Limites de armazenamento

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

Ciclo de vida do arquivo

• Os arquivos estão no escopo do 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 de Mensagens e usos de ferramentas associados
• Os arquivos que os usuários excluem serão excluídos de acordo com nossa política de retenção de dados.

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)
• 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 solicitaçã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 API de Arquivos são gratuitas:

• Carregamento de arquivos
• Download de arquivos
• Listagem de arquivos
• Obtenção de metadados de arquivo
• Exclusão de arquivos

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

Limites de taxa

Durante o período beta:

• As 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