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.

Funcionalidades soportadas en el modo compatible

La API compatible con OpenAI de Ollama soporta las funcionalidades más habituales del esquema de OpenAI, aunque con algunas diferencias según la versión y el modelo:

• Chat completions (/v1/chat/completions): conversación con historial, streaming, parámetros de generación (temperature, top_p, max_tokens), mensajes con roles system, user y assistant.
• Responses (/v1/responses): generación a partir de un único prompt, equivalente a /api/generate en la API nativa.
• Structured outputs: puedes pasar response_format con un JSON schema para obtener respuestas estructuradas, igual que con el parámetro format de la API nativa.
• Tool calling: si el modelo soporta herramientas, puedes enviar definiciones de funciones en tools y recibir tool_calls en la respuesta, del mismo modo que con la API de OpenAI.
• Streaming: por defecto, las respuestas llegan en streaming (Server-Sent Events), igual que la API de OpenAI. Con stream: false se recibe la respuesta completa de una vez.

No todos los campos de la API de OpenAI están implementados (por ejemplo, campos relacionados con facturación o con modelos exclusivos de OpenAI), pero los que se usan habitualmente en desarrollo y producción están cubiertos. La documentación de compatibilidad en docs.ollama.com detalla qué campos se soportan en cada versión.

Integración con frameworks y herramientas

La compatibilidad con OpenAI permite usar Ollama con cualquier framework o herramienta que ya tenga integración con la API de OpenAI:

• LangChain: configura ChatOpenAI con base_url apuntando a Ollama y usa cadenas, agentes y RAG sin cambiar el resto del código.
• Vercel AI SDK: establece la base URL del proveedor de OpenAI y todas las funciones de streaming y generación funcionan contra Ollama.
• Cursor y VS Code: muchos plugins de asistencia de código permiten configurar una URL base personalizada para la API de OpenAI. Apuntando a http://localhost:11434/v1 usas modelos locales de Ollama como backend.

La variable de entorno OPENAI_API_BASE (o su equivalente en cada librería) permite inyectar esta URL sin modificar el código, lo que facilita alternar entre OpenAI y Ollama por entorno (desarrollo en local, producción con OpenAI o viceversa).

Compatibilidad con la API de Anthropic

Además de la compatibilidad con OpenAI, Ollama expone una API compatible con Anthropic. Esto permite que herramientas como Claude Code se conecten a Ollama como si fuera el backend de Anthropic. La configuración se hace con las variables ANTHROPIC_BASE_URL y ANTHROPIC_AUTH_TOKEN, apuntando al servidor de Ollama. La integración con Claude Code se detalla en la lección correspondiente del módulo de integraciones.

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.