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.
A API de Arquivos está atualmente em beta. Entre em contato através do nosso formulário de feedback para compartilhar sua experiência com a API de Arquivos.
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
Para usar a API de Arquivos, você precisará incluir o cabeçalho de recurso beta: anthropic-beta: files-api-2025-04-14
.
Fazendo upload de um arquivo
Faça upload de um arquivo para ser referenciado em futuras chamadas de API:
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:
Tipo de Arquivo | Tipo MIME | Tipo de Bloco de Conteúdo | Caso de Uso |
---|---|---|---|
application/pdf | document | Análise de texto, processamento de documentos | |
Texto simples | text/plain | document | Análise de texto, processamento |
Imagens | image/jpeg , image/png , image/gif , image/webp | image | Análise de imagem, tarefas visuais |
Conjuntos de dados, outros | Varia | container_upload | Analisar dados, criar visualizações |
Blocos de documento
Para PDFs e arquivos de texto, use o bloco de conteúdo document
:
Blocos de imagem
Para imagens, use o bloco de conteúdo image
:
Gerenciando arquivos
Listar arquivos
Recupere uma lista dos seus arquivos carregados:
Obter metadados do arquivo
Recupere informações sobre um arquivo específico:
Excluir um arquivo
Remova um arquivo do seu espaço de trabalho:
Baixando um arquivo
Baixe arquivos que foram criados pela ferramenta de execução de código:
Você só pode baixar arquivos que foram criados pela ferramenta de execução de código. Arquivos que você carregou não podem ser baixados.
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)
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