completados de chat

Endpoint: POST /v1/chat/completions. Los formatos de solicitud y respuesta coinciden exactamente con la API Chat Completions de OpenAI, incluidos el streaming y los campos opcionales tool_calls / reasoning_tokens.

Llamada básica

resp = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[
        {"role": "system", "content": "You are a senior staff engineer."},
        {"role": "user", "content": "Pros and cons of postgres LISTEN/NOTIFY for a job queue?"},
    ],
    max_tokens=800,
)
print(resp.choices[0].message.content)

Parámetros

Se aceptan todos los parámetros estándar de OpenAI. Algunos solo son pertinentes para ciertos proveedores: el traductor transmite los que admite cada proveedor upstream.

Streaming

Establece stream=True. Kunavo emite eventos enviados por el servidor en el formato exacto de OpenAI: cada fragmento es un chat.completion.chunk con choices[0].delta.content. La carga útil final de uso llega con data: [DONE].

stream = client.chat.completions.create(
    model="claude-haiku-4-5",
    messages=[{"role": "user", "content": "Explain B-trees in one paragraph."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Llamadas a herramientas y funciones

Las llamadas a herramientas funcionan con todos los proveedores. Define las herramientas como esquemas JSON; el modelo devuelve tool_calls en su mensaje; las ejecutas y devuelves los resultados en mensajes role: "tool".

tools = [{
    "type": "function",
    "function": {
        "name": "get_current_weather",
        "description": "Get current weather for a city",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string"},
                "unit": {"type": "string", "enum": ["c", "f"]},
            },
            "required": ["city"],
        },
    },
}]

resp = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
    tools=tools,
    tool_choice="auto",
)

# Inspect tool calls the model wants to make
for call in resp.choices[0].message.tool_calls or []:
    print(call.function.name, call.function.arguments)

Salida JSON (response_format)

response_format solicita una respuesta en JSON. Lo que garantiza depende de la familia del modelo, porque la solicitud de cada familia se traduce a un mecanismo distinto del proveedor upstream:

import json

resp = client.chat.completions.create(
    model="claude-haiku-4-5",
    messages=[{"role": "user", "content": "Jane Doe <jane@example.com> wants the Pro plan."}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "signup",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "email": {"type": "string"},
                    "plan": {"type": "string", "enum": ["free", "pro", "enterprise"]},
                },
                "required": ["name", "email", "plan"],
                "additionalProperties": False,
            },
        },
    },
)
signup = json.loads(resp.choices[0].message.content)  # constrained to the schema

Cuatro aspectos que debes conocer sobre Claude:

• El esquema se envía a Anthropic casi tal como lo escribiste. Anthropic exige additionalProperties: false en los objetos, por lo que Kunavo lo añade a cualquier objeto que enumere sus propiedades y lo deja sin definir, como hace Pydantic con model_json_schema(). Anthropic sigue rechazando lo siguiente con un error 400 que identifica el problema: un objeto abierto (additionalProperties definido con cualquier valor distinto de false, o sin propiedades enumeradas y con additionalProperties sin definir) y oneOf; usa anyOf. La página de salida estructurada de Anthropic enumera los demás casos.
• Se ignoran strict y name: Anthropic aplica todos los esquemas que acepta, tanto si son estrictos como si no.
• No se puede combinar un esquema con un mensaje final assistant (un prefill); Anthropic responde con un error 400.
• Si max_tokens se agota a mitad de un objeto, el JSON queda truncado y finish_reason es "length".

Entrada visual y multimodal

Los modelos con la capacidad vision aceptan bloques de contenido de imagen. Usa una URL HTTPS o una URI base64 data:.

# Pass an image URL or a base64 data URI as part of a multimodal message
resp = client.chat.completions.create(
    model="claude-haiku-4-5",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What's in this image?"},
            {"type": "image_url", "image_url": {
                "url": "https://example.com/cat.jpg"
            }},
        ],
    }],
)
print(resp.choices[0].message.content)

Los modelos con capacidad de visión del catálogo incluyen Claude Opus 5.5; consulta la lista de modelos para ver los demás.

Para una imagen HTTPS, Kunavo descarga el archivo y se lo entrega al modelo en línea, porque algunos proveedores upstream ignoran una URL de imagen sin procesar. Límites: 16 imágenes por solicitud, 5 MB por imagen, 20 MB en total y 10 segundos por descarga. Si no se puede obtener una imagen, se devuelve un error que la identifica en lugar de omitirla.

Razonamiento

El efecto de un control de razonamiento en este endpoint depende de la familia, porque la solicitud de cada familia se traduce a una API distinta del proveedor upstream:

# GPT models: reasoning_effort is forwarded as the Responses API's
# reasoning.effort. Reasoning tokens are part of completion_tokens.
resp = client.chat.completions.create(
    model="gpt-6-sol",
    messages=[{"role": "user", "content": "Plan a 3-week MLOps migration."}],
    reasoning_effort="high",
)
details = resp.usage.completion_tokens_details   # absent when no reasoning ran
print(details.reasoning_tokens if details else 0)

caché de prompts

Un prompt de sistema extenso, un documento de referencia o un bloque de ejemplos: cualquier prefijo estable puede almacenarse en caché en el proveedor y reutilizarse en llamadas posteriores por una fracción del precio de entrada. Los aciertos de caché aparecen en el objeto de uso como prompt_tokens_details.cached_tokens.

Los modelos GPT almacenan en caché automáticamente; no hace falta modificar la solicitud. cached_tokens es un subconjunto de prompt_tokens y se factura a una tarifa reducida de lectura de caché.

Claude solo almacena en caché hasta un punto de interrupción cache_control, y en un prompt largo este endpoint establece los puntos de interrupción por ti: en el prompt de sistema, en las definiciones de herramientas y en el último mensaje en cuanto la conversación contiene un turno del asistente. Para elegir tú el prefijo, adjunta cache_control a un bloque de contenido, como se muestra abajo; Kunavo conserva tus puntos de interrupción y solo añade los suyos en las posiciones que dejaste vacías:

# Claude caches prefixes you mark with cache_control. Attach it to a content
# block; later calls reusing that prefix read it at ~10% of the input price.
resp = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": LONG_DOCUMENT,            # the stable, reused prefix
                "cache_control": {"type": "ephemeral"},
            },
            {"type": "text", "text": "Summarize the document above."},
        ],
    }],
)
print(resp.usage.prompt_tokens_details.cached_tokens)

Objeto de uso

Cada respuesta (y el fragmento final de la transmisión) incluye un objeto usage:

Compatibilidad de Ollama con OpenAI — /v1/chat/completions

Ollama ofrece sus modelos locales mediante una API compatible con OpenAI en http://localhost:11434/v1, que implementa el mismo contrato /chat/completions documentado en esta página. Así, ambas opciones son intercambiables desde el cliente: cualquier código escrito para la API v1 de Ollama funciona con la de Kunavo con solo cambiar la URL base y el modelo.

from openai import OpenAI

# Before — Ollama's OpenAI-compatible API, local models
client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama",                       # ignored locally
)
resp = client.chat.completions.create(
    model="llama3.2",
    messages=[{"role": "user", "content": "Summarize this changelog."}],
)

# After — the same call against hosted frontier models.
# Two lines changed. Everything below them is untouched.
client = OpenAI(
    base_url="https://api.kunavo.com/v1",   # <- was localhost:11434/v1
    api_key=os.environ["KUNAVO_API_KEY"],
)
resp = client.chat.completions.create(
    model="claude-sonnet-5",  # <- was llama3.2
    messages=[{"role": "user", "content": "Summarize this changelog."}],
)

Los elementos que suelen fallar al cambiar de proveedor aquí no fallan, porque el formato en la red es el mismo:

Próximos pasos

• API nativa Anthropic Messages
• Referencia de generación de imágenes
• Cómo funciona la facturación (precios por token, recargo)
• La API de Ollama compatible con OpenAI y cómo cambiar a modelos alojados
• Explorar todos los modelos de chat