A API de Arquivos permite fazer upload e gerenciar arquivos para usar com a API da Anthropic sem precisar reenviar 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 reenviar continuamente documentos e imagens usados com frequência em várias chamadas de API.

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

​
Modelos suportados

Referenciar um file_id em uma solicitação de Mensagens é suportado em todos os modelos que suportam o tipo de arquivo específico. 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 3.5 Haiku mais todos os modelos Claude 3.7+.

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

​
Como funciona a API de Arquivos

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

  • Fazer upload de arquivos para nosso armazenamento seguro e receber um file_id único
  • Baixar arquivos que são criados pela ferramenta de execução de código
  • Referenciar arquivos em solicitações de Mensagens usando o file_id em vez de reenviar conteúdo
  • Gerenciar seus arquivos com operações de listar, recuperar e excluir

​
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.

​
Fazendo upload de um arquivo

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

curl -X POST https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -F "file=@/path/to/document.pdf"

​
Usando um arquivo em mensagens

Uma vez enviado, referencie o arquivo usando seu file_id:

curl -X POST https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Por favor, resuma este documento para mim."          
          },
          {
            "type": "document",
            "source": {
              "type": "file",
              "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
            }
          }
        ]
      }
    ]
  }'

​
Tipos de arquivo e blocos de conteúdo

A API de Arquivos 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 imagem, tarefas visuais
Conjuntos de dados, outrosVariacontainer_uploadAnalisar dados, criar visualizações

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

# Exemplo: Lendo um arquivo de texto e enviando como texto simples
# Nota: Para arquivos com caracteres especiais, considere codificação base64
TEXT_CONTENT=$(cat document.txt | jq -Rs .)

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d @- <<EOF
{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Aqui está o conteúdo do documento:\n\n${TEXT_CONTENT}\n\nPor favor, resuma este documento."
        }
      ]
    }
  ]
}
EOF

Para arquivos .docx contendo imagens, converta-os primeiro para formato PDF, depois use o 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": "Título do Documento", // Opcional
  "context": "Contexto sobre o documento", // Opcional  
  "citations": {"enabled": true} // Opcional, habilita citações
}

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

curl https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

​
Obter metadados do arquivo

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

curl https://api.anthropic.com/v1/files/file_011CNha8iCJcU1wXNR6q4V8w \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

​
Excluir um arquivo

Remova um arquivo do seu espaço de trabalho:

curl -X DELETE https://api.anthropic.com/v1/files/file_011CNha8iCJcU1wXNR6q4V8w \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

​
Baixando um arquivo

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

curl -X GET "https://api.anthropic.com/v1/files/file_011CNha8iCJcU1wXNR6q4V8w/content" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  --output downloaded_file.txt

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

​
Armazenamento e limites de arquivos

​
Limites de armazenamento

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

​
Ciclo de vida do arquivo

  • Os arquivos são limitados ao espaço de trabalho da chave API. Outras chaves API podem usar arquivos criados por qualquer outra chave API associada ao mesmo espaço de trabalho
  • Os arquivos persistem até você excluí-los
  • 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

​
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)
  • 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 100 GB
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Arquivo não encontrado: file_011CNha8iCJcU1wXNR6q4V8w"
  }
}

​
Uso e cobrança

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

  • Upload de arquivos
  • Download de arquivos
  • Listagem de arquivos
  • Obtenção de metadados de arquivos
  • Exclusão de arquivos

O conteúdo de arquivos usado em solicitações Messages é cobrado como tokens de entrada. Você só pode baixar arquivos criados pela ferramenta de execução de código.

​
Limites de taxa

Durante o período beta:

  • 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