Chat completions

La API Chat Completions de OpenAI, para todos los modelos de texto: la misma petición y la misma respuesta, el mismo streaming, los mismos SDK.

Petición

Respuesta

{
  "id": "chatcmpl-AbC123...",
  "object": "chat.completion",
  "created": 1790870400,
  "model": "claude-opus-5-5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Here's the summary..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1204,
    "completion_tokens": 312,
    "total_tokens": 1516,
    "prompt_tokens_details": { "cached_tokens": 1024 },
    "completion_tokens_details": { "reasoning_tokens": 128 }
  }
}

• model es el modelo que respondió. Es el que pediste, salvo que el enrutamiento inteligente haya respondido con una alternativa.
• Los modelos de razonamiento pueden añadir reasoning_content al mensaje: el razonamiento del modelo, cuando lo comparte.
• usage es lo que se te factura. cached_tokens son tokens de entrada leídos de la caché de prompts del modelo, facturados al precio de caché donde el modelo lo tenga.

Todas las respuestas incluyen además estas cabeceras:

Streaming

Con stream: true, la respuesta llega como server-sent events en el formato de fragmentos de OpenAI, terminando con data: [DONE]. Todos los SDK los leen por ti.

import os
from openai import OpenAI
client = OpenAI(
    base_url="https://api.zurelay.com/v1",
    api_key=os.environ["ZURELAY_API_KEY"],
)
stream = client.chat.completions.create(
    model="claude-sonnet-5-5",
    messages=[
      {
        "role": "user",
        "content": "Write a limerick about databases."
      }
    ],
    stream=True,
    stream_options={
      "include_usage": True
    },
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

• No se envía ninguna respuesta hasta que el modelo ha producido su primer token, así que un reintento o un cambio a otra ruta pasa inadvertido para ti.
• Los tramos de silencio (un modelo razonando entre pasos) se rellenan con líneas de comentario SSE (: keep-alive) cada 15 segundos. Los clientes las ignoran; evitan que los proxies cierren la conexión. Si el primer token tarda más de 20 segundos (un prompt largo, o una ruta que se bloqueó y está siendo reemplazada), el stream se abre entonces: las cabeceras y los comentarios de keep-alive llegan mientras esperas. Cada ruta tiene hasta 3 minutos para arrancar (5 con un nivel de razonamiento alto) antes de probar la siguiente, así que configura el timeout de tu cliente a 10 minutos.
• Un stream que se abrió antes de su primer token solo incluye x-zurelay-model cuando ningún otro modelo puede responderla (enrutamiento inteligente desactivado), y un error posterior a su apertura llega como un evento de error en el stream (con la misma forma que el cuerpo del error) en lugar de un estado de error.
• Con include_usage, el último fragmento antes de [DONE] tiene una lista choices vacía y el usage.

Llamadas a herramientas

Describe funciones en tools; cuando el modelo quiere una, responde con tool_calls en lugar de texto. Ejecuta la función, envía el resultado de vuelta como mensaje tool con el ID de la llamada, y el modelo continúa.

import os
from openai import OpenAI
client = OpenAI(
    base_url="https://api.zurelay.com/v1",
    api_key=os.environ["ZURELAY_API_KEY"],
)
response = client.chat.completions.create(
    model="gpt-6-sol",
    messages=[
      {
        "role": "user",
        "content": "What's the weather in Lisbon right now?"
      }
    ],
    tools=[
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Current weather for a city",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {
                "type": "string"
              }
            },
            "required": [
              "city"
            ]
          }
        }
      }
    ],
)
print(response.choices[0].message.content)

Salida estructurada

Pide JSON con response_format. Un json_schema obliga a los modelos que lo admiten a seguir tu esquema; json_object pide cualquier JSON válido (indícalo también en tu prompt).

import os
from openai import OpenAI
client = OpenAI(
    base_url="https://api.zurelay.com/v1",
    api_key=os.environ["ZURELAY_API_KEY"],
)
response = client.chat.completions.create(
    model="gpt-6.1-sol",
    messages=[
      {
        "role": "user",
        "content": "Extract the people: 'Ana met Ben and Chloe in Porto.'"
      }
    ],
    response_format={
      "type": "json_schema",
      "json_schema": {
        "name": "people",
        "schema": {
          "type": "object",
          "properties": {
            "names": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "required": [
            "names"
          ]
        }
      }
    },
)
print(response.choices[0].message.content)

Razonamiento

Los modelos de razonamiento piensan antes de responder. Configura reasoning_effort para cambiar velocidad y coste por profundidad: un nivel más alto piensa más tiempo, tarda más y usa más tokens de salida. Cada modelo acepta los niveles que documenta su laboratorio, desde none (sin pensar) pasando por minimal, low, medium, high y xhigh (extra alto) hasta max; la tabla de abajo los enumera. Si lo omites, el modelo usa su nivel por defecto. Funciona igual con cualquier OpenAI SDK, y puedes probar cada nivel en el Playground del panel.

from openai import OpenAI
client = OpenAI(base_url="https://api.zurelay.com/v1", api_key="YOUR_ZURELAY_KEY")
response = client.chat.completions.create(
    model="zurelay-auto",
    reasoning_effort="high",
    messages=[{"role": "user", "content": "How many primes are there below 1,000?"}],
)
message = response.choices[0].message
print(getattr(message, "reasoning_content", None))  # the thinking, when the model shares it
print(message.content)

El razonamiento vuelve junto con la respuesta en message.reasoning_content (al hacer streaming, en delta.reasoning_content) en los modelos que lo comparten; algunos llaman al campo reasoning. Se factura como tokens de salida y siempre forma parte de completion_tokens; completion_tokens_details.reasoning_tokens lo cuenta aparte cuando el modelo lo informa. Con un esfuerzo alto, una respuesta puede tardar minutos en empezar, así que dale a tu cliente un timeout generoso (consulta Fiabilidad y timeouts).

Niveles de cada modelo

Según la documentación de cada laboratorio. Si un modelo no acepta un nivel, se ejecuta en el más cercano que sí acepta (si hay dos igual de cercanos, el inferior; y el razonamiento solo se desactiva cuando envías none), así que una misma petición funciona en todos los modelos, incluido el enrutado inteligente. La cabecera de respuesta x-zurelay-reasoning-effort indica qué nivel se ejecutó. Una palabra que no sea un nivel se rechaza con un 400 que enumera los niveles del modelo.

El razonamiento de Claude

A través de este endpoint, Claude acepta reasoning_effort como cualquier otro modelo: low, medium, high, xhigh o max (Opus 4.6 no tiene xhigh). En el formato propio de Anthropic, Claude razona de forma adaptativa según un nivel: envía thinking: { type: "adaptive", display: "summarized" } con output_config: { effort: "xhigh" } y lee los bloques de razonamiento. Consulta Anthropic Messages.