Explicación de tu primera solicitud
Una explicación línea por línea de una llamada a Messages: qué hace cada campo y qué se devuelve.
La guía de inicio rápido te permite obtener una respuesta. Esta página explica qué significa cada parte, para que puedas escribir por tu cuenta la siguiente solicitud.
La solicitud
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 | Obligatorio | Qué hace |
|---|---|---|
model | sí | Qué modelo ejecutar. Debe coincidir con un identificador de /v1/models exactamente. |
max_tokens | sí | Límite máximo de salida. El modelo se detiene aquí, incluso a mitad de una frase. Es un control de costes, no un objetivo. |
messages | sí | La conversación hasta el momento, empezando por lo más antiguo. Cada entrada tiene un role (user o assistant) y content. |
system | no | Instrucciones que se aplican a toda la conversación. Es un campo de nivel superior, no un mensaje con role: system. |
temperature | no | 0–1. Los valores más bajos producen resultados más deterministas. Déjalo sin configurar salvo que tengas un motivo. |
stream | no | true devuelve eventos enviados por el servidor en lugar de un único cuerpo JSON. Consulta Transmisión en tiempo real. |
La respuesta
{
"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}
}contentes un array, no una cadena. El texto se encuentra encontent[0].text. Tratarlo como una cadena es el error más común en los clientes.stop_reasonte indica por qué terminó la generación:end_turn(finalizada),max_tokens(se alcanzó tu límite: la respuesta está truncada),stop_sequence, otool_use.usagees lo que se usa para calcular tu factura. Regístralo; es la única base fiable para atribuir los costes.
Si
stop_reason es max_tokens, tu respuesta se ha truncado. Aumenta max_tokens o pide una respuesta más corta; no vuelvas a intentarlo a ciegas, ya que también pagas por la salida truncada.Conversaciones de varios turnos
La API no mantiene estado. Para continuar una conversación, debes reenviar todo el historial, incluidas las respuestas anteriores del 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 el historial se reenvía en cada turno, los tokens de entrada aumentan con la conversación, al igual que la factura. Por eso las sesiones largas con agentes resultan caras. Caché de prompts y gestión del contexto ambos abordan este problema directamente.