Sua primeira solicitação explicada
Uma explicação linha por linha de uma chamada à Messages — o que cada campo faz e o que é retornado.
O guia de início rápido permite obter uma resposta. Esta página explica o significado de cada parte dela, para que você escreva a próxima solicitação por conta própria.
A solicitação
curl https://aiprimetech.io/v1/messages \
-H "x-api-key: $CLAUDEAPIKEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "Hello"}]
}'| Campo | Obrigatório | O que faz |
|---|---|---|
model | sim | Qual modelo executar. Deve corresponder a um ID de /v1/models exatamente. |
max_tokens | sim | Limite máximo para a saída. O modelo para nesse ponto, mesmo no meio de uma frase. É um controle de custos, não uma meta. |
messages | sim | A conversa até agora, da mensagem mais antiga para a mais recente. Cada entrada tem um role (user ou assistant) e content. |
system | não | Instruções que se aplicam à conversa inteira. Um campo de nível superior, não uma mensagem com role: system. |
temperature | não | 0–1. Valores menores tornam a geração mais determinística. Deixe sem definir, a menos que tenha um motivo. |
stream | não | true retorna eventos enviados pelo servidor em vez de um único corpo JSON. Consulte Transmissão. |
A resposta
{
"id": "msg_01ABC...",
"type": "message",
"role": "assistant",
"model": "claude-sonnet-4-6",
"content": [{"type": "text", "text": "Hello! How can I help?"}],
"stop_reason": "end_turn",
"usage": {"input_tokens": 9, "output_tokens": 12}
}contenté um array, não uma string. O texto fica emcontent[0].text. Tratá-lo como uma string é o erro mais comum no cliente.stop_reasoninforma por que a geração terminou:end_turn(concluída),max_tokens(atingiu o limite definido — a resposta está truncada),stop_sequence, outool_use.usageé a base da cobrança. Registre esse valor; ele é a única base confiável para atribuir custos.
Se
stop_reason é max_tokens, sua resposta foi cortada. Aumente max_tokens ou peça uma resposta mais curta — não repita a solicitação às cegas, pois você também paga pela saída truncada.Conversas com múltiplos turnos
A API não mantém estado. Para continuar uma conversa, você reenvia todo o histórico, incluindo as respostas anteriores do modelo:
{
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "What is the capital of France?"},
{"role": "assistant", "content": "Paris."},
{"role": "user", "content": "And its population?"}
]
}Como o histórico é reenviado a cada turno, os tokens de entrada aumentam com a conversa, assim como a cobrança. É por isso que sessões longas de agentes ficam caras. Cache de prompts e gerenciamento de contexto ambos tratam disso diretamente.