Ollama como API compatible con OpenAI

Endpoints bajo /v1/

Ollama ofrece una API compatible con la de OpenAI bajo el path /v1/. Así puedes usar librerías y clientes pensados para OpenAI (por ejemplo el SDK oficial de Python o de JavaScript) apuntando a tu instancia de Ollama, en local o a Ollama Cloud, con cambios mínimos de configuración.

En local, la base URL del API compatible es http://localhost:11434/v1 (o http://localhost:11434/v1/). Los endpoints típicos son:

• /v1/chat/completions: equivalente a conversación con historial (como /api/chat nativo). Recibe model y messages en el formato estándar de OpenAI.
• /v1/responses: generación a partir de un único prompt (equivalente a /api/generate). Recibe model e input. La respuesta incluye el texto generado. Detalles en la documentación de compatibilidad OpenAI de Ollama.

Las peticiones y respuestas siguen el esquema de la API de OpenAI (campos como model, messages, stream, etc.), de modo que el mismo código que usas con OpenAI puede enviar las peticiones a Ollama cambiando solo la base URL y, si aplica, la API key.

flowchart LR
    A["Cliente OpenAI<br/>Python / JavaScript"] --> B{"base_url"}
    B -->|"api.openai.com"| C["API de OpenAI"]
    B -->|"localhost:11434/v1"| D["Ollama local"]
    B -->|"URL de Ollama Cloud"| E["Ollama Cloud"]
    D --> F["Mismos endpoints<br/>/v1/chat/completions<br/>/v1/responses"]
    E --> F

Configurar el cliente con la base URL

Las librerías de OpenAI permiten indicar una base URL distinta del valor por defecto. Así apuntas todas las peticiones a Ollama en lugar de a api.openai.com.

En Python con el cliente oficial:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama",
)
response = client.chat.completions.create(
    model="llama3.2",
    messages=[{"role": "user", "content": "Hola, ¿qué es un LLM?"}],
)
print(response.choices[0].message.content)

En JavaScript/Node con el SDK de OpenAI:

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://localhost:11434/v1",
  apiKey: "ollama",
});
const completion = await client.chat.completions.create({
  model: "llama3.2",
  messages: [{ role: "user", content: "Hola, ¿qué es un LLM?" }],
});
console.log(completion.choices[0].message.content);

En local, la API key no se valida. Muchos clientes la exigen igualmente. Puedes usar cualquier valor (por ejemplo ollama) para satisfacer el parámetro. Lo importante es que base_url (o baseURL) apunte a http://localhost:11434/v1.

La variable de entorno OPENAI_API_BASE (o su equivalente en cada librería) suele usarse para inyectar esta URL sin hardcodearla en el código, útil para alternar entre OpenAI y Ollama por entorno.

Uso con Ollama Cloud y API key

Cuando usas Ollama Cloud, la base URL es la del servicio (por ejemplo la URL pública de la API de Ollama Cloud) y sí debes enviar una API key válida. La misma configuración de cliente sirve: cambias base_url a la URL de la nube y api_key a tu clave real. El servidor de Ollama Cloud valida la API key en las peticiones a /v1/.

Así puedes tener un único código que, según configuración, use Ollama en local (sin clave real) o Ollama Cloud (con API key), y en ambos casos los endpoints bajo /v1/ se comportan de forma compatible con OpenAI.

Resumen práctico

• Local: base_url = "http://localhost:11434/v1", api_key puede ser cualquier string (p. ej. "ollama").
• Ollama Cloud: base_url = URL del servicio, api_key = tu API key de la cuenta.
• OPENAI_API_BASE: úsala para definir la base URL por entorno y reutilizar el mismo código con distintos backends.

Con esto puedes integrar Ollama en cualquier aplicación o framework (LangChain, Vercel AI SDK, etc.) que ya use la API de OpenAI, cambiando solo la URL base y la API key cuando uses la nube.