Files API

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 diretamente, 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 ver o suporte por modelo.

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_id exclusivo
• Baixe arquivos que são criados por skills ou pela ferramenta de execução de código
• Referencie arquivos em requisições de Messages 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 Files API

Fazendo upload de um arquivo

Faça upload de um arquivo para ser referenciado em chamadas futuras à 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
}

downloadable é false para 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.

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:

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 à 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 para 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.

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é limit arquivos (20 por padrão e no máximo 1.000), e o cursor next_page da resposta busca a próxima página quando passado de volta como o parâmetro page. Os arquivos são ordenados do mais recente para o mais antigo. Consulte a referência da API List Files. Os SDKs retornam a primeira página e fornecem auxiliares de paginação automática. O exemplo de CLI limita o total com --max-items:

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

Remova 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 por arquivo
• Armazenamento total: 1 TB por organização

Ciclo de vida dos arquivos

• Os arquivos têm escopo restrito 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 ou renomeados após o upload. Para alterar o conteúdo de um arquivo, faça upload de 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é atingirem seu expires_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 à Messages API e nos usos de ferramentas associados
• Arquivos que os usuários excluem serão excluídos de acordo com a política de retenção de dados da Anthropic. Para elegibilidade a ZDR em todos os recursos, consulte API e retenção de dados

Expiração de arquivos

Para que um arquivo expire automaticamente, inclua um campo de formulário expires_in_seconds ao fazer o upload. O valor é um número inteiro de segundos entre 3.600 (1 hora) e 7.776.000 (90 dias). O timestamp expires_at resultante (RFC 3339) aparece em toda resposta 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 de Messages que referencia o arquivo falha antes da inferência
• Seus metadados (GET /v1/files/{file_id}) permanecem legíveis por até 30 dias, com expires_at no passado
• Ele continua aparecendo nas respostas de listagem durante essa janela; compare expires_at com 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.

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 ainda 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:

Para migrar:

1. Remova o cabeçalho beta. Retire anthropic-beta: files-api-2025-04-14 das suas requisições. Nos SDKs, chame client.files em vez de client.beta.files; manter client.beta.files funciona apenas nas versões do SDK que não enviam mais o cabeçalho. Versões anteriores o enviam a partir de client.beta.files mesmo sem o argumento betas.
2. Atualize a paginação. Substitua os loops com after_id/before_id pelo cursor page/next_page, ou use os auxiliares de paginação automática do SDK mostrados em Gerenciando arquivos.
3. Leia expires_at. O campo aparece apenas sem o cabeçalho; null significa 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, 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. Ele aceita um argumento betas para recursos de Files que ainda estão em beta, como a filtragem por scope_id sob um cabeçalho beta de Managed Agents. Versões anteriores do SDK são tipadas com 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_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)
• Não baixável (400): Arquivos que você envia têm "downloadable": false e 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 a 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

Compatibility