Guía de API compatible con OpenAI: del endpoint local de Ollama a modelos de frontera alojados

"Compatible con OpenAI" significa que una API utiliza el mismo formato de comunicación que /v1/chat/completions de OpenAI, por lo que cualquier SDK o herramienta de OpenAI funciona cambiando únicamente base_url. Ollama ofrece un endpoint compatible con OpenAI para modelos que se ejecutan localmente en su máquina. Kunavo ofrece uno para modelos frontier alojados —Claude, GPT y modelos de imagen, vídeo y audio— detrás de un único token bearer. Esta guía muestra el patrón y cómo pasar de uno a otro sin reescribir el código.

Qué significa «compatible con OpenAI»

El formato Chat Completions de OpenAI se convirtió en el estándar de facto: entra un array messages, sale un choices[].message, Server-Sent Events para el streaming y tools para las llamadas a funciones. Cualquier endpoint que respete ese contrato es «compatible con OpenAI», y los SDK oficiales openai (Python, Node y todos los ports de la comunidad) apuntan a él configurando base_url.

El patrón de Ollama (local)

Ollama ejecuta modelos abiertos localmente y los sirve en http://localhost:11434/v1:

from openai import OpenAI

# Ollama exposes an OpenAI-compatible endpoint on localhost
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

resp = client.chat.completions.create(
    model="llama3.1",
    messages=[{"role": "user", "content": "Summarize this changelog."}],
)
print(resp.choices[0].message.content)

El mismo código, modelos frontier alojados (Kunavo)

Apunte el mismo SDK a Kunavo y elija un modelo frontier. Solo cambian base_url, api_key y model; la llamada es idéntica byte por byte:

import os
from openai import OpenAI

# Same SDK, same call shape — only base_url, api_key and model change
client = OpenAI(
    base_url="https://api.kunavo.com/v1",
    api_key=os.environ["KUNAVO_API_KEY"],
)

resp = client.chat.completions.create(
    model="claude-sonnet-5",  # or claude-haiku-4-5, gpt-5-5, gpt-5-6-terra...
    messages=[{"role": "user", "content": "Summarize this changelog."}],
)
print(resp.choices[0].message.content)

Obtenga una clave en /app/keys; el inicio rápido incluye ejemplos para Node y curl.

Local frente a alojado: cuándo usar cada uno

Una configuración habitual: Ollama en localhost para desarrollo sin conexión y Kunavo para calidad alojada en producción; una variable de entorno permite alternarlos. Para consultar el contrato campo por campo que implementan ambos extremos —parámetros, deltas de streaming, tool_calls, el objeto usage y la tabla de paridad con la superficie v1 de Ollama— consulte la referencia de /v1/chat/completions y su sección de compatibilidad de Ollama con OpenAI.

Descubrir modelos en tiempo de ejecución

Al igual que /api/tags de Ollama, Kunavo expone un catálogo con formato OpenAI. Resuelva los slugs en tiempo de ejecución en vez de codificarlos:

# Discover every enabled model (OpenAI-shaped, like Ollama's /api/tags)
curl https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer $KUNAVO_API_KEY"

Más allá del chat

La misma clave llega a los endpoints de imagen (/v1/images/generations), vídeo (/v1/video/generations) y audio, todos con formato OpenAI. Consulte la guía de IA multimodal y la comparación con OpenRouter para saber en qué se diferencia Kunavo de otras puertas de enlace.

Una superficie va más allá de la definición habitual de «compatible» y conviene conocerla: POST /v1/responses. Codex CLI acepta un proveedor personalizado únicamente mediante la Responses API, por lo que la mayoría de las puertas de enlace compatibles con OpenAI no pueden controlarlo; cuánto cuesta Codex por token muestra cómo hacerlo mediante un bloque de configuración que funciona. Para calcular el precio de un flujo GPT incluyendo la entrada en caché, la calculadora de precios de la API de OpenAI utiliza sus propios recuentos de tokens.

Preguntas frecuentes