Inicio / La API de Claude para quienes construyen

La petición, una única puerta de entrada

Toda interacción con Claude pasa por un único punto de entrada HTTP, la petición POST /v1/messages, que recibe un array de turnos y siempre devuelve la misma estructura de respuesta.

La API de Claude cuenta con una única puerta de entrada: la petición POST /v1/messages, llamada la API Messages. Cada intercambio, ya se resuelva en un solo turno o encadene una conversación larga, pasa por ese mismo punto de entrada, con un cuerpo que lleva un array messages y un modelo elegido. Basta un cliente HTTP corriente: ninguna otra ruta que memorizar, sea cual sea el modelo consultado o la naturaleza de la petición.

Un campo obligatorio, sin valor por defecto

El cuerpo de la petición lleva un campo llamado exactamente max_tokens, que fija el número máximo de tokens que el modelo puede generar antes de detenerse. Este campo no tiene valor por defecto: es obligatorio en cada petición, al mismo título que el modelo y el array messages. Este campo también condiciona el coste y la duración de la generación, sin por ello imponerla: el modelo puede perfectamente detenerse antes de alcanzar ese límite, en cuanto considera su respuesta terminada. Existe un caso particular: enviar max_tokens a 0 no solicita ninguna generación, solo el prerrellenado de la caché de prompt de cara a una petición siguiente.

// Corps minimal d'une requête à l'API Messages
{
  "model": "claude-sonnet-5",
  "max_tokens": 300,
  "messages": [
    { "role": "user", "content": "Résume ce texte en une phrase." }
  ]
}

Una respuesta siempre estructurada de la misma manera

La respuesta devuelta por la API sigue siempre la misma forma, sea cual sea el modelo consultado. El campo content lleva un array de bloques, el campo model confirma el modelo realmente utilizado, y el campo stop_reason indica por qué se detuvo la generación: end_turn para una respuesta terminada de forma natural, max_tokens para un corte por el límite fijado, stop_sequence para una secuencia de parada encontrada, y según el contexto de la petición, tool_use, refusal, pause_turn o model_context_window_exceeded. Cuando una secuencia de parada ha provocado el corte, se repite en el campo stop_sequence.

El campo usage cierra la respuesta con cuatro contadores: input_tokens, output_tokens, cache_creation_input_tokens y cache_read_input_tokens. Estos cuatro números bastan para calcular el coste exacto de un intercambio sin consultar ninguna otra fuente, y aparecen en cada petición, incluso la más simple. Leer input_tokens antes de enviar el turno siguiente también permite saber cuánto margen queda disponible en la conversación en curso.

Esta misma estructura de respuesta reaparece en la declaración de una herramienta, donde el campo stop_reason toma el valor tool_use para señalar una solicitud de uso en lugar de una respuesta terminada.