API de Arquivos do Claude: carregue uma vez e use em qualquer lugar (guia GA)

A Files API da Claude permite que você faça upload de um arquivo uma única vez para https://api.anthropic.com/v1/files, receba de volta um file_id e referencie esse ID em qualquer requisição do Messages em vez de reenviar o conteúdo a cada vez. Desde 20 de agosto de 2026, ela está disponível de forma geral na Claude Platform: sem cabeçalho beta, 1 TB de armazenamento por organização e limites de taxa cinco vezes maiores que os do beta. A Anthropic anunciou a mudança em seu post sobre agentes de produção, junto com a GA para uso de computador, a ferramenta de navegador e a Skills API.

Este guia cobre o ciclo de vida completo: upload, referência a arquivos em mensagens, download de saídas geradas, expiração, o modelo de segurança do workspace e os limites que você vai encontrar em produção. Como cada etapa aqui é uma chamada HTTP, seu agente de codificação pode transformar todo o fluxo em um cenário de teste da CLI do Apidog em vez de um monte de comandos curl avulsos.

O que a Files API faz

A Files API é uma camada de armazenamento do tipo "crie uma vez, use muitas vezes" para a Claude API. Ela resolve um custo específico: se seu app faz perguntas sobre o mesmo PDF de 40 páginas ao longo de centenas de requisições, reenviar esse PDF em cada requisição desperdiça largura de banda e complica o código do seu cliente. Com a Files API, você:

Ciclo de vida da Claude Files API: upload, referência por file_id, download, exclusão

Faz upload de um arquivo para o armazenamento da Anthropic e recebe um file_id exclusivo
Referencia esse ID em requisições do Messages por meio de um bloco de conteúdo
Baixa arquivos que as skills ou a ferramenta de execução de código geram (gráficos, planilhas, apresentações)
Gerencia tudo com operações de listagem, recuperação de metadados e exclusão

A superfície de endpoints é pequena:

Operação	Endpoint
Fazer upload de um arquivo	`POST /v1/files`
Listar arquivos	`GET /v1/files`
Obter metadados do arquivo	`GET /v1/files/{file_id}`
Baixar o conteúdo do arquivo	`GET /v1/files/{file_id}/content`
Excluir um arquivo	`DELETE /v1/files/{file_id}`

Tudo isso funciona com os cabeçalhos padrão x-api-key e anthropic-version: 2023-06-01. Se você é novo na própria Messages API, nosso guia da Claude Opus 5 API cobre o básico de autenticação e formato de requisição.

O que mudou na GA

A Files API passou meses em beta atrás de um cabeçalho. A versão GA de 20 de agosto de 2026 mudou quatro coisas que importam para o planejamento de produção:

O que mudou quando a Claude Files API passou a GA

Sem cabeçalho beta. As requisições funcionam com cabeçalhos padrão na Claude API.
Limites de taxa 5x maiores. As operações de arquivo agora permitem cerca de 500 requisições por minuto, com limites maiores disponíveis por meio do time comercial.
1 TB de armazenamento por organização, com limite de 500 MB por arquivo.
Cobertura mais ampla da plataforma. A Files API roda diretamente na Claude API, na Claude Platform on AWS em beta e no Microsoft Foundry ao usar uma implantação Hosted on Anthropic. Ela não está disponível no Amazon Bedrock nem no Google Cloud Vertex AI, e não é elegível para acordos de retenção zero de dados. Planeje de acordo se você segue uma política de retenção rigorosa.

Fazendo upload de um arquivo

Os uploads são requisições multipart form, não JSON:

curl -X POST https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -F "file=@/path/to/report.pdf"

A resposta fornece tudo o que você precisa para referenciar o arquivo depois:

{
  "id": "file_011CNha8iCJcU1wXNR6q4V8w",
  "type": "file",
  "filename": "report.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 1024000,
  "created_at": "2026-08-24T00:00:00Z",
  "downloadable": false,
  "expires_at": null
}

Dois campos merecem atenção. downloadable é false para qualquer coisa que você fizer upload; apenas arquivos que a Claude gera por meio de skills ou execução de código podem ser baixados de volta. E expires_at é null a menos que você defina uma expiração no momento do upload (mais sobre isso abaixo).

No teste da CLI do Apidog mais adiante, a etapa de upload salva o id como uma variável, de modo que cada requisição subsequente referencia {{claude_file_id}} em vez de uma string fixa no código.

Referenciando arquivos em mensagens

Depois do upload, o arquivo se conecta a uma requisição do Messages por meio de um de três tipos de bloco de conteúdo, dependendo do arquivo:

Tipo de arquivo	Tipo MIME	Bloco de conteúdo
PDF, texto simples	`application/pdf`, `text/plain`	`document`
Imagens	`image/jpeg`, `image/png`, `image/gif`, `image/webp`	`image`
Conjuntos de dados e todo o resto	varia	`container_upload` (ferramenta de execução de código)

Uma requisição de resumo de PDF fica assim:

curl -X POST https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 1024,
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "Summarize this document."},
        {"type": "document", "source": {"type": "file", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"}}
      ]
    }]
  }'

O bloco document também aceita os campos opcionais title, context e citations, então você pode habilitar a saída de citações com base no arquivo enviado. Para imagens, troque o tipo de bloco para image com o mesmo formato de source. Para planilhas, CSVs que você quer analisar em vez de apenas ler, ou qualquer formato que o bloco document não aceite, use container_upload para entregar o arquivo à ferramenta de execução de código.

Uma observação sobre formatos: .docx e .xlsx não são suportados diretamente pelo bloco document. Converta arquivos do Word para PDF para manter a análise de imagens e as citações, ou extraia o texto simples e envie-o embutido.

Baixando arquivos gerados

O endpoint de download existe para saída, não para entrada. Quando a Claude monta um gráfico com execução de código ou produz uma planilha por meio de uma skill, a resposta inclui um file_id dentro do bloco bash_code_execution_tool_result. Esse ID é baixável:

curl "https://api.anthropic.com/v1/files/$FILE_ID/content" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  --output chart.png

Tentar baixar um arquivo que você enviou retorna um 400. Verifique a flag downloadable nos metadados antes de criar uma lógica de retentativa em torno disso; isso economiza um ticket de suporte. Esse ciclo de entrada por upload e saída por geração é a espinha dorsal do fluxo de trabalho da Skills API recém-disponibilizada em GA, em que as skills produzem documentos do Office que você baixa por esse mesmo endpoint. Nosso guia sobre Claude Skills aborda o que são as skills e como elas são executadas.

Expiração e ciclo de vida dos arquivos

Os arquivos persistem até que você os exclua ou até uma expiração definida no upload:

Passe expires_in_seconds como campo de formulário no upload. Intervalo válido: 3.600 (1 hora) a 7.776.000 (90 dias). É definido uma vez e não pode ser alterado depois.
Depois que expires_at passa, os downloads de conteúdo retornam 404 e qualquer requisição do Messages que referencie o arquivo falha antes da inferência.
Os metadados permanecem legíveis por até 30 dias após a expiração, e arquivos expirados ainda aparecem nas respostas de listagem durante essa janela. Compare expires_at com o horário atual ao filtrar.
Excluir um arquivo o remove imediatamente e não pode ser desfeito. O conteúdo expirado é liberado da sua cota de armazenamento, mas pode ser retido brevemente para revisão de segurança, então a expiração é uma ferramenta de ciclo de vida, não um controle de exclusão garantida.

O modelo de segurança: os arquivos têm escopo de workspace

Esse é o ponto mais delicado de toda a API. Os arquivos enviados ficam acessíveis para todo o seu workspace, não limitados a um usuário final, conversa ou sessão. Qualquer chave de API no mesmo workspace pode ler qualquer arquivo enviado ali, e todas as chaves compartilham o Default Workspace da sua organização, a menos que você as atribua a outro lugar.

As regras práticas:

Nunca aceite valores de file_id vindos de usuários finais. Um ID fornecido pelo usuário permitiria que um usuário do seu app lesse os uploads de outro usuário. Trate os IDs de arquivo como referências do lado do servidor e mantenha o mapeamento usuário-para-arquivo no seu próprio banco de dados.
Construindo multi-tenant? Um workspace por tenant. O workspace é a fronteira de isolamento. Cada organização recebe até 100 workspaces, e os times de conta da Anthropic podem aumentar esse número.

Se você já acompanha chaves de API por tenant para atribuição de custos (um tema que exploramos em como reduzir sua conta da Claude API), o mesmo layout de workspace oferece isolamento de arquivos de graça.

Limites e cobrança

Os números para se basear:

Limite	Valor
Tamanho máximo do arquivo	500 MB
Armazenamento da organização	1 TB
Limite de taxa da Files API	~500 requisições/minuto
Comprimento do nome do arquivo	1 a 255 caracteres
Intervalo de expiração	1 hora a 90 dias

A cobrança é amigável: fazer upload, baixar, listar e excluir arquivos é tudo gratuito. Você paga apenas quando o conteúdo do arquivo entra em uma requisição do Messages, onde é cobrado como tokens de entrada comuns. Um PDF de 100 páginas referenciado em dez requisições custa os mesmos tokens de entrada dez vezes; a Files API economiza largura de banda e complexidade do cliente, não gasto de tokens. Para economizar do lado dos tokens, combine referências de arquivo com cache de prompt.

Fique atento a estes erros: 413 quando um arquivo excede 500 MB, 400 quando sua organização atinge o teto de 1 TB, 400 quando o tipo do arquivo não corresponde ao seu bloco de conteúdo (uma imagem em um bloco document, por exemplo) e 404 para IDs fora do seu workspace.

Deixe o Claude Code testar a Files API com a CLI do Apidog

A Files API é um fluxo com estado e várias etapas, então ela merece um teste de regressão, não um histórico de shell. O Claude Code, ou qualquer agente de codificação, pode construir e executar esse teste por meio da CLI do Apidog. Configure uma vez:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

O token vem do Apidog, em Account Settings, API Access Token. Depois, dê um único prompt ao agente:

Use Apidog CLI on project <id>. Add the Files API endpoints (upload, list,
metadata, download, delete) and POST /v1/messages, with x-api-key from
{{ANTHROPIC_API_KEY}} and the anthropic-version header. Build a test scenario:
upload with expires_in_seconds=3600 and assert expires_at is set, save the id
as claude_file_id, reference it in a Messages call and assert 200, delete it,
then assert the metadata call returns 404. Run it and summarize any failures.

Os comandos que ele executa, verificados com a CLI do Apidog 2.2.7:

apidog cli-schema get endpoint-create
apidog endpoint create --project <id> --file files-upload.json
apidog test-scenario create --project <id> --name "Files API lifecycle" --priority 1
apidog test-scenario import-steps <scenarioId> --project <id> --source endpoint \
  --ids <uploadId>,<messagesId>,<deleteId>,<metadataId> --sync manual
apidog cli-schema validate test-scenario-update --file lifecycle.json
apidog test-scenario update <scenarioId> --project <id> --file lifecycle.json
apidog run -t <scenarioId> --project <id> -e <envId> \
  --env-var "ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY" -r cli,json

O agente repete endpoint create para cada endpoint, depois escreve a extração de variáveis e as asserções no cenário antes de executá-lo. Trocar de arquivo de teste mais tarde significa mudar uma etapa de upload, não cada requisição. Peça também um mock da resposta de upload (apidog mock create), e o time de frontend recebe o formato do JSON antes mesmo de o seu proxy de backend existir. A mesma linha apidog run com -r junit entra no CI; nosso guia da CLI do Apidog no Claude Code cobre a configuração do agente de ponta a ponta.

Perguntas frequentes

Ainda preciso de um cabeçalho beta? Não. Desde a GA de 20 de agosto de 2026, a Files API funciona na Claude API com os cabeçalhos padrão x-api-key e anthropic-version. Se o seu SDK ou proxy ainda fixa o antigo cabeçalho beta de files, remova-o quando fizer a atualização.

Posso atualizar o conteúdo de um arquivo? Não. Os arquivos são imutáveis após o upload. Envie um novo arquivo, aponte suas referências para o novo ID e exclua o antigo.

A Files API funciona no Bedrock ou no Vertex AI? Não. Ela está disponível na Claude API, na Claude Platform on AWS (beta) e no Microsoft Foundry com uma implantação Hosted on Anthropic. No Bedrock e no Vertex, você ainda precisa de conteúdo base64 embutido.

A Files API é a mesma coisa que a Skills API usa para saídas? Sim. As skills e a ferramenta de execução de código gravam seus documentos gerados no mesmo armazenamento de arquivos, e você os baixa por meio de GET /v1/files/{file_id}/content. O lado da Skills API desse fluxo de trabalho combina bem com testes automatizados.

Conclusão

A disponibilidade geral da Files API remove a última desculpa para empacotar em base64 o mesmo documento em cada requisição. Faça upload uma vez, referencie pelo ID, defina uma expiração e mantenha os arquivos de cada tenant em workspaces separados. A superfície da API são cinco endpoints, e todos eles são testáveis em minutos: peça ao seu agente de codificação para scriptar o fluxo com a CLI do Apidog, encadeie o file_id por meio de uma variável e coloque todo o ciclo de vida no CI antes que seus usuários encontrem os casos extremos no seu lugar.