API compatible con OpenAI de Ollama: acceso, precios, integración y guía de producción

API compatible con OpenAI de Ollama: acceso, precios, integración y guía de producción

La API compatible con OpenAI de Ollama permite que una aplicación conserve la estructura familiar del SDK de OpenAI y envíe solicitudes a un servidor local de Ollama o directamente a Ollama Cloud. Esto resulta útil, pero no garantiza una equivalencia exacta de funciones: Ollama documenta la compatibilidad con un subconjunto de la API de OpenAI, y algunas capacidades dependen del endpoint y del modelo que elijas.

Esta guía muestra cómo acceder a esta interfaz, configurarla en una aplicación existente de Python o JavaScript, comprender los costes de la nube frente a los locales y establecer límites reales para su uso en producción.

Respuesta rápida: usa http://localhost:11434/v1/ para un servidor local de Ollama y una clave de API de marcador de posición que exige el SDK, pero que Ollama ignora. Usa https://ollama.com/v1 junto con OLLAMA_API_KEY para acceder directamente a la nube. Valida el endpoint y el modelo concretos antes de depender del streaming, la visión, las herramientas, la salida estructurada o el comportamiento de la API Responses.

¿Qué significa «compatible con OpenAI» para Ollama?

Se trata de una interfaz de integración para clientes de OpenAI, no de una API alojada por OpenAI. Permite apuntar clientes compatibles a las URL base de Ollama y usar rutas compatibles como chat completions, embeddings, descubrimiento de modelos y solicitudes de Responses sin estado.

La referencia de compatibilidad de Ollama es la fuente definitiva para conocer el subconjunto admitido. En particular:

• /v1/chat/completions admite funciones como streaming, modo JSON, visión, herramientas, salidas reproducibles, logprobs y controles que solo se aplican a modelos compatibles.
• /v1/embeddings admite entradas de tipo cadena y matriz.
• /v1/models y /v1/models/{model} permiten descubrir modelos, pero algunos campos devueltos tienen significados específicos de Ollama.
• POST /v1/responses está disponible, pero no mantiene estado: no dependas de previous_response_id ni de conversation.

Consulta la referencia actualizada de compatibilidad de Ollama con OpenAI antes de habilitar una capacidad en producción. «Compatible» debe entenderse como un motivo para reutilizar el cliente y la estructura de las solicitudes, no como una razón para omitir las pruebas de funcionalidad.

Acceso a la API compatible con OpenAI de Ollama: local frente a nube

La decisión de implementación más sencilla es si la inferencia se ejecuta en tu propia máquina o utiliza el endpoint en la nube de Ollama.

Esta distinción está documentada en la introducción a la API y la guía de autenticación de Ollama. Las llamadas directas a la nube requieren una clave de API. Las llamadas locales no.

Configuración local

Instala Ollama y, después, descarga el modelo que quieras usar. La documentación de Ollama muestra el patrón general:

ollama pull gpt-oss:20b
ollama serve

Ahora comprueba que el endpoint local puede enumerar los modelos:

curl http://localhost:11434/v1/models

Si falla la conexión, resuelve el problema del servidor local antes de modificar el código de la aplicación. Una migración de cliente es mucho más fácil de depurar cuando la URL base de la API y el inventario de modelos ya funcionan de forma independiente.

Configuración del acceso directo a la nube

Para usar la nube directamente, crea una clave de API en tu cuenta de Ollama y guárdala en una variable de entorno:

export OLLAMA_API_KEY="replace-with-your-key"

La URL base de la nube es https://ollama.com/v1. Ollama documenta que su API alojada utiliza Authorization: Bearer; no incluyas una clave de larga duración en el código del navegador, en un repositorio ni en un archivo de configuración del lado del cliente.

Integración de la API compatible con OpenAI de Ollama con el SDK de OpenAI

El punto de migración es la configuración del cliente. Mantén los mensajes de la aplicación y el manejo de errores detrás de tu propia interfaz y, después, cambia únicamente la URL base, la clave y la configuración del modelo.

Python: servidor local

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1/",
    api_key="ollama",  # required by the SDK; ignored by the local server
)

response = client.chat.completions.create(
    model="gpt-oss:20b",
    messages=[
        {"role": "user", "content": "Summarize the production risks of exposing a local API."}
    ],
)

print(response.choices[0].message.content)

El endpoint local no autentica las solicitudes. La clave de marcador de posición existe únicamente porque el cliente de OpenAI espera un valor; no protege el servidor local.

Python: nube directa

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://ollama.com/v1",
    api_key=os.environ["OLLAMA_API_KEY"],
)

response = client.chat.completions.create(
    model="gemma4:31b",
    messages=[
        {"role": "user", "content": "Give one sentence on safe API key storage."}
    ],
)

print(response.choices[0].message.content)

La estructura del código es deliberadamente similar. La diferencia operativa no lo es: las llamadas directas a la nube dependen de una clave de API y del modelo en la nube elegido; las llamadas locales dependen de un modelo descargado y de los recursos disponibles en el host.

JavaScript: mantenga el endpoint configurable

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: process.env.OLLAMA_BASE_URL ?? "http://localhost:11434/v1/",
  apiKey: process.env.OLLAMA_API_KEY ?? "ollama",
});

const completion = await client.chat.completions.create({
  model: process.env.OLLAMA_MODEL ?? "gpt-oss:20b",
  messages: [{ role: "user", content: "Return a concise health-check message." }],
});

console.log(completion.choices[0].message.content);

Establezca variables de entorno para cada despliegue:

# Local
OLLAMA_BASE_URL=http://localhost:11434/v1/
OLLAMA_API_KEY=ollama
OLLAMA_MODEL=gpt-oss:20b

# Direct cloud
OLLAMA_BASE_URL=https://ollama.com/v1
OLLAMA_API_KEY=replace-with-your-key
OLLAMA_MODEL=gemma4:31b

Esta configuración hace que un cambio posterior de ruta o modelo sea explícito y revisable. También evita que una URL base específica del entorno se convierta en comportamiento oculto de la aplicación.

Matriz de compatibilidad: qué probar antes del lanzamiento

La API compatible con OpenAI de Ollama es más útil cuando convierte la compatibilidad en un plan de pruebas en lugar de una suposición.

Dos detalles suelen sorprender a los equipos:

1. El estado pertenece a su aplicación. Su aplicación debe almacenar los mensajes o el estado de conversación que necesite, en lugar de esperar un comportamiento de Responses con estado de Ollama.
2. El nombre de un modelo no garantiza sus capacidades. Una solicitud puede usar un endpoint compatible y aun así no proporcionar la calidad o el comportamiento de herramientas que necesita un flujo de trabajo. Pruebe conjuntamente el modelo, el tamaño del prompt, los límites de salida y las herramientas.

Si una integración existente codifica de forma rígida un nombre de modelo predeterminado de OpenAI, Ollama documenta ollama cp como una forma de crear un alias temporal de modelo local. Úselo solo como una capa de compatibilidad deliberada, documente el alias y elimínelo cuando su configuración sea explícita.

Precios de Ollama: TCO local frente a tarifas de tokens en la nube

Los precios de la API compatible con OpenAI de Ollama dependen de la ruta.

La inferencia local no es una factura por tokens, pero no es gratuita

Ejecutar un modelo local no genera una factura de Ollama Cloud por token. Sí crea un perfil de costes operativos:

• Capacidad de GPU o CPU, RAM/VRAM, almacenamiento y depreciación de las máquinas
• Electricidad y refrigeración
• Tiempo de descarga del modelo y almacenamiento de imágenes
• Planificación de capacidad, supervisión, aplicación de parches y respuesta a incidentes
• El coste de oportunidad de mantener un modelo activo para solicitudes de baja latencia

Para un solo desarrollador, esto puede ser una excelente opción. Para un producto con tráfico irregular o múltiples modelos, calcule la utilización del hardware y el trabajo de fiabilidad junto con el costo bruto de inferencia.

Los precios directos en la nube se publican por millón de tokens

La página de precios en tiempo real de Ollama enumera las tarifas en la nube por un millón de tokens, incluidos precios independientes para entrada, entrada en caché y salida. Los ejemplos siguientes se verificaron el 22 de octubre de 2026; use la lista de precios en tiempo real para las decisiones de compras y despliegue.

La página de precios de Ollama también describe precios fuera de horario punta para las entradas elegibles. No elabore un presupuesto basándose solo en la etiqueta de un modelo: use la fila de precios que corresponda a la ruta, el modelo y el momento reales.

Una estimación mensual práctica es:

monthly_cloud_cost =
  (input_tokens / 1,000,000 × input_rate)
+ (cached_input_tokens / 1,000,000 × cached_input_rate)
+ (output_tokens / 1,000,000 × output_rate)

Por ejemplo, con las tarifas publicadas de gpt-oss:20b indicadas arriba, 1 millón de tokens de entrada sin caché más 250.000 tokens de salida se estiman en $0.145 antes de cualquier cambio de precios o crédito específico de la cuenta. Use la telemetría de tokens observada, no una longitud de chat estimada, para una previsión de producción.

Guía de producción: proteja el servidor local antes de exponerlo

La regla de producción más importante para la API compatible con OpenAI de Ollama es simple: un servidor local de Ollama no tiene autenticación de forma predeterminada.

Ollama se vincula a 127.0.0.1:11434 de forma predeterminada. Su documentación muestra que OLLAMA_HOST puede cambiar la dirección de enlace y que un proxy como Nginx puede reenviar tráfico al servidor. Estas son opciones de implementación, no de autenticación. Si mueve el servicio más allá de localhost, implemente controles deliberados a su alrededor.

Lista de verificación para producción

1. Mantenga el enlace de loopback predeterminado, salvo que tenga una ruta de acceso definida. No exponga el puerto 11434 directamente a Internet.
2. Implemente TLS y autenticación en el perímetro. Use un proxy inverso, una red privada, identidad de servicio y autorización por cliente adecuados para su entorno. Una clave ficticia del SDK de OpenAI no es un control de acceso.
3. Permita orígenes de navegador de forma restringida. Ollama documenta OLLAMA_ORIGINS para orígenes permitidos adicionales. Agregue solo los orígenes exactos de aplicaciones web o extensiones que necesiten acceso; no lo convierta en una omisión general de la política de origen cruzado.
4. Use una lista de modelos permitidos. Trate el model solicitado como una entrada que debe validar. Los llamadores de producción no deberían poder descargar modelos arbitrarios ni seleccionar modelos no revisados.
5. Defina una política de cola y gestione las sobrecargas. Ollama documenta que un servidor sobrecargado puede devolver HTTP 503 y expone OLLAMA_MAX_QUEUE. Use reintentos limitados con retroceso exponencial y aleatorización, y luego presente un error controlado al llamador.
6. Planifique conjuntamente la capacidad de VRAM y la concurrencia. OLLAMA_NUM_PARALLEL aumenta el paralelismo por modelo, pero los requisitos de memoria crecen con él. OLLAMA_MAX_LOADED_MODELS y OLLAMA_KEEP_ALIVE determinan cuán agresivamente los modelos ocupan memoria.
7. Instrumente las rutas importantes. Realice seguimiento de la latencia, el tiempo en cola, los HTTP 503, el inventario de modelos activos, el tamaño de las solicitudes, las desconexiones de streams, los errores de llamadas a herramientas y la presión de memoria de GPU/CPU. ollama ps ayuda a verificar dónde se ejecutan los modelos cargados.
8. Pruebe reinicios y arranques en frío. Un modelo local puede necesitar tiempo de carga después de un despliegue o desalojo. Realice pruebas de carga, reversión y tiempos de espera antes de que la API respalde un flujo de trabajo orientado al cliente.
9. Mantenga los secretos fuera de los clientes. Para el modo en la nube, almacene OLLAMA_API_KEY en un administrador de secretos del lado del servidor o en un entorno de ejecución protegido, no en un bundle de frontend.
10. Fije la suite de aceptación, no solo la versión de la dependencia. Vuelva a ejecutar pruebas de chat, streaming, herramientas, JSON, visión y estado de respuesta cada vez que actualice Ollama, cambie un modelo o modifique la capa de enrutamiento.

Las preguntas frecuentes de Ollama documentan la dirección de enlace, la configuración de CORS, el comportamiento de las colas, la configuración de concurrencia y los controles locales/en la nube que respaldan estas recomendaciones.

Una ruta de implementación más segura

Use esta secuencia para una aplicación que comienza localmente y que más adelante puede usar modelos alojados:

1. Pruebe el endpoint local. Descargue un modelo, enumere los modelos y envíe una finalización de chat sin streaming.
2. Estabilice la configuración del cliente de OpenAI. Convierta la URL base, la clave de API y el modelo en variables de entorno, no en literales dispersos por la base de código.
3. Cree una suite de compatibilidad. Incluya salida JSON, streaming, cada esquema de herramientas, entradas de visión cuando corresponda, comportamiento de tiempos de espera y solicitudes malformadas.
4. Realice pruebas de carga en el host. Registre la latencia, la profundidad de cola, la VRAM/RAM y el punto en el que comienzan los errores 503.
5. Añada un perímetro autenticado antes del acceso remoto. Mantenga Ollama privado detrás del servicio de aplicación o de un proxy de confianza.
6. Evalúe el modo en la nube por separado. Use una clave dedicada para la nube, modelos incluidos en una lista de permitidos, alertas de presupuesto y casos de prueba que cubran las limitaciones de Responses específicas de la nube.
7. Desacople la elección del proveedor de la lógica de negocio. Si un producto necesita comparar modelos alojados o añadir una ruta de respaldo, mantenga el contrato del cliente de OpenAI detrás de un pequeño adaptador.

Para el último paso, una lista de verificación para la migración a una puerta de enlace de API compatible con OpenAI puede ayudarle a separar la integración del cliente de la selección del proveedor de modelos. Si desea evaluar varios proveedores alojados sin añadir un nuevo patrón de cliente para cada uno, consulte la guía de inicio rápido de la API de Flatkey y la guía para decidir cuándo resulta útil una puerta de enlace de API de IA.

Errores comunes con la API compatible con OpenAI de Ollama

Tratar un servidor localhost como un servicio protegido

Una solicitud local puede funcionar porque el proceso está en la misma máquina, no porque el acceso esté autenticado. En cuanto cambie una dirección de enlace, un túnel, un proxy o un puerto de contenedor, revise la identidad, la política de red, TLS y el registro de auditoría.

Suponer paridad de funcionalidades con OpenAI

Ollama admite explícitamente un subconjunto de la API de OpenAI. Incorpore una comprobación de capacidades en CI y pruebe la semántica, no solo una respuesta 200. Una definición de herramienta que se analiza localmente puede comportarse de forma diferente después de cambiar de modelo.

Usar las etiquetas de precios de la nube como presupuesto

Las tarifas de entrada, entrada en caché y salida pueden diferir considerablemente. Registre los campos de tokens, calcule el coste efectivo por tarea completada correctamente y vuelva a consultar la página de precios antes de comprometer un presupuesto fijo.

Aumentar el paralelismo sin un modelo de memoria

Más solicitudes en paralelo pueden aumentar los requisitos de contexto y memoria. Supervise la presión real en el host con prompts representativos antes de cambiar la configuración de concurrencia.

Dar al navegador una clave de nube

Una llamada directa del navegador a la nube dificulta mucho más la rotación de claves, el control del presupuesto y la prevención del abuso. Mantenga la clave de nube en un backend de confianza y exponga únicamente la operación que necesita su aplicación.

Preguntas frecuentes

¿La API compatible con OpenAI de Ollama es igual que la API de OpenAI?

No. La capa de compatibilidad de Ollama admite un subconjunto documentado de la API de OpenAI para que los clientes compatibles puedan conectarse a Ollama. Confirme los endpoints y campos individuales en la referencia de compatibilidad de Ollama antes de considerar una funcionalidad como portable.

¿La API local de Ollama necesita una clave de API?

No. Ollama indica que la API local no requiere autenticación. El valor api_key="ollama" en los ejemplos de SDK es un requisito de cliente no vacío, no una credencial. Mantenga el servidor local en localhost o añada controles reales antes de exponerlo de forma remota.

¿Ollama Cloud necesita una clave de API?

Sí. El acceso directo a la nube en https://ollama.com/v1 requiere una clave de API enviada como token Bearer. Almacénela en el servidor.

¿Puedo usar /v1/responses?

Sí, para solicitudes de Responses sin estado. No dependa de previous_response_id ni de conversation. La documentación de la nube también señala limitaciones relacionadas con la búsqueda web integrada y la reproducción de llamadas a herramientas personalizadas/de formato libre.

¿La API compatible con OpenAI de Ollama es gratuita?

La inferencia local no tiene un cargo por token de Ollama Cloud, pero aun así paga por el hardware y las operaciones que ejecuta. La inferencia directa en la nube utiliza precios publicados por token y créditos de cuenta.

¿Cuándo debería usar una puerta de enlace en su lugar?

Use Ollama directamente cuando la ruta local o en la nube satisfaga las necesidades de modelo, privacidad y operación de la carga de trabajo. Considere una puerta de enlace cuando su producto necesite una integración coherente entre varios proveedores alojados, un flujo de trabajo de evaluación de modelos o una ruta de respaldo independiente. Comience con una decisión clara sobre una API de IA unificada y, a continuación, mantenga el mismo adaptador de cliente a nivel de aplicación.

Conclusión

La API compatible con OpenAI de Ollama ofrece a los desarrolladores una forma práctica de reutilizar un SDK de OpenAI con modelos locales o servidos desde la nube. Una implementación segura no consiste solo en cambiar la URL base: requiere una matriz de capacidades probada, un modelo de costes claro para local frente a nube, un límite de despliegue local privado y un plan probado bajo carga para las colas y la memoria de los modelos.

Empieza en local si necesitas control y puedes operar el hardware. Usa la nube directa cuando quieras inferencia alojada mediante la misma interfaz de cliente. En cualquier caso, mantén la elección del endpoint configurable y haz que cada función compatible se gane su lugar en tu suite de pruebas de producción.