Claude Platform Docs
MensagensTrabalhando com arquivos

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

Messages API
Referencie um arquivo enviado pelo seu file_id em um bloco document, image ou container_upload.
Managed Agents
Monte arquivos no sandbox da sessão ou referencie um 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_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 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_id em vez de reenviar o conteúdo
  • Gerencie seus arquivos com operações de listar, recuperar e excluir
Arquivos enviados ficam acessíveis para todo o seu workspace

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:

Response
{
  "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 arquivoTipo MIMETipo de bloco de conteúdoCaso de uso
PDFapplication/pdfdocumentAnálise de texto, processamento de documentos
Texto simplestext/plaindocumentAnálise de texto, processamento
Imagensimage/jpeg, image/png, image/gif, image/webpimageAnálise de imagens, tarefas visuais
Conjuntos de dados, outros (consulte Faça upload e analise seus próprios arquivos)Variacontainer_uploadAná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 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 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, com expires_at no passado.
  • Ele continua aparecendo nas respostas de listagem durante esse período; 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 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-14Sem 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 listagembefore_id, after_idpage, ou até 100 ids[] (before_id e after_id retornam um erro 400)
expires_at em objetos de arquivoNão retornadoSempre presente; null quando o arquivo não tem expiração
Content-Type na parte do arquivo enviadoObrigatórioOpcional; o tipo é detectado quando omitido

Para migrar:

  1. Remova o cabeçalho beta. Retire anthropic-beta: files-api-2025-04-14 das suas requisições. Com o SDK, 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 quando você não passa nenhum nome beta.
  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, 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_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): Os 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–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.
Output
{
  "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

Files API
APIs
  • Messages API
  • Managed Agents
Modelos
  • Todos os modelos

Endpoints aplicáveis

  • /v1/files
Retenção zero de dadosNão elegível

Arquivos retidos até serem explicitamente excluídos ou atingirem a expiração configurada. Saiba mais

HIPAANão elegível

Esta página foi útil?