Files API
Faça upload de arquivos uma única vez, referencie-os por file_id em requisições de Messages e faça download de saídas criadas por skills ou pela ferramenta de execução de código.
O uso varia conforme o produto
file_id em um bloco document, image ou container_upload.file_id em um evento user.message.A Files API permite que você faça upload e gerencie arquivos para usar com a Claude API sem precisar reenviar o conteúdo a cada requisiçã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ê pode explorar a referência da API diretamentePré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar., além deste guia.
Suporte a tipos de arquivo
Referenciar um file_id em uma requisição de Messages é suportado em todos os modelos que suportam o tipo de arquivo em questão. Imagens são suportadas em todos os modelos Claude atuais. Para PDFs e outros tipos de arquivo com a ferramenta de execução de código, consulte as páginas vinculadas para obter informações sobre o suporte a modelos.
Como a Files API funciona
A Files API oferece uma abordagem de criar uma vez e usar muitas vezes para trabalhar com arquivos:
- Faça upload de arquivos para o armazenamento seguro da Anthropic e receba um
file_idexclusivo - Baixe arquivos que são criados por skills ou pela ferramenta de execução de código
- Referencie arquivos em requisições de MessagesPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. usando o
file_idem vez de reenviar o conteúdo - Gerencie seus arquivos com operações de listar, recuperar e excluir
Os arquivos não têm escopo limitado a um usuário final, conversa ou sessão. Qualquer chave de API com acesso a um workspace pode acessar quaisquer arquivos enviados para esse workspace. Toda conta de serviço, e todo usuário cuja função na organização permita acesso à API, pode usar o workspace padrão, além de qualquer workspace ao qual você o adicione; portanto, mantenha os arquivos que precisam ficar separados em seu próprio workspace e acesse-os apenas com chaves com escopo limitado a esse workspace. Nunca aceite valores de file_id de usuários finais ou de outras fontes não confiáveis: um ID de arquivo fornecido pelo usuário permitiria que um usuário da sua aplicação lesse conteúdo enviado por outro usuário. Trate os IDs de arquivo como referências do lado do servidor e mantenha o mapeamento entre seus usuários e os arquivos deles na sua aplicação.
Se você estiver construindo uma aplicação multitenant sobre a Files API, crie um workspace separado para cada tenant. O workspace é a fronteira de isolamento dos arquivos, então um workspace para cada tenant garante aos dados desse tenant um isolamento rígido em relação a todos os outros tenants. Cada organização pode ter até 100 workspaces; entre em contato com a equipe da sua conta se precisar de mais.
Como usar a Files API
Fazendo upload de um arquivo
Faça upload de um arquivo para referenciá-lo em chamadas futuras da API:
uploaded = client.files.upload(
file=("document.pdf", open("/path/to/document.pdf", "rb"), "application/pdf"),
)
file_id = uploaded.id
print(file_id)A resposta do upload de um arquivo inclui:
{
"id": "file_011CNha8iCJcU1wXNR6q4V8w",
"type": "file",
"filename": "document.pdf",
"mime_type": "application/pdf",
"size_bytes": 1024000,
"created_at": "2025-01-01T00:00:00Z",
"downloadable": false,
"expires_at": null
}downloadablePré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. é false para os arquivos que você envia. Somente arquivos criados por skills ou pela ferramenta de execução de código podem ser baixados. Consulte Baixando um arquivo.
A referência da API descreve todos os campos do objeto de arquivo.
Usando um arquivo em mensagens
Após o upload, referencie o arquivo passando o id da resposta de upload como file_id:
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Please summarize this document for me."},
{
"type": "document",
"source": {
"type": "file",
"file_id": file_id,
},
},
],
}
],
)
print(response)Tipos de arquivo e blocos de conteúdo
A Files API 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 imagens, tarefas visuais |
| Conjuntos de dados, outros (consulte Faça upload e analise seus próprios arquivos) | Varia | container_upload | Análise de dados, visualização |
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", // Optional
"context": "Context about the document", // Optional
"citations": { "enabled": true } // Optional, enables citations
}Blocos de imagem
Para imagens, use o bloco de conteúdo image:
{
"type": "image",
"source": {
"type": "file",
"file_id": "file_011CPMxVD3fHLUhvTqtsQA5w"
}
}Blocos de upload para contêiner
Para enviar um arquivo para a ferramenta de execução de código, use o bloco de conteúdo container_upload:
{
"type": "container_upload",
"file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
}Trabalhando com outros formatos de arquivo
Para tipos de arquivo que o bloco document não suporta (por exemplo, .docx e .xlsx), converta os arquivos em texto simples e inclua o conteúdo diretamente na sua mensagem. Arquivos que já são texto simples, como arquivos .csv e .md, podem ser lidos dessa forma ou enviados pela Files API com um tipo de conteúdo text/plain explícito. Para analisar conjuntos de dados em vez de lê-los como texto, faça upload deles para a ferramenta de execução de código usando um bloco container_upload (consulte Faça upload e analise seus próprios arquivos).
Os exemplos a seguir leem um arquivo de texto e enviam seu conteúdo como texto simples:
client = anthropic.Anthropic()
# Lê o arquivo de texto
with open("document.txt") as f:
text_content = f.read()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "text",
"text": f"Here's the document content:\n\n{text_content}\n\nPlease summarize this document.",
}
],
}
],
)
for block in response.content:
if block.type == "text":
print(block.text)Gerenciando arquivos
Listar arquivos
Recupere uma lista dos seus arquivos enviados. O endpoint é paginado: cada requisição retorna até limitPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. arquivos (20 por padrão, e no máximo 1.000), e o cursor next_pagePré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. da resposta busca a próxima página quando passado de volta como o parâmetro pagePré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar.. Os arquivos são ordenados do mais recente para o mais antigo. Consulte a referência da API Listar arquivosPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar.. O SDK retorna a primeira página e fornece auxiliares de paginação automática.
client = anthropic.Anthropic()
files = client.files.list()
print(files)Para verificar um conjunto conhecido de arquivos em uma única requisição em vez de paginar, passe até 100 IDs de arquivo como parâmetros de consulta ids[]. Uma requisição com ids[] sempre retorna uma única página (next_page é null), e qualquer ID que não corresponda a um arquivo no seu workspace é silenciosamente omitido de data; compare os IDs retornados com os IDs solicitados para detectar ausências. ids[] não pode ser combinado com page ou limit.
Obter metadados do arquivo
Recupere informações sobre um arquivo específico:
file = client.files.retrieve_metadata(file_id)
print(file)Excluir um arquivo
Exclua um arquivo do seu workspace:
client.files.delete(file_id)Baixando um arquivo
Baixe arquivos que foram criados por skills ou pela ferramenta de execução de código. Arquivos que você envia não podem ser baixados. O file_id de um arquivo gerado aparece no bloco de conteúdo bash_code_execution_tool_result da resposta de Messages que o criou:
file_content = client.files.download(file_id)
file_content.write_to_file("downloaded_file.txt")Na Claude API, os arquivos de imagem, vídeo e áudio suportados que Claude produz com a ferramenta de execução de código, incluindo arquivos criados por skills, trazem Content Credentials C2PA assinadas quando você os baixa. Consulte Content Credentials em arquivos gerados para saber o que a credencial contém e como verificá-la.
Armazenamento de arquivos e limites
Limites de armazenamento
- Tamanho máximo de arquivo: 500 MB para cada arquivo
- Armazenamento total: 1 TB para cada organização
Ciclo de vida dos arquivos
- Os arquivos têm escopo limitado ao workspace em que foram enviados. Qualquer requisição no mesmo workspace pode referenciá-los; nunca aceite IDs de arquivo de fontes não confiáveis (consulte o aviso sobre acesso ao workspace).
- Os arquivos não podem ser modificados nem renomeados após o upload. Para alterar o conteúdo de um arquivo, envie um novo arquivo e exclua o antigo.
- Os arquivos persistem até que você os exclua com o endpoint
DELETE /v1/files/{file_id}ou até que atinjam seuexpires_at. - Arquivos excluídos não podem ser recuperados.
- Os arquivos ficam inacessíveis pela API pouco depois da exclusão, mas podem persistir em chamadas ativas da Messages API e nos usos de ferramentas associados.
- Os arquivos que os usuários excluírem serão excluídos de acordo com a política de retenção de dados da Anthropic.
Expiração de arquivos
Para que um arquivo expire automaticamente, inclua um campo de formulário expires_in_secondsPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. ao enviá-lo. O valor é um número inteiro de segundos entre 3.600 (1 hora) e 7.776.000 (90 dias). O timestamp expires_atPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. resultante (RFC 3339) aparece em todas as respostas de arquivo e é null para arquivos enviados sem expiração. A expiração é definida uma única vez no upload e não pode ser alterada.
Quando um arquivo atinge seu expires_at:
- Baixar seu conteúdo (
GET /v1/files/{file_id}/content) retorna um erro 404. - Uma requisição Messages que referencia o arquivo falha antes da inferência.
- Seus metadados (
GET /v1/files/{file_id}) continuam legíveis por até 30 dias, comexpires_atno passado. - Ele continua aparecendo nas respostas de listagem durante esse período; compare
expires_atcom o horário atual para filtrar arquivos expirados.
Excluir um arquivo expirado com DELETE /v1/files/{file_id} remove seus metadados imediatamente em vez de aguardar o término da janela de 30 dias.
Registro de auditoria
Se sua organização tem a Compliance API habilitada, seu Activity Feed registra as operações da Files API feitas com uma chave de API da Claude API ou a partir do Claude Console: cada upload (POST /v1/files), download de conteúdo (GET /v1/files/{file_id}/content) e exclusão (DELETE /v1/files/{file_id}) aparece como uma atividade platform_file_uploaded, platform_file_content_downloaded ou platform_file_deleted. A listagem de arquivos e a recuperação de metadados de arquivos não são registradas. Operações que ocorrem enquanto a Compliance API está desativada não são registradas e não podem ser recuperadas posteriormente, portanto configure a Compliance API antes de depender dessa trilha de auditoria. No Claude Platform on AWS, audite as operações de arquivo com eventos de dados do AWS CloudTrail em vez disso.
Migrar de files-api-2025-04-14
A Files API saiu da fase beta e não precisa de cabeçalho beta. Migrar de files-api-2025-04-14 é opcional: requisições que o enviam continuam funcionando e continuam retornando os formatos de resposta beta, então uma integração existente continua funcionando até que você a altere. Remover o cabeçalho muda essas requisições para os formatos documentados nesta página:
Com files-api-2025-04-14 | Sem o cabeçalho | |
|---|---|---|
| Resposta de listagem | { data, has_more, first_id, last_id } | { data, next_page }; passe next_page de volta como o parâmetro de consulta page |
| Cursores de listagem | before_id, after_id | page, ou até 100 ids[] (before_id e after_id retornam um erro 400) |
expires_at em objetos de arquivo | Não retornado | Sempre presente; null quando o arquivo não tem expiração |
Content-Type na parte do arquivo enviado | Obrigatório | Opcional; o tipo é detectado quando omitido |
Para migrar:
- Remova o cabeçalho beta. Retire
anthropic-beta: files-api-2025-04-14das suas requisições. Com o SDK, chameclient.filesem vez declient.beta.files; manterclient.beta.filesfunciona apenas nas versões do SDK que não enviam mais o cabeçalho. Versões anteriores o enviam a partir declient.beta.filesmesmo quando você não passa nenhum nome beta. - Atualize a paginação. Substitua os loops com
after_id/before_idpelo cursorpage/next_page, ou use os auxiliares de paginação automática do SDK mostrados em Gerenciando arquivos. - Leia
expires_at. O campo aparece apenas sem o cabeçalho;nullsignifica que o arquivo não tem expiração (consulte Expiração de arquivos).
Namespace beta do SDK
A partir do Python SDK 1.2.0, TypeScript SDK 0.122.0, Go SDK 1.68.0, Java SDK 2.59.0, PHP SDK 0.45.0, Ruby SDK 1.67.0 e C# SDK 12.44.0, client.beta.files não envia mais files-api-2025-04-14 e retorna os mesmos formatos que client.files, com nomes de tipo prefixados com Beta (em PHP, classes no namespace Anthropic\Beta). Ele aceita nomes beta por meio de betas para recursos de Files que estão em beta, como a filtragem por scope_id com um cabeçalho beta de Managed Agents. Versões anteriores do SDK são tipadas para os formatos beta; se você depende desses tipos, permaneça em uma versão anterior até migrar.
Requisições que carregam anthropic-beta: managed-agents-2026-04-01 sem files-api-2025-04-14 recebem os formatos desta página com uma concessão de compatibilidade em GET /v1/files: before_id e after_id ainda são aceitos (não combináveis com page ou ids[]), e a resposta de listagem inclui has_more, first_id e last_id junto com next_page. Versões beta posteriores de Managed Agents recebem o formato simples.
Tratamento de erros
Erros comuns ao usar a Files API incluem:
- Arquivo não encontrado (404): O
file_idespecificado 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).
- Não baixável (400): Os arquivos que você envia têm
"downloadable": falsee não podem ser baixados. Somente arquivos criados por skills ou pela ferramenta de execução de código podem ser baixados. - Excede o tamanho da janela de contexto (400): O arquivo é maior que o tamanho da “context window” (janela de contexto) (por exemplo, usar um arquivo de texto simples de 500 MB em uma requisiçã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 (400): Sua organização atingiu o limite de armazenamento de 1 TB.
{
"type": "error",
"error": {
"type": "not_found_error",
"message": "File `file_011CNha8iCJcU1wXNR6q4V8w` not found."
},
"request_id": "req_011CQFYcrRp7mCHLDsAYT8Qt"
}Uso e cobrança
As operações da Files API são gratuitas:
- Fazer upload de arquivos
- Baixar arquivos
- Listar arquivos
- Obter metadados de arquivos
- Excluir arquivos
O conteúdo de arquivos usado em requisições de Messages é cobrado como tokens de entrada.
Limites de taxa
As chamadas de API relacionadas a arquivos são limitadas a aproximadamente 500 requisições por minuto. Para solicitar um “rate limit” (limite de taxa) maior, entre em contato com vendas.
Próximos passos
Processe PDFs com o Claude. Extraia texto, analise gráficos e compreenda o conteúdo visual dos seus documentos.
Execute código Python e Bash em um contêiner isolado para analisar dados, gerar arquivos e iterar em soluções.
Processe e analise entradas visuais e gere texto e código a partir de imagens.
Disponibilidade
Claude API
- APIs
- Messages API
- Managed Agents
- Modelos
- Todos os modelos
Claude Platform on AWS
- APIs
- Messages API
- Managed Agents
- Modelos
- Todos os modelos
Claude Models on Google Cloud (Anthropic managed)
- APIs
- Messages API
- Managed Agents
- Modelos
- Todos os modelos
Microsoft Foundry (hosted on Anthropic)
- API
- Messages API
- Modelos
- Todos os modelos
Tratamento de dados
Visão geral do tratamento de dadosEndpoints aplicáveis
/v1/files
Arquivos retidos até serem explicitamente excluídos ou atingirem a expiração configurada. Saiba mais
Esta página foi útil?