/v1/chat/completions vs /v1/responses vs /v1/messages: ¿Qué endpoint de API de IA deberías usar?

/v1/chat/completions vs /v1/responses vs /v1/messages: ¿Qué endpoint de API de IA deberías usar?#

Un problema habitual en el soporte técnico de las pasarelas de API de IA no tiene que ver con la clave de API, el modelo ni el SDK. Tiene que ver con el endpoint.

Un usuario elige un modelo que existe, pero envía la solicitud al endpoint equivocado. El resultado puede ser:

• modelo no disponible;
• endpoint no compatible;
• cuerpo de solicitud no válido;
• las llamadas a herramientas no funcionan;
• incompatibilidad en el formato de streaming;
• el modelo Claude funciona en una herramienta, pero falla en otra.

Esta guía explica la diferencia entre tres familias de endpoints:

/v1/chat/completions
/v1/responses
/v1/messages

Versión breve:

Si tu cliente indica que es «compatible con OpenAI», empieza con:

https://crazyrouter.com/v1/chat/completions

o establece la URL base en:

https://crazyrouter.com/v1

y deja que el SDK añada /chat/completions.

Si tu herramienta requiere específicamente la API Responses de OpenAI, usa /v1/responses.

Si tu herramienta es nativa de Anthropic y espera la API Messages de Claude, usa /v1/messages.

El error más común#

El error más común es mezclar la familia del modelo con la familia del endpoint.

Por ejemplo, un modelo Claude puede ofrecerse a través de una pasarela compatible con OpenAI, pero eso no significa automáticamente que el cuerpo de tu solicitud deba usar el esquema nativo de /v1/messages de Anthropic.

Del mismo modo, si una herramienta envía solicitudes nativas de Anthropic a /v1/messages, no basta con cambiar el nombre del modelo para solucionar un fallo. El endpoint y el cuerpo de la solicitud deben corresponderse.

Piénsalo así:

model name + endpoint + request schema must match

Si uno de los tres es incorrecto, el modelo puede parecer no disponible aunque funcione correctamente.

Qué es /v1/chat/completions#

/v1/chat/completions es el endpoint de chat clásico compatible con OpenAI.

Una solicitud típica tiene este aspecto:

curl https://crazyrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $CRAZYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Explain API endpoints in one paragraph."}
    ]
  }'

Usa /v1/chat/completions cuando:

• la aplicación indique que admite una API compatible con OpenAI;
• la configuración solicite OPENAI_BASE_URL o base_url;
• el cuerpo de la solicitud use messages con role y content;
• uses el modo habitual de compatibilidad con el SDK de OpenAI;
• configures herramientas como clientes tipo Cursor, enrutadores tipo LiteLLM, aplicaciones tipo FastGPT o muchas interfaces de chat.

Para muchos usuarios, este es el endpoint predeterminado más seguro.

Qué es /v1/responses#

/v1/responses es el endpoint de la API Responses de OpenAI, más reciente.

Está diseñado en torno a un objeto de respuesta más general y puede representar elementos como:

• salida de texto;
• llamadas a herramientas;
• entrada multimodal;
• elementos de razonamiento;
• salida estructurada;
• flujos de trabajo de tipo agente.

Una solicitud simplificada tiene este aspecto:

curl https://crazyrouter.com/v1/responses \
  -H "Authorization: Bearer $CRAZYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": "Explain the difference between chat completions and responses."
  }'

Usa /v1/responses cuando:

• la herramienta indique explícitamente que usa la API Responses de OpenAI;
• la configuración mencione responses en lugar de chat.completions;
• el cuerpo de la solicitud use input en lugar de messages;
• la ruta del modelo/proveedor admita el comportamiento de la API Responses;
• necesites los formatos más recientes de OpenAI para la salida de herramientas o de razonamiento.

No envíes un cuerpo de Chat Completions a /v1/responses a menos que la pasarela documente explícitamente esa conversión.

Qué es /v1/messages#

/v1/messages es el endpoint que sigue el formato de la API Messages de Anthropic.

Una solicitud típica en el formato nativo de Claude tiene este aspecto:

curl https://crazyrouter.com/v1/messages \
  -H "Authorization: Bearer $CRAZYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "system": "You are a helpful assistant.",
    "messages": [
      {"role": "user", "content": "Explain Claude Messages API."}
    ]
  }'

Usa /v1/messages cuando:

• el cliente sea nativo de Anthropic;
• el SDK espere el formato de la API Messages de Claude;
• la solicitud tenga system en el nivel superior en lugar de un mensaje de sistema dentro del array;
• la solicitud requiera bloques de contenido o un esquema de herramientas específicos de Anthropic;
• la documentación indique explícitamente que se debe llamar a /v1/messages.

No des por hecho que todos los modelos Claude deben invocarse con /v1/messages. Si usas una pasarela o un SDK compatibles con OpenAI, es posible que las llamadas a los modelos Claude se hagan a través de /v1/chat/completions.

Por qué los errores de endpoint hacen que los modelos parezcan no disponibles#

Cuando un modelo falla, los usuarios suelen asumir que está caído. Pero, en muchos casos, el modelo funciona bien y lo que está mal es el formato de la solicitud.

Ejemplos habituales de incompatibilidad:

URL base vs endpoint completo#

Muchas herramientas solicitan una URL base, no un endpoint completo.

URL base correcta:

https://crazyrouter.com/v1

Después, el SDK llama a:

https://crazyrouter.com/v1/chat/completions

URL base incorrecta para la mayoría de los SDK:

https://crazyrouter.com/v1/chat/completions

¿Por qué? Porque el SDK puede volver a añadir /chat/completions.

Regla:

• Si el campo se llama base_url, usa /v1.
• Si el campo se llama endpoint y solicita una URL completa, usa la ruta completa que requiera la herramienta.

¿Qué endpoint debería elegir?#

Usa este árbol de decisión:

1. ¿Tu herramienta indica «API compatible con OpenAI»?
   Usa /v1/chat/completions o la URL base https://crazyrouter.com/v1.

2. ¿Tu herramienta indica específicamente «API Responses»?
   Usa /v1/responses.

3. ¿Tu herramienta usa el SDK de Anthropic o la API Messages de Claude?
   Usa /v1/messages.

4. ¿Tienes dudas?
   Empieza con /v1/chat/completions, porque la mayoría de los clientes de terceros lo admiten.

Configuración recomendada de Crazyrouter#

Para la mayoría de las herramientas compatibles con OpenAI:

API Key: your Crazyrouter API key
Base URL: https://crazyrouter.com/v1
Model: choose a model from the Crazyrouter model list

Para usuarios en regiones donde la ruta global es inestable:

Base URL: https://cn.crazyrouter.com/v1

Los enlaces destinados a personas pueden usar seguimiento UTM:

https://crazyrouter.com/models?utm_source=blog&utm_medium=article&utm_campaign=api_endpoints

Los endpoints de API no deben hacerlo:

https://api-endpoint.example.invalid/v1?utm_source=blog

Lista rápida de comprobaciones para depurar#

Antes de informar de que un «modelo no está disponible», comprueba estos cinco puntos:

1. ¿El nombre del modelo está escrito exactamente como aparece en la lista de modelos?
2. ¿La familia del endpoint es correcta: chat completions, responses o messages?
3. ¿El cuerpo de la solicitud coincide con el esquema de ese endpoint?
4. ¿La URL base termina exactamente en /v1, sin omitirlo ni duplicar las rutas del endpoint?
5. ¿Usas el modo correcto del SDK: compatible con OpenAI o nativo de Anthropic?

Recomendación final#

Si desarrollas integraciones generales para aplicaciones, empieza con /v1/chat/completions. Es la opción con mayor compatibilidad.

Usa /v1/responses cuando tu cliente o flujo de trabajo requiera explícitamente la API Responses.

Usa /v1/messages cuando trabajes con herramientas nativas de Anthropic.

La mayoría de los problemas con los endpoints desaparecen si recuerdas esta regla:

OpenAI-compatible client → /v1/chat/completions
OpenAI Responses client → /v1/responses
Anthropic-native client → /v1/messages

Si el modelo existe, pero aparece como no disponible, no te limites a cambiar su nombre. Comprueba primero el endpoint y el esquema de la solicitud.