API de Arquivos

Files API

A API de Arquivos permite que você carregue e gerencie arquivos para usar com a API Claude sem fazer upload novamente do conteúdo a cada solicitaçã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 API de Arquivos para evitar ter que fazer upload continuamente de documentos e imagens frequentemente usados em várias chamadas de API. Você pode explorar a referência da API diretamente, além deste guia.

A API de Arquivos está em beta. Entre em contato através do formulário de feedback para compartilhar sua experiência com a API de Arquivos.

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

Modelos suportados

Referenciar um file_id em uma solicitação de Mensagens é suportado em todos os modelos que suportam o tipo de arquivo fornecido. Por exemplo, imagens são suportadas em todos os modelos Claude 3+, PDFs em todos os modelos Claude 3.5+, e vários outros tipos de arquivo para a ferramenta de execução de código no Claude Haiku 4.5 mais todos os modelos Claude 3.7+.

A API de Arquivos não é suportada no Amazon Bedrock ou Google Vertex AI.

Como a API de Arquivos funciona

A API de Arquivos fornece uma abordagem simples de carregar uma vez, usar muitas vezes para trabalhar com arquivos:

Carregue arquivos no armazenamento seguro da Anthropic e receba um file_id único
Baixe arquivos que são criados a partir de skills ou da ferramenta de execução de código
Referencie arquivos em solicitações de Mensagens usando o file_id em vez de fazer upload novamente do conteúdo
Gerencie seus arquivos com operações de listagem, recuperação e exclusão

Como usar a API de Arquivos

Para usar a API de Arquivos, você precisará incluir o cabeçalho de recurso beta: anthropic-beta: files-api-2025-04-14.

Carregando um arquivo

Carregue um arquivo para ser referenciado em futuras chamadas de API:

A resposta do carregamento de um arquivo incluirá:

Output

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

Uma vez carregado, referencie o arquivo usando seu file_id:

Tipos de arquivo e blocos de conteúdo

A API de Arquivos suporta diferentes tipos de arquivo que correspondem a diferentes tipos de blocos de conteúdo:

Tipo de Arquivo	Tipo MIME	Tipo de Bloco de Conteúdo	Caso de Uso
PDF	`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 imagem, tarefas visuais

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

Para arquivos .docx contendo imagens, converta-os para formato PDF primeiro, depois use suporte a PDF para aproveitar a análise de imagem integrada. Isso permite usar citações do documento PDF.

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 de seus arquivos carregados:

Obter metadados do arquivo

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

Excluir um arquivo

Remova um arquivo de seu workspace:

Baixando um arquivo

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

Você só pode baixar arquivos que foram criados por skills ou pela ferramenta de execução de código. Arquivos que você carregou não podem ser baixados.

Armazenamento de arquivo 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 estão no escopo do 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 de Mensagens e usos de ferramentas associados
Os arquivos que os usuários excluem serão excluídos de acordo com a política de retenção de dados da Anthropic.

Retenção de dados

Os arquivos carregados via API de Arquivos 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 solicitações de API.

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

Tratamento de erros

Erros comuns ao usar a API de Arquivos 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 janela de contexto (por exemplo, usar um arquivo de texto simples de 500 MB em uma solicitaçã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)
O arquivo excede o limite de 500 MB

Output

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

Uso e faturamento

As operações da API de Arquivo são gratuitas:

Carregamento de arquivos
Download de arquivos
Listagem de arquivos
Obtenção de metadados de arquivo
Exclusão de arquivos

O conteúdo do arquivo usado em solicitações de 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 solicitações por minuto
Entre em contato conosco se você precisar de limites mais altos para seu caso de uso

response = client.beta.messages.create(
    model="claude-opus-4-6",
    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)

import pandas as pd
# ...
# Example: Reading a CSV file
df = pd.read_csv("data.csv")
csv_content = df.to_string()

# Send as plain text in the message
response = client.messages.create(
    model="claude-opus-4-7",
    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)