API de Arquivos
A API de Arquivos permite fazer upload e gerenciar arquivos para usar com a API da Anthropic sem precisar reenviar conteúdo a cada solicitação.
A API de Arquivos permite fazer upload e gerenciar arquivos para usar com a API da Anthropic sem precisar reenviar 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 usados com frequência 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 específico. 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 3.5 Haiku mais 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, usar muitas vezes para trabalhar com arquivos:
- Fazer upload de arquivos para nosso armazenamento seguro e receber um
file_id
único - Baixar arquivos que são criados pela ferramenta de execução de código
- Referenciar arquivos em solicitações de Mensagens usando o
file_id
em vez de reenviar conteúdo - Gerenciar 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:
Usando um arquivo em mensagens
Uma vez enviado, 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 bloco 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 |
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:
Para arquivos .docx contendo imagens, converta-os primeiro para formato PDF, depois use o suporte a PDF para aproveitar a análise de imagem integrada. Isso permite usar citações do documento PDF.
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 enviados:
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ê enviou não podem ser baixados.
Armazenamento e limites de arquivos
Limites de armazenamento
- Tamanho máximo do arquivo: 500 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 API. Outras chaves API podem usar arquivos criados por qualquer outra chave API associada ao mesmo espaço de trabalho
- Os arquivos persistem até você excluí-los
- 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)
- 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) - 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
Uso e cobrança
As 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 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