Skip to main content
Anthropic Claude é um sistema de diálogo AI muito poderoso, capaz de gerar respostas fluentes e naturais em questão de segundos, apenas com a entrada de um prompt. A API Claude Messages é o formato nativo oficial da Anthropic, que, ao contrário do formato compatível da OpenAI (Chat Completion), adota uma estrutura de solicitação e resposta própria da Anthropic, permitindo melhor aproveitamento das capacidades únicas do Claude, como entrada de conteúdo multimodal, chamadas de ferramentas, pensamento profundo (Extended Thinking) e outros recursos avançados. Este documento descreve principalmente o fluxo de uso da API Claude Messages, permitindo que utilizemos uma interface nativa consistente com a oficial da Anthropic para acessar as funcionalidades de diálogo do Claude.

Fluxo de Solicitação

Para usar a API Claude Messages, primeiro acesse o Painel de Controle Ace Data Cloud para obter seu Token de API, que deve ser guardado para uso futuro. Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, onde será convidado a se registrar e logar; após a conclusão, você será retornado automaticamente à página atual. Um Token de API é suficiente para acessar todos os serviços da plataforma, não sendo necessário solicitar um para cada serviço individualmente. A primeira solicitação oferece um crédito gratuito para que você possa experimentar; quando o crédito estiver baixo, você pode recarregar o saldo geral no painel de controle.
📘 Documentação Completa: Claude Messages API →

Uso Básico

O caminho de solicitação da API Claude Messages é /v1/messages, mantendo a consistência com a API oficial da Anthropic. Precisamos fornecer pelo menos três parâmetros obrigatórios:
  • model: escolha o modelo Claude a ser utilizado. O mais recente é claude-fable-5-1 (contexto de 1 milhão de tokens, saída máxima de 128K tokens); o modelo original claude-fable-5 ainda é compatível e mantido.
  • messages: array de mensagens de entrada, onde cada mensagem contém role (papel) e content (conteúdo), sendo que role suporta user e assistant.
  • max_tokens: número máximo de tokens de saída, usado para limitar o comprimento da resposta única.
Parâmetros opcionais comuns:
  • system: prompt do sistema, usado para definir o comportamento e o papel do modelo.
  • temperature: aleatoriedade da geração, entre 0-1, quanto maior o valor, mais dispersa a resposta.
  • stream: se deve usar resposta em fluxo, definindo como true para obter um efeito de retorno palavra por palavra.
  • stop_sequences: sequência de parada personalizada, o modelo interrompe a geração ao encontrar esses textos.
  • top_p: parâmetro de amostragem nuclear, que, em conjunto com a temperatura, controla a aleatoriedade da geração.
  • top_k: amostra apenas entre as K opções com maior probabilidade.
  • tools: definição de ferramentas, para permitir que o modelo chame funções externas.
  • tool_choice: controla como o modelo utiliza as ferramentas fornecidas.
  • cache_control: cria automaticamente um ponto de cache no último bloco de conteúdo que pode ser armazenado em cache; também pode ser escrito em blocos de conteúdo específicos.

Exemplo cURL

Exemplo Python

Após a chamada, o resultado retornado é o seguinte:
Descrição dos campos do resultado retornado:
  • id: identificador único da mensagem atual.
  • type: sempre será message.
  • role: sempre será assistant.
  • content: array de conteúdo da resposta, onde cada elemento contém type (como text) e o conteúdo correspondente.
  • model: nome do modelo que processou a solicitação.
  • stop_reason: razão da parada. Valores estáveis incluem end_turn, max_tokens, stop_sequence, tool_use, pause_turn (pode retornar o conteúdo atual do assistant para continuar), refusal e model_context_window_exceeded.
  • stop_sequence: se a parada ocorreu devido a uma sequência de parada personalizada, exibe o texto correspondente da sequência de parada.
  • stop_details: quando stop_reason é refusal, pode incluir a categoria e a descrição da recusa.
  • usage: estatísticas de uso de tokens. input_tokens é a entrada não armazenada em cache; cache_creation_input_tokens e cache_read_input_tokens são, respectivamente, a gravação e leitura de cache; output_tokens é o número de tokens de saída. A taxa oficial de leitura de cache para Fable 5.1 é de 0.25/milha~odetokens,comtaxasdegravac\ca~odecachede5minutose1horade0.25/milhão de tokens, com taxas de gravação de cache de 5 minutos e 1 hora de 12.50 e $20/milhão de tokens, respectivamente; os preços reais da plataforma são calculados com base nos descontos do pacote. Respostas não em fluxo também podem incluir o cost registrado pela Ace Data Cloud.

Prompt do Sistema

A API Claude Messages suporta a definição de prompts do sistema através do campo system, que é usado para definir o comportamento, papel e contexto do modelo.

Exemplo Python

Ao definir o prompt system, é possível controlar com precisão o papel e o comportamento do Claude.

Resposta em Fluxo

Esta interface também suporta resposta em fluxo, definindo o parâmetro stream como true para obter um efeito de retorno gradual, ideal para exibição palavra por palavra em uma página da web.

Exemplo Python

A resposta em fluxo é retornada no formato de Eventos Enviados pelo Servidor (SSE), com cada linha prefixada por event: e data:. Os tipos de eventos em fluxo incluem:
  • message_start: início da mensagem, contendo informações básicas da mensagem e o nome do modelo.
  • content_block_start: início do bloco de conteúdo.
  • content_block_delta: atualização incremental do bloco de conteúdo, contendo novos trechos de texto gerados.
  • content_block_stop: fim do bloco de conteúdo.
  • message_delta: atualização incremental em nível de mensagem, contendo informações de stop_reason e usage final.
  • message_stop: fim da mensagem.
O efeito da saída é o seguinte:
Pode-se ver que o evento content_block_delta na resposta em fluxo contém o conteúdo do texto gerado passo a passo, e ao concatenar todos os text_delta, é possível obter a resposta completa.

Exemplo em JavaScript

Diálogo em várias rodadas

Se você deseja integrar a funcionalidade de diálogo em várias rodadas, deve alternar as mensagens dos papéis user e assistant no array messages, incluindo o histórico de conversas anteriores.

Exemplo em Python

O resultado retornado é o seguinte:
Ao passar o histórico completo de conversas em messages, Claude pode fornecer respostas precisas com base no contexto.

Modelo de Pensamento Profundo

O pensamento de Claude e o resumo do pensamento são dois conceitos diferentes: o modelo pode realizar raciocínios internos, mas a API não retornará a cadeia de pensamento original. Quando é necessário mostrar o processo de raciocínio, a API retorna um resumo processado. O modelo atual recomenda o uso de pensamento adaptativo e controla o esforço geral de raciocínio através de output_config.effort:
O bloco de pensamento na resposta é semelhante a:
  • display: "summarized" retorna um resumo de pensamento legível; não é a cadeia de pensamento original.
  • display: "omitted" retorna thinking: "", mas ainda mantém a signature opaca para suportar diálogos subsequentes.
  • Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 e Opus 4.7 têm o valor padrão de display como omitted; Opus 4.6, Sonnet 4.6 e modelos anteriores que suportam pensamento têm o valor padrão como summarized.
  • O display afeta apenas o conteúdo retornado e a latência do fluxo, não desativa o raciocínio nem reduz a contagem de tokens de pensamento.
  • Se o pensamento é ativado por padrão e o valor padrão do display são duas questões independentes. Opus 5 e Sonnet 5 ativam o pensamento adaptativo por padrão; Opus 4.8, 4.7 e 4.6 precisam ser ativados explicitamente.
  • budget_tokens é usado apenas para modelos antigos que ainda suportam orçamento fixo de pensamento. Novos modelos devem usar thinking.type=adaptive e output_config.effort; o pensamento de Fable 5.1 está sempre ativado e não pode ser desativado explicitamente.
  • Durante diálogos em várias rodadas e chamadas de ferramentas, o bloco completo de pensamento e a signature retornados pelo assistente devem ser enviados de volta sem modificações; não altere ou gere a signature por conta própria.
  • Alguns roteadores parcialmente compatíveis não conseguem processar redacted_thinking sem perda ou desativar explicitamente o pensamento, e nesse caso, retornará um erro de parâmetro, sem descartar silenciosamente ou alterar o significado da solicitação.
Em solicitações em fluxo, summarized gerará thinking_delta; omitted não gerará thinking_delta, apenas manterá o ciclo de vida do bloco de pensamento e signature_delta.

Modelo Visual

Claude suporta entrada multimodal, podendo processar texto e imagem simultaneamente. Na API Messages, é possível utilizar a capacidade visual definindo content como um formato de array e passando blocos de conteúdo de imagem.

Usando Imagem Codificada em Base64

Usando Imagem por URL

Exemplo cURL

Os formatos de imagem suportados incluem: image/jpeg, image/png, image/gif, image/webp.

Documentos e PDF

PDF usa blocos de conteúdo document, suportando fontes estáveis em Base64 e URL. A fonte Base64 deve usar application/pdf:
A fonte URL é escrita como {"type":"url","url":"https://example.com/report.pdf"}. O document também suporta text/plain e fontes de content compostas por blocos de texto/imagem; campos opcionais incluem title, context e citations. A fonte file_id da API Files é uma funcionalidade beta independente, não incluída no contrato estável desta interface.

Cache de Dicas

O cache_control de nível superior automaticamente coloca o ponto de interrupção de cache no último bloco que pode ser armazenado em cache:
Quando é necessário controlar a posição com precisão, o mesmo cache_control pode ser escrito nos blocos de conteúdo text, image, document, tool_use, tool_result ou na definição de ferramentas. O ttl suporta 5m (padrão) e 1h; verifique usage.cache_creation_input_tokens e usage.cache_read_input_tokens para determinar a gravação e a correspondência do cache. Exemplo de resultado retornado:

Chamada de Ferramentas (Tool Use)

A API Messages do Claude suporta nativamente a funcionalidade de chamada de ferramentas, permitindo que o modelo chame suas ferramentas/funções predefinidas quando necessário.

Exemplo em Python

Quando o modelo decide chamar uma ferramenta, o content do resultado retornado incluirá um bloco de conteúdo do tipo tool_use:
Note que o stop_reason é tool_use, indicando que o modelo precisa chamar uma ferramenta. Após receber esse resultado, você deve executar a função da ferramenta e retornar o resultado na forma de tool_result.
模型会基于工具返回的结果,生成最终的自然语言回复。

Diferença em relação à API de Conclusão de Chat

Ace Data Cloud oferece simultaneamente dois formatos de API Claude, cujas principais diferenças são as seguintes: O usage.input_tokens da API Messages representa apenas a entrada não armazenada em cache, cache_read_input_tokens e cache_creation_input_tokens são contadores de cobrança independentes; os três serão calculados separadamente de acordo com os preços correspondentes. Se o seu sistema já estiver integrado à API no formato OpenAI, você pode usar a API de Conclusão de Chat para uma transição suave. Se você precisar usar todas as capacidades nativas do Claude, recomenda-se usar a API Messages.

Tratamento de Erros

As respostas de erro da interface pública usam o envelope da plataforma Ace Data Cloud: error.code é o código de erro estável, error.message é a descrição, trace_id é usado para rastrear a solicitação. Os estados HTTP comuns incluem:
  • 400: Parâmetros de solicitação ou conteúdo do protocolo inválidos.
  • 401: Token de autorização inválido, ausente ou expirado.
  • 403: Acesso proibido, saldo insuficiente ou cota limitada.
  • 404: API ou modelo inexistente.
  • 413: Corpo da solicitação muito grande.
  • 429: Muitas solicitações.
  • 500 / 503 / 504: Erro de serviço, temporariamente indisponível ou tempo de processamento excedido.

Exemplo de Resposta de Erro

Essa estrutura de erro é o contrato de tempo de execução da Ace Data Cloud, não se igualando ao envelope de erro oficial da Anthropic; trate conforme o estado HTTP e error.code.

Conclusão

Através deste documento, você já entende como usar a API Messages do Claude no formato nativo da Anthropic para chamar as funcionalidades de conversa do Claude. A API Messages suporta uma variedade de recursos, como conversas básicas, prompts do sistema, respostas em fluxo, diálogos de múltiplas rodadas, pensamento profundo, compreensão visual, PDF, cache de prompts e chamadas de ferramentas. Se tiver alguma dúvida, entre em contato com nossa equipe de suporte técnico.