Skip to main content
POST
Use POST /v1/messages para enviar solicitudes a Claude en el formato Anthropic Messages. Los ejemplos configuran el SDK oficial de Anthropic con la URL base de CometAPI y leen su clave de API de $COMETAPI_KEY.
Para ver definiciones de campos y opciones específicas del modelo, consulte la referencia de la API Messages. Para solicitudes compatibles con OpenAI, consulte Chat Completions.
Autentíquese con x-api-key o Authorization: Bearer. El SDK de Anthropic usa x-api-key. Los ejemplos HTTP incluyen anthropic-version: 2023-06-01.

Inicio rápido

Los siguientes ejemplos solicitan tres consultas de búsqueda. Configure $COMETAPI_KEY antes de ejecutarlos. Instale anthropic para Python o @anthropic-ai/sdk para JavaScript:
La respuesta contiene un array content. Lea los bloques cuyo type sea text; pueden aparecer bloques de pensamiento y herramientas antes del texto.

Controla el pensamiento adaptativo

Establece thinking.type en adaptive y elige un valor para output_config.effort. El siguiente ejemplo usa xhigh y lee el mensaje completado de una transmisión:
El pensamiento contribuye al límite de salida de max_tokens. Deja espacio para la respuesta final, además del pensamiento. Una respuesta puede contener texto sin un bloque de pensamiento visible. Conserva sin cambios los bloques de pensamiento devueltos en el historial de la conversación . Para conocer la configuración de pensamiento específica del modelo, consulta Pensamiento. Los ejemplos omiten temperature, top_p y top_k; consulta la documentación de parámetros del modelo seleccionado antes de agregar controles de muestreo.

Almacena Prompts en caché

Coloca un punto de interrupción de caché en el material de referencia que reutilizas entre solicitudes. Guarda el material de referencia en un archivo reference.txt con codificación UTF-8 antes de ejecutar este ejemplo. Usa un prefijo que cumpla con la longitud mínima apta para caché:
Vuelve a ejecutar la solicitud con el mismo modelo, texto de referencia y configuración de pensamiento. Inspecciona los contadores de uso para determinar si la solicitud reutilizó un prefijo:
  • cache_creation_input_tokens cuenta los tokens escritos en la caché.
  • cache_read_input_tokens cuenta los tokens leídos de la caché.
  • input_tokens cuenta la entrada procesada fuera de esos contadores de caché.
En solicitudes repetidas, cache_read_input_tokens informa cuántos tokens de entrada se leyeron de la caché. El ejemplo OpenAPI Prompt Cache contiene una referencia ficticia completa que puedes guardar como reference.txt para probar el ejemplo.

Transmitir respuestas

Establece stream: true para Server-Sent Events. El SDK expone fragmentos de texto a medida que llegan:
Un flujo de mensajes contiene message_start, eventos de bloques de contenido, message_delta, y message_stop. Los bloques de contenido pueden contener texto, razonamiento o actividad de herramientas. Para un bloque de texto, content_block_delta contiene un text_delta. Lee el uso final y el motivo de detención de message_delta.

Control del esfuerzo

Establece output_config.effort para orientar la cantidad de razonamiento. Este ejemplo usa low para una explicación breve y espera a que se complete el mensaje transmitido:
Usa la referencia oficial de esfuerzo para elegir un nivel de esfuerzo. Establece max_tokens por separado para limitar la longitud de salida.

Usar herramientas de servidor

Las herramientas del servidor se ejecutan durante la solicitud a la API y devuelven bloques de resultados junto con la respuesta de Claude.
Recupere un artículo y pida a Claude que use el documento recuperado en su respuesta. Este ejemplo transmite la respuesta y examina tanto el texto final como el web_fetch_tool_result bloque:
La respuesta combina un bloque server_tool_use con un web_fetch_tool_result que contiene el documento recuperado o un error de herramienta.

Devolver resultados de herramientas de cliente

Para una herramienta de cliente, Claude devuelve un bloque tool_use. Ejecuta la función de tu aplicación y envía su resultado en un bloque tool_result con el tool_use_id correspondiente. Conserva el contenido completo del asistente entre las dos solicitudes. Este ejemplo proporciona un resultado de pedido ficticio y le pide a Claude que use ese resultado:

Ejemplo de respuesta

Una solicitud sin Streaming devuelve un objeto de mensaje. El siguiente ejemplo muestra sus campos de texto y uso con un identificador de mensaje ilustrativo:
El motivo de detención describe la siguiente acción. end_turn completa la respuesta, max_tokens significa que la salida alcanzó el límite y tool_use solicita el resultado de una herramienta de cliente. Para un turno de herramienta de servidor que devuelve pause_turn, continúa con el contenido devuelto del asistente sin cambios.

Autorizaciones

x-api-key
string
header
requerido

Your CometAPI key passed via the x-api-key header. Authorization: Bearer $COMETAPI_KEY is also supported.

Encabezados

anthropic-version
string
predeterminado:2023-06-01

The Anthropic API version to use. Defaults to 2023-06-01.

Ejemplo:

"2023-06-01"

anthropic-beta
string

Comma-separated feature identifiers required by a specific beta API feature. Omit this header for the examples on this page.

Cuerpo

application/json
model
string
predeterminado:claude-opus-5
requerido

The Claude model to use. See the Models page for available Claude model IDs.

Ejemplo:

"claude-opus-5"

messages
object[]
requerido

Conversation history. Use user and assistant messages with text strings or content-block arrays. Return complete assistant content blocks when continuing a tool call.

max_tokens
integer
requerido

The maximum number of tokens to generate. The model may stop before reaching this limit. When using thinking, the thinking tokens count towards this limit.

Rango requerido: x >= 1
Ejemplo:

1024

system

System prompt providing context and instructions to Claude. Can be a plain string or an array of content blocks (useful for prompt caching).

temperature
number

Sampling temperature. The examples omit sampling overrides.

Rango requerido: 0 <= x <= 1
top_p
number

Nucleus sampling threshold. The examples omit sampling overrides.

Rango requerido: 0 <= x <= 1
top_k
integer

Limits sampling to the k most likely tokens. The examples omit sampling overrides.

Rango requerido: x >= 0
stream
boolean
predeterminado:false

If true, stream the response incrementally using Server-Sent Events (SSE). Events include message_start, content_block_start, content_block_delta, content_block_stop, message_delta, and message_stop.

stop_sequences
string[]

Custom strings that cause the model to stop generating when encountered. The stop sequence is not included in the response.

thinking
object

Thinking configuration. The adaptive example uses type adaptive and sets output_config.effort separately.

tools
object[]

Client tools define a name and input_schema. Server tools use a versioned type and name, such as the web_fetch and web_search examples on this page.

tool_choice
object

Controls how the model uses tools.

metadata
object

Request metadata for tracking and analytics.

output_config
object

Configuration for reasoning effort and structured output.

service_tier
enum<string>

The service tier to use. auto tries priority capacity first, standard_only uses only standard capacity.

Opciones disponibles:
auto,
standard_only

Respuesta

Successful response. When stream is true, the response is a stream of SSE events.

id
string

Message identifier returned by the API.

type
enum<string>

Always message.

Opciones disponibles:
message
role
enum<string>

Always assistant.

Opciones disponibles:
assistant
content
object[]

The response content blocks. May include text, thinking, tool_use, and other block types.

model
string

Model ID reported by the response.

stop_reason
enum<string>

Why the model stopped generating. refusal can be returned as a successful HTTP response when the model declines a request.

Opciones disponibles:
end_turn,
max_tokens,
stop_sequence,
tool_use,
pause_turn,
refusal
stop_sequence
string | null

The stop sequence that caused the model to stop, if applicable.

usage
object

Token usage statistics.

Última modificación el 8 de septiembre de 2026