Solicitação e Uso da API Claude Messages

Anthropic Claude é um sistema de diálogo AI muito poderoso, que pode 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 você pode acessar a página Claude Messages API e clicar no botão “Acquire” para obter as credenciais necessárias para a solicitação:

Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, convidando-o a se registrar e fazer login. Após o registro e login, você será redirecionado de volta para a página atual. Na primeira solicitação, haverá um crédito gratuito disponível, permitindo o uso gratuito dessa 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, como claude-opus-4-20250514, claude-sonnet-4-20250514, etc.
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, configurado como true para obter um efeito de retorno palavra por palavra.
stop_sequences: sequência de parada personalizada, o modelo parará de gerar 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 usa as ferramentas fornecidas.

Exemplo cURL

curl -X POST 'https://api.xhuoapi.ai/v1/v1/messages' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "Hello, Claude"
      }
    ]
  }'

Exemplo Python

import requests

url = "https://api.xhuoapi.ai/v1/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, Claude"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Após a chamada, o resultado retornado é o seguinte:

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hi! My name is Claude. How can I help you today?"
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 15
  }
}

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, os valores possíveis incluem end_turn (término normal), max_tokens (alcance do comprimento máximo), stop_sequence (encontro de sequência de parada), tool_use (chamada de ferramenta).
stop_sequence: se a parada foi devido a uma sequência de parada personalizada, exibe o texto correspondente da sequência de parada.
usage: estatísticas de uso de tokens, incluindo input_tokens (número de tokens de entrada) e output_tokens (número de tokens de saída).

Prompt do Sistema

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

Exemplo Python

import requests

url = "https://api.xhuoapi.ai/v1/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "system": "Você é um assistente de tradução profissional em chinês, por favor, traduza o inglês inserido pelo usuário para o chinês.",
    "messages": [
        {"role": "user", "content": "The quick brown fox jumps over the lazy dog."}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Ao definir o prompt system, é possível controlar com precisão o papel e o modo de atuação 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 passo a passo, ideal para exibição palavra por palavra em uma página da web.

Exemplo Python

import requests

url = "https://api.xhuoapi.ai/v1/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "stream": True,
    "messages": [
        {"role": "user", "content": "Hello, Claude"}
    ]
}

response = requests.post(url, json=payload, headers=headers, stream=True)
for line in response.iter_lines():
    if line:
        print(line.decode("utf-8"))

A resposta em fluxo retorna no formato de Server-Sent Events (SSE), onde cada linha é precedida 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 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 stop_reason e informações finais de usage.
message_stop: fim da mensagem.

O efeito de saída é o seguinte:

event: message_start
data: {"type":"message_start","message":{"id":"msg_01XFDUDYJgAACzvnptvVoYEL","type":"message","role":"assistant","content":[],"model":"claude-sonnet-4-20250514","stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":12,"output_tokens":0}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Oi"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"! Meu nome é"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" Claude. Como posso ajudá-lo hoje?"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"output_tokens":15}}

event: message_stop
data: {"type":"message_stop"}

Pode-se ver que a resposta em fluxo contém eventos content_block_delta que incluem o texto gerado passo a passo, e ao concatenar todos os text_delta, é possível obter a resposta completa.

Exemplo em JavaScript

const options = {
  method: "POST",
  headers: {
    accept: "application/json",
    authorization: "Bearer {token}",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    model: "claude-sonnet-4-20250514",
    max_tokens: 1024,
    stream: true,
    messages: [{ role: "user", content: "Olá, Claude" }],
  }),
};

const response = await fetch("https://api.xhuoapi.ai/v1/v1/messages", options);
const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(decoder.decode(value));
}

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

import requests

url = "https://api.xhuoapi.ai/v1/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Olá, meu nome é Alice."},
        {"role": "assistant", "content": "Olá Alice! Prazer em conhecê-la. Como posso ajudá-la hoje?"},
        {"role": "user", "content": "Qual é o meu nome?"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

O resultado retornado é o seguinte:

{
  "id": "msg_01Y1wfQmd89g968TVbFu57Yc",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Seu nome é Alice, como você acabou de me dizer!"
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 40,
    "output_tokens": 14
  }
}

Ao passar o histórico completo de conversas em messages, Claude pode fornecer respostas precisas com base no contexto.

Modelo de Pensamento Profundo

Claude suporta a funcionalidade de Pensamento Estendido, que permite que o modelo realize raciocínios internos antes de responder, aumentando a precisão no tratamento de questões complexas. Para usar essa funcionalidade, é necessário passar o parâmetro thinking.

Exemplo em Python

import requests

url = "https://api.xhuoapi.ai/v1/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 16000,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 10000
    },
    "messages": [
        {"role": "user", "content": "Qual é o seno de 30 graus? Mostre seu raciocínio."}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

O resultado retornado é o seguinte:

{
  "id": "msg_018J4YaRoGHtbsTVb4Vvz7oH",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "thinking",
      "thinking": "O usuário está perguntando sobre o seno de 30 graus. Esta é uma questão básica de trigonometria.\n\nEm um triângulo 30-60-90, os lados estão na proporção 1:√3:2.\n\nPara um ângulo de 30°:\n- O lado oposto é 1\n- A hipotenusa é 2\n- Portanto, sen(30°) = oposto/hipotenusa = 1/2 = 0.5"
    },
    {
      "type": "text",
      "text": "O seno de 30 graus é **1/2** ou **0.5**.\n\nEste é um dos valores trigonométricos fundamentais. Em um triângulo 30-60-90, os lados estão na proporção 1:√3:2, onde o lado oposto ao ângulo de 30° tem comprimento 1 e a hipotenusa tem comprimento 2, nos dando sen(30°) = 1/2."
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 28,
    "output_tokens": 239
  }
}

Pode-se ver que o array content contém dois blocos de conteúdo:

type: "thinking": o processo de pensamento interno do modelo, mostrando os passos de raciocínio.
type: "text": o resultado final da resposta.

Observações:

Ao usar thinking, max_tokens deve ser maior que budget_tokens, pois budget_tokens é o orçamento de tokens alocado para o processo de pensamento.
Quanto maior o budget_tokens, maior será o espaço para o modelo realizar um raciocínio mais profundo, adequado para lidar com questões complexas.

Modelo Visual

Claude suporta entrada multimodal, podendo processar texto e imagens simultaneamente. Na API de Mensagens, você pode usar a capacidade visual definindo content como um formato de array e incluindo blocos de conteúdo de imagem.

Usando Imagem Codificada em Base64

import base64
import requests

url = "https://api.xhuoapi.ai/v1/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

# Lendo e codificando a imagem
with open("image.png", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode("utf-8")

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image_data
                    }
                },
                {
                    "type": "text",
                    "text": "O que há nesta imagem?"
                }
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Usando Imagem por URL

# Exemplo de uso de imagem por URL

import requests

url = "https://api.xhuoapi.ai/v1/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://cdn.xhuoapi.ai/ueugot.png"
                    }
                },
                {
                    "type": "text",
                    "text": "O que há nesta imagem?"
                }
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Exemplo de cURL

curl -X POST 'https://api.xhuoapi.ai/v1/v1/messages' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {
              "type": "url",
              "url": "https://cdn.xhuoapi.ai/ueugot.png"
            }
          },
          {
            "type": "text",
            "text": "O que há nesta imagem?"
          }
        ]
      }
    ]
  }'

Formatos de imagem suportados incluem: image/jpeg, image/png, image/gif, image/webp. Exemplo de resultado retornado:

{
  "id": "msg_01NCrxpZmV17bhQJJRQEFEb9",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Esta imagem mostra uma interface de configuração de requisição de API para o que parece ser um serviço de conclusão de chat de IA. A interface inclui parâmetros para seleção de modelo, mensagens, modo de streaming e configurações de tokens máximos."
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1570,
    "output_tokens": 52
  }
}

Chamada de Ferramenta (Tool Use)

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

Exemplo em Python

import requests

url = "https://api.xhuoapi.ai/v1/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Obter o clima atual em uma determinada localização",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "A cidade e estado, por exemplo, San Francisco, CA"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "Como está o clima em San Francisco?"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Quando o modelo decide chamar uma ferramenta, o resultado retornado terá content contendo um bloco de conteúdo do tipo tool_use:

{
  "id": "msg_01Aq9w938a90dw8q",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Deixe-me verificar o clima em San Francisco para você."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lgs",
      "name": "get_weather",
      "input": {
        "location": "San Francisco, CA"
      }
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "tool_use",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 120,
    "output_tokens": 68
  }
}

Note que 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 para o modelo:

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Obter o clima atual em uma determinada localização",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "A cidade e estado, por exemplo, San Francisco, CA"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "Como está o clima em San Francisco?"},
        {
            "role": "assistant",
            "content": [
                {"type": "text", "text": "Deixe-me verificar o clima em San Francisco para você."},
                {"type": "tool_use", "id": "toolu_01A09q90qw90lq917835lgs", "name": "get_weather", "input": {"location": "San Francisco, CA"}}
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01A09q90qw90lq917835lgs",
                    "content": "Ensolarado, 22°C"
                }
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

O modelo gerará a resposta final em linguagem natural com base no resultado retornado pela ferramenta.

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

A XHuoAPI oferece dois formatos de API do Claude, e as principais diferenças são as seguintes:

Característica	API de Mensagens (`/v1/messages`)	API de Conclusão de Chat (`/v1/chat/completions`)
Formato	Formato nativo da Anthropic	Formato compatível com OpenAI
Prompt do sistema	Campo `system` independente	Passado através de `messages` com `role: "system"`
Estrutura de resposta	Array `content` (suporta vários tipos)	Array `choices` (contém `message`)
Formato de streaming	Eventos SSE (vários tipos de eventos)	Linhas SSE `data`
Pensamento profundo	Parâmetro `thinking` nativo	Acionado por nome de modelo especial (como sufixo `-thinking`)
Chamada de ferramentas	`tools` nativo + `input_schema`	Formato `functions` compatível com OpenAI
Estatísticas de Token	`input_tokens` / `output_tokens`	`prompt_tokens` / `completion_tokens`

Se o seu sistema já estiver integrado ao formato da API do 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 de Mensagens.

Tratamento de Erros

Ao chamar a API, se ocorrer um erro, a API retornará o código de erro e a mensagem correspondente. Por exemplo:

400 token_mismatched: Requisição inválida, possivelmente devido a parâmetros ausentes ou inválidos.
400 api_not_implemented: Requisição inválida, possivelmente devido a parâmetros ausentes ou inválidos.
401 invalid_token: Não autorizado, token de autorização inválido ou ausente.
429 too_many_requests: Muitas requisições, você excedeu o limite de taxa.
500 api_error: Erro interno do servidor, algo deu errado no servidor.

Exemplo de Resposta de Erro

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "falha na busca"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Conclusão

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

Documentation Index

​Fluxo de Solicitação

​Uso Básico

​Exemplo cURL

​Exemplo Python

​Prompt do Sistema

​Exemplo Python

​Resposta em Fluxo

​Exemplo Python

​Exemplo em JavaScript

​Diálogo em várias rodadas

​Exemplo em Python

​Modelo de Pensamento Profundo

​Exemplo em Python

​Modelo Visual

​Usando Imagem Codificada em Base64

​Usando Imagem por URL

​Exemplo de cURL

​Chamada de Ferramenta (Tool Use)

​Exemplo em Python

​Diferença em Relação à API de Conclusão de Chat

​Tratamento de Erros

​Exemplo de Resposta de Erro

​Conclusão

Fluxo de Solicitação

Uso Básico

Exemplo cURL

Exemplo Python

Prompt do Sistema

Exemplo Python

Resposta em Fluxo

Exemplo Python

Exemplo em JavaScript

Diálogo em várias rodadas

Exemplo em Python

Modelo de Pensamento Profundo

Exemplo em Python

Modelo Visual

Usando Imagem Codificada em Base64

Usando Imagem por URL

Exemplo de cURL

Chamada de Ferramenta (Tool Use)

Exemplo em Python

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

Tratamento de Erros

Exemplo de Resposta de Erro

Conclusão