Files API

A Files API permite que você faça upload e gerencie arquivos para usar com a API do Claude 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ê também pode usar a Files API para evitar ter que reenviar continuamente documentos e imagens usados com frequência em várias chamadas de API. Você pode explorar a referência da API diretamente, além deste guia.



Modelos compatíveis

Referenciar um file_id em uma requisição Messages é compatível com todos os modelos que suportam o tipo de arquivo em questão. Imagens são compatíveis com todos os modelos atuais do Claude. Para PDFs e outros tipos de arquivo com a ferramenta de execução de código, consulte as páginas vinculadas para ver a compatibilidade de modelos.

A Files API está disponível na API do Claude, no Claude Platform on AWS e no Microsoft Foundry. No Microsoft Foundry, a Files API requer uma implantação Hosted on Anthropic. Atualmente, ela não está disponível no Amazon Bedrock ou no Google Cloud.



Como a Files API funciona

A Files API oferece uma abordagem simples de criar uma vez e usar várias 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 a partir de skills ou da ferramenta de execução de código
• Referencie arquivos em requisições Messages usando o file_id em vez de reenviar o conteúdo
• Gerencie seus arquivos com operações de listagem, recuperação e exclusão



Como usar a Files API



Fazendo upload de um arquivo

Faça upload de um arquivo para ser referenciado em chamadas de API futuras:

uploaded = client.beta.files.upload(
    file=("document.pdf", open("/path/to/document.pdf", "rb"), "application/pdf"),
)

A resposta do upload de um arquivo incluirá:

{
  "id": "file_011CNha8iCJcU1wXNR6q4V8w",
  "type": "file",
  "filename": "document.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 1024000,
  "created_at": "2025-01-01T00:00:00Z",
  "downloadable": false
}



Usando um arquivo em mensagens

Após o upload, referencie o arquivo usando seu file_id:

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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,
                    },
                },
            ],
        }
    ],
    betas=["files-api-2025-04-14"],
)
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:



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 na sua mensagem:

import pandas as pd
# ...
# Exemplo: Lendo um arquivo CSV
df = pd.read_csv("data.csv")
csv_content = df.to_string()

# Envie como texto simples na mensagem
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": f"Here's the CSV data:\n\n{csv_content}\n\nPlease analyze this data.",
                }
            ],
        }
    ],
)

print(response.content[0].text)



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"
  }
}



Gerenciando arquivos



Listar arquivos

Recupere uma lista dos seus arquivos enviados:

client = anthropic.Anthropic()
files = client.beta.files.list()



Obter metadados do arquivo

Recupere informações sobre um arquivo específico:

file = client.beta.files.retrieve_metadata(file_id)



Excluir um arquivo

Remova um arquivo do seu workspace:

result = client.beta.files.delete(file_id)



Baixando um arquivo

Baixe arquivos que foram criados por skills ou pela ferramenta de execução de código:

file_content = client.beta.files.download(file_id)

# Salvar em arquivo
file_content.write_to_file("downloaded_file.txt")



Armazenamento de arquivos e limites



Limites de armazenamento

• Tamanho máximo de arquivo: 500 MB por arquivo
• Armazenamento total: 500 GB por organização



Ciclo de vida do arquivo

• Os arquivos têm escopo no workspace da chave de API. Outras chaves de API podem usar arquivos criados por qualquer outra chave de API associada ao mesmo workspace
• Os arquivos persistem até que você os exclua
• 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
• Arquivos que os usuários excluírem serão excluídos de acordo com a política de retenção de dados da Anthropic.



Retenção de dados

Arquivos enviados via Files API são retidos até serem explicitamente excluídos usando o endpoint DELETE /v1/files/{file_id}. Os arquivos são armazenados para reutilização em várias requisições de API.

Para elegibilidade ZDR em todos os recursos, consulte API e retenção de dados.



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)
• 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 (403): Sua organização atingiu o limite de armazenamento de 500 GB

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "File not found: file_011CNha8iCJcU1wXNR6q4V8w"
  }
}



Uso e cobrança

As operações da File 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 Messages é cobrado como tokens de entrada. Você só pode baixar arquivos criados por skills ou pela ferramenta de execução de código.



Limites de taxa

Durante o período beta:

• As chamadas de API relacionadas a arquivos são limitadas a aproximadamente 100 requisições por minuto
• Entre em contato conosco se precisar de limites mais altos para o seu caso de uso