Documentação da API Anthropic Messages: Endpoints, Requisições, Visão e Backends de Agentes

A API Anthropic Messages é a principal interface HTTP para enviar prompts ao Claude. O endpoint principal é POST /v1/messages: você fornece um modelo, uma lista de blocos de conteúdo de mensagens tipadas e um limite de tokens, e recebe uma mensagem de assistente contendo um ou mais blocos de saída.

Este guia transforma a documentação da API Anthropic em uma lista de verificação de implementação. Aborda o contrato da requisição, estado de múltiplas trocas, streaming, visão, a API de Arquivos, uso de ferramentas e as escolhas envolvidas quando um backend de agente precisa suportar provedores de modelo nativos da Anthropic e compatíveis com OpenAI.

Endpoint da API Messages e Cabeçalhos Exigidos

A API Messages nativa da Anthropic usa este endpoint:

POST https://api.anthropic.com/v1/messages

Requisições HTTP diretas normalmente incluem estes cabeçalhos:

Cabeçalho	Propósito
x-api-key	Autentica a conta Anthropic
anthropic-version	Seleciona o contrato de versão da API documentado
content-type: application/json	Declara um corpo de requisição JSON

O cabeçalho de versão da API não é uma versão de modelo. Ele controla o comportamento da API HTTP, enquanto o campo model seleciona o modelo Claude usado para inferência. Mantenha ambos os valores na configuração, em vez de espalhá-los pelo código da aplicação.

A Estrutura da Requisição e Resposta

Uma requisição básica contém três campos:

{
  "model": "YOUR_CLAUDE_MODEL_ID",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Explique chaves de idempotência em dois parágrafos."
    }
  ]
}

A resposta é uma mensagem de assistente em vez de uma string simples. Sua propriedade content é um array de blocos tipados, então o código de produção deve inspecionar o type de cada bloco antes de ler seus campos.

{
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Uma chave de idempotência..."
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 18,
    "output_tokens": 126
  }
}

Este design baseado em blocos é importante quando você adiciona imagens ou ferramentas. Uma única troca do assistente pode conter texto e uma solicitação de ferramenta, e uma troca do usuário pode conter texto junto com blocos de imagem ou documento.

Uma Requisição curl Mínima

Armazene as credenciais em uma variável de ambiente e use um ID de modelo atualmente disponível para sua conta Anthropic:

export ANTHROPIC_API_KEY="sua-chave-api"
export ANTHROPIC_MODEL="seu-id-modelo-claude"

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --data '{
    "model": "'"$ANTHROPIC_MODEL"'",
    "max_tokens": 512,
    "messages": [
      {
        "role": "user",
        "content": "Retorne três maneiras práticas de reduzir a latência de API."
      }
    ]
  }'

Não codifique um nome de modelo copiado de um tutorial antigo. A disponibilidade e os aliases dos modelos podem mudar, então a configuração de implantação deve usar um ID de modelo verificado na documentação ou console atual do provedor.

Uso em Python com o SDK Anthropic

O SDK oficial Python lida com cabeçalhos de autenticação e converte a resposta em objetos tipados:

import os

from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

message = client.messages.create(
    model=os.environ["ANTHROPIC_MODEL"],
    max_tokens=512,
    messages=[
        {
            "role": "user",
            "content": "Escreva uma função Python que valide uma string UUID.",
        }
    ],
)

for block in message.content:
    if block.type == "text":
        print(block.text)

Iterar sobre os blocos de conteúdo é mais seguro do que assumir que message.content[0] é sempre texto. Aplicações de agente podem receber blocos de uso de ferramenta, e recursos multimodais podem adicionar outros tipos de bloco à conversa.

Conversas de Múltiplas Trocas e Prompts de Sistema

A API Messages é sem estado. Sua aplicação envia o histórico de conversa relevante novamente a cada requisição:

{
  "model": "YOUR_CLAUDE_MODEL_ID",
  "max_tokens": 512,
  "system": "Você é um assistente de documentação de API conciso.",
  "messages": [
    {"role": "user", "content": "O que significa HTTP 429?"},
    {"role": "assistant", "content": "Indica limitação de taxa."},
    {"role": "user", "content": "Como meu cliente deve tentar novamente?"}
  ]
}

A Anthropic coloca a instrução de sistema no campo de nível superior system em vez de em uma mensagem com role: "system". Essa é uma das diferenças importantes a serem consideradas ao traduzir requisições de esquemas compatíveis com OpenAI.

Para sessões longas, não reenvie uma transcrição ilimitada. Mantenha as trocas mais recentes, preserve decisões e resultados de ferramentas que ainda afetam a tarefa, e resuma o contexto mais antigo antes que o prompt se aproxime do limite de contexto do modelo selecionado.

Respostas em Streaming

Defina stream: true quando a interface deve exibir a saída incrementalmente:

import os

from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

with client.messages.stream(
    model=os.environ["ANTHROPIC_MODEL"],
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Explique o pool de conexões de banco de dados."}
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

O streaming melhora a latência percebida, mas adiciona trabalho de gerenciamento de estado. Sua aplicação deve lidar com uma conexão que fecha cedo, texto parcial, ordenação de eventos e metadados de uso finais. Para agentes que usam ferramentas, armazene em buffer o bloco completo de entrada da ferramenta antes de analisá-lo ou executá-lo.

Requisições da API Claude Vision

A API Claude Vision usa o mesmo endpoint de Messages. Adicione um bloco de conteúdo de imagem antes da pergunta de texto relacionada. As imagens podem ser fornecidas como dados base64 suportados ou através de um tipo de fonte permitido descrito na documentação de visão atual.

import base64
import os

from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

with open("architecture.png", "rb") as image_file:
    image_data = base64.b64encode(image_file.read()).decode("utf-8")

message = client.messages.create(
    model=os.environ["ANTHROPIC_VISION_MODEL"],
    max_tokens=700,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image_data,
                    },
                },
                {
                    "type": "text",
                    "text": "Identifique dois riscos de confiabilidade neste diagrama de arquitetura.",
                },
            ],
        }
    ],
)

Redimensione imagens muito grandes antes de enviá-las. Imagens grandes aumentam o tempo de transferência e o uso de tokens sem necessariamente melhorar a resposta. Valide também o tipo MIME; declarar dados JPEG como PNG é uma causa comum de requisições rejeitadas.

Uso da API de Arquivos Anthropic

A API de Arquivos Anthropic é útil quando um arquivo deve ser enviado uma vez e referenciado por chamadas posteriores da API Messages em vez de ser codificado e transmitido repetidamente. A disponibilidade exata, tipos de arquivo suportados e campos de requisição podem diferir dependendo do status do recurso, então verifique a documentação atual da API de Arquivos antes de confiar nela em produção.

Uma integração típica tem dois estágios:

1. Faça upload do arquivo e persista o identificador de arquivo retornado com o registro de documento da sua aplicação.
2. Referencie esse identificador em um bloco de conteúdo suportado ao criar uma mensagem.

Trate IDs de arquivos como recursos específicos do provedor. Registre qual provedor e conta criaram cada ID, aplique seus próprios controles de acesso e defina uma política de exclusão. Um identificador de arquivo não deve ser aceito diretamente de um usuário não confiável sem verificações de autorização.

Para imagens pequenas e ocasionais, base64 é simples. Para documentos usados em muitas requisições, um recurso de arquivo do provedor pode reduzir uploads repetidos. Se sua aplicação precisar funcionar em vários provedores, mantenha o objeto original em seu próprio armazenamento e crie IDs de arquivo específicos do provedor como um cache.

Uso de Ferramentas para Backends de Agentes

Ferramentas permitem que Claude solicite uma função definida pela aplicação. Seu backend descreve cada ferramenta com um nome, um propósito e um contrato de entrada JSON Schema. O modelo pode então retornar um bloco tool_use em vez de fingir que executou a operação.

{
  "name": "get_order_status",
  "description": "Consultar o status atual de um pedido de cliente.",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "O identificador do pedido mostrado ao cliente."
      }
    },
    "required": ["order_id"]
  }
}

O loop de execução seguro é:

1. Envie mensagens e definições de ferramentas para o modelo.
2. Detecte um bloco de conteúdo tool_use.
3. Valide sua entrada contra o esquema e suas regras de autorização.
4. Execute a ferramenta em um ambiente controlado.
5. Retorne um bloco tool_result correspondente na próxima troca do usuário.
6. Continue até que o modelo produza uma resposta normal ou atinja seu limite de loop.

Nunca execute argumentos de ferramentas como shell, SQL ou caminhos de arquivo confiáveis. Para agentes de codificação, execute comandos gerados dentro de um ambiente isolado, como o Novita Agent Sandbox, com limites explícitos de tempo, rede, sistema de arquivos e recursos.

Requisições Nativas Anthropic vs. Compatíveis com OpenAI

APIs nativas Anthropic e compatíveis com OpenAI resolvem o mesmo problema geral, mas seus formatos de transmissão não são idênticos.

Aspecto	API Anthropic Messages	API de chat compatível com OpenAI
Endpoint comum	/v1/messages	/v1/chat/completions
Instrução de sistema	Campo system de nível superior	Comumente uma mensagem system ou developer
Representação da saída	Blocos de conteúdo tipados	Comumente choices[].message
Solicitação de ferramenta	Bloco tool_use	Comumente tool_calls
Resultado de ferramenta	Bloco de conteúdo tool_result	Comumente uma mensagem de papel tool

Um endpoint compatível com OpenAI é valioso quando sua aplicação já usa o SDK OpenAI ou precisa alternar entre modelos de código aberto com mudanças mínimas de transporte. Novita AI expõe uma API LLM compatível com OpenAI, então a mesma estrutura de cliente pode atingir vários modelos disponíveis alterando a URL base e a configuração do modelo.

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NOVITA_API_KEY"],
    base_url="https://api.novita.ai/v3/openai",
)

response = client.chat.completions.create(
    model=os.environ["NOVITA_MODEL"],
    messages=[
        {
            "role": "user",
            "content": "Revise esta estratégia de repetição para modos de falha.",
        }
    ],
)

print(response.choices[0].message.content)

Isso não é uma tradução direta de todos os recursos da Anthropic. Se sua aplicação depende de blocos de conteúdo específicos da Anthropic, semântica de ferramentas, citações ou recursos beta, mantenha um adaptador nativo Anthropic. Use o caminho compartilhado compatível com OpenAI para cargas de trabalho que se encaixam em seu modelo de requisição comum.

Construindo um Backend de Agente Neutro em Relação ao Provedor

Um backend neutro em relação ao provedor deve normalizar os conceitos da aplicação sem fingir que todos os provedores são idênticos. Um design prático tem quatro camadas:

1. Modelo de conversa: armazene papéis, texto, imagens, chamadas de ferramenta e resultados de ferramentas em um esquema interno.
2. Adaptador de provedor: traduza o esquema interno para payloads da Anthropic Messages ou compatíveis com OpenAI.
3. Registro de capacidade: monitore se o modelo selecionado suporta visão, ferramentas, saída estruturada ou outro comportamento necessário.
4. Camada de execução: execute ferramentas e código separadamente do provedor de inferência.

Essa separação permite que uma equipe use Claude onde o comportamento nativo da Anthropic é importante, enquanto roteia cargas de trabalho compatíveis para um modelo de código aberto através da Novita AI. O caminho de código aberto pode ser útil para controle de custos, experimentação de modelos, requisitos de localização de dados ou para evitar dependência de um único provedor. Teste a qualidade da saída e a confiabilidade das ferramentas em suas próprias tarefas, em vez de assumir que dois modelos são intercambiáveis porque ambos aceitam mensagens de chat.

Para cargas de trabalho de agente, a camada de execução merece atenção igual. A troca de modelo não protege sua infraestrutura de comandos inseguros. Use um sandbox isolado, imponha listas de permissões de ferramentas, limite iterações e registre cada decisão do modelo e resultado de ferramenta com segredos removidos.

Erros Comuns e Depuração

400 Bad Request

Verifique a forma do JSON, tipos de bloco de conteúdo, campos obrigatórios e se o modelo selecionado suporta o recurso solicitado. Registre o ID da requisição do provedor e o corpo do erro estruturado, mas remova credenciais e dados de arquivo base64.

401 Erro de Autenticação

Confirme se a chave da API está presente no ambiente de execução e pertence ao provedor pretendido. A Anthropic usa x-api-key para requisições HTTP diretas; um cliente compatível com OpenAI geralmente envia um token de portador automaticamente.

404 Modelo ou Recurso Não Encontrado

Verifique o ID do modelo na documentação ou console atual do provedor. Para recursos da API de Arquivos, verifique também se o arquivo pertence à mesma conta e ambiente usados pela requisição.

429 Limitação de Taxa

Tente novamente com backoff exponencial e jitter, mas limite o número de tentativas. Coloque o trabalho em segundo plano na fila, limite a concorrência por provedor e evite tentar novamente imediatamente toda requisição com falha no mesmo intervalo.

Erros de Limite de Contexto ou Token

Reduza o histórico da conversa, tamanho da imagem, conteúdo do arquivo ou comprimento da saída solicitada. Conte toda a requisição, incluindo instruções de sistema, esquemas de ferramentas, resultados de ferramentas anteriores e conteúdo multimodal.

Artigos Recomendados

• O Que São Agentes de Codificação? Arquitetura, Ferramentas e Loops de Execução
• O Que é MCP? Um Guia do Desenvolvedor para o Protocolo de Contexto de Modelo
• Guia de LLM de Código Aberto 2026: Modelos, Trade-offs e Implantação

Lista de Verificação de Implementação

• Mantenha chaves de API, IDs de modelo, URLs base e versões de API na configuração de tempo de execução.
• Analise blocos de conteúdo tipados em vez de assumir uma única string de texto.
• Armazene estado de conversa suficiente para reconstruir cada requisição sem estado.
• Valide entradas de ferramentas e execute-as fora do processo do modelo.
• Adicione timeouts, limites de repetição, IDs de requisição e observabilidade com dados removidos.
• Condicione o roteamento do provedor pela capacidade do modelo, não apenas pelo preço ou nome.
• Verifique novamente IDs de modelo, status de recursos, limites e preços antes da implantação.

A API Messages é direta na camada HTTP. O trabalho de engenharia mais difícil aparece quando uma aplicação adiciona streaming, entrada multimodal, ferramentas, arquivos persistentes ou múltiplos provedores de modelo. Mantenha essas preocupações atrás de adaptadores explícitos, e seu backend de agente pode evoluir sem amarrar a lógica de negócios a um formato de requisição.

FAQ

Qual é o endpoint da API Anthropic Messages?

O endpoint nativo é POST https://api.anthropic.com/v1/messages. Requisições exigem autenticação, um cabeçalho de versão da API Anthropic, um ID de modelo, um limite de tokens e um array de mensagens.

A API Anthropic Messages é compatível com OpenAI?

Não. Os conceitos se sobrepõem, mas prompts de sistema, blocos de conteúdo, objetos de resposta e mensagens de uso de ferramentas diferem. Use um adaptador de provedor se uma aplicação precisar suportar ambos os formatos.

A API Claude Vision usa um endpoint separado?

Não. Requisições de visão usam a API Messages com blocos de conteúdo de imagem e texto. O modelo Claude selecionado deve suportar entrada de imagem.

Quando devo usar a API de Arquivos Anthropic?

Use-a quando arquivos suportados precisarem ser referenciados entre requisições e uploads base64 repetidos seriam desperdiçadores. Mantenha seu próprio arquivo de origem e registro de autorização, pois IDs de arquivo do provedor são recursos específicos da conta.

O Claude Code pode usar um backend de API personalizado?

A integração do Claude Code depende da autenticação e configuração do provedor suportadas pela versão atual do Claude Code. Não assuma que um endpoint compatível com OpenAI implementa a API Messages da Anthropic. Para um agente personalizado, um adaptador neutro em relação ao provedor geralmente é mais claro do que tentar fazer protocolos diferentes parecerem idênticos.

Quando devo escolher um modelo de código aberto através da Novita AI?

Considere isso quando você quiser alternância de modelo compatível com OpenAI, experimentação de modelo aberto ou um segundo provedor para cargas de trabalho compatíveis. Mantenha requisições nativas Anthropic para recursos que exigem comportamento específico da API Claude, e avalie ambos os caminhos em seus próprios prompts e ferramentas.