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