Integración de programación con la API REST de Ollama
Después de instalar Ollama, se ofrece un conjunto completo de API REST en el puerto local 11434, que cubre generación de texto, chat, incrustación de vectores y gestión de modelos, y proporciona dos conjuntos de protocolos compatibles: OpenAI y Anthropic.
En este artículo se explican a fondo los interfaces principales: estructura de solicitudes, procesamiento en streaming, estadísticas de uso y manejo de errores, para que cualquier lenguaje pueda integrarse con el modelo local.
Dos URL base y métodos de autenticación
La API de Ollama tiene dos puntos de entrada: local y nube, con diferentes reglas de autenticación.
| Entrada | Base URL | Autenticación |
|---|---|---|
| Servicio local | http://localhost:11434/api | Sin autenticación |
| Servicio local (protocolo compatible) | http://localhost:11434/v1 | Sin autenticación, api_key se puede rellenar con cualquier valor |
| Ollama Cloud | https://ollama.com/api | Authorization: Bearer + API Key |
El servicio local no requiere autenticación por defecto y funciona de inmediato; al conectarse directamente a la interfaz en la nube de ollama.com, primero cree una clave API en la página de configuración del sitio oficial y colóquela en el encabezado de la solicitud.
Generación de texto: /api/generate
generate es la interfaz de generación de una sola ronda más básica; basta con pasar el nombre del modelo y el prompt:
Ejemplo
"model": "qwen3.5",
"prompt": "Presenta EJEMPLO (Tutorial para novatos) en una frase",
"stream": false
}'
Cuando stream se establece en false, se devuelve un único objeto JSON:
{
"model": "qwen3.5",
"created_at": "2026-08-29T03:20:00.499127Z",
"response": "Ejemplo是一个面向编程初学者的免费中文教程网站。",
"done": true,
"total_duration": 10706818083,
"load_duration": 6338219291,
"prompt_eval_count": 26,
"prompt_eval_duration": 130079000,
"eval_count": 42,
"eval_duration": 4232710000
}
Los parámetros comunes son los siguientes:
| Parámetro | Descripción |
|---|---|
| model | Obligatorio, nombre del modelo |
| prompt | Prompt; se puede dejar vacío para precargar el modelo |
| stream | Por defecto true devuelve en streaming; cuando es false devuelve el resultado completo de una vez |
| system | Especificar temporalmente el prompt del sistema, sobrescribiendo la configuración en Modelfile |
| options | Objeto de parámetros de generación, como temperature, num_ctx (igual que los parámetros de Modelfile) |
| format | "json" o un JSON Schema completo, para forzar la salida estructurada |
| keep_alive | Duración de la permanencia del modelo después de la solicitud, como "10m", -1 para permanente, 0 para descargar inmediatamente |
| raw | Cuando es true, omite el ensamblaje de la plantilla y usa directamente el prompt completo que proporcionaste |
| suffix | Texto que se añade después de la salida del modelo, para escenarios de autocompletado de texto |
| images | Array de imágenes en base64, para usar con modelos multimodales |
Dos consejos prácticos: enviar un prompt vacío puede precargar el modelo en la memoria, eliminando la espera de carga de la primera solicitud; establecer keep_alive en 0 junto con un prompt vacío puede descargar el modelo inmediatamente y liberar memoria de video.
Ejemplo
curl http://localhost:11434/api/generate -d '{"model": "qwen3.5"}'
# Descargar el modelo inmediatamente, liberar memoria de video
curl http://localhost:11434/api/generate -d '{"model": "qwen3.5", "keep_alive": 0}'
Generación de chat: /api/chat
chat es una interfaz de conversación de múltiples turnos; el historial de mensajes lo mantiene el propio llamador, esta es la diferencia esencial con generate.
Ejemplo
"model": "qwen3.5",
"messages": [
{ "role": "user", "content": "¿Qué es Python?" },
{ "role": "assistant", "content": "Un sitio web de tutoriales en chino orientado a principiantes." },
{ "role": "user", "content": "¿Es gratuito? Responde en una frase" }
],
"stream": false
}'
Campos admitidos por el objeto de mensaje:
| Campo | Descripción |
|---|---|
| role | Cuatro roles: system / user / assistant / tool |
| content | Contenido del mensaje |
| images | Opcional, lista de imágenes en base64 (modelos multimodales) |
| thinking | Opcional, proceso de razonamiento del modelo de pensamiento (junto con el parámetro think) |
| tool_calls | Opcional, lista de herramientas que el modelo solicita llamar (práctica en el capítulo de llamada de herramientas) |
La forma correcta de una conversación de múltiples turnos: añade el mensaje assistant que devuelve el modelo en cada ronda al array messages, y envíalo junto con la nueva pregunta; así el modelo puede "recordar" el contexto completo.
messages se gestiona completamente por ti, lo que significa que el historial se puede persistir en una base de datos, se puede comprimir en resúmenes, y también se puede restaurar entre sesiones: el problema de "perder la memoria al salir de la línea de comandos" mencionado en el artículo 5 tiene aquí una solución de ingeniería.
Incrustación de vectores: /api/embed
La interfaz embed convierte texto en vectores; es el taller de materias primas para RAG y la búsqueda semántica.
Ejemplo
curl http://localhost:11434/api/embed -d '{
"model": "embeddinggemma",
"input": "EJEMPLO es un sitio web de tutoriales de programación"
}'
# Lote: input pasa un array, devuelve múltiples vectores a la vez
curl http://localhost:11434/api/embed -d '{
"model": "embeddinggemma",
"input": ["Primer texto", "Segundo texto", "Tercer texto"]
}'
Los embeddings en la respuesta son un array bidimensional; cada vector ya ha sido normalizado L2 (longitud unitaria), por lo que se pueden comparar directamente con similitud de coseno.
Dos parámetros a tener en cuenta: dimensions puede especificar la dimensión del vector de salida (cuando el modelo lo admite, se puede reducir la dimensión para ahorrar almacenamiento); truncate por defecto true trunca automáticamente el texto demasiado largo; si se establece en false, se produce un error cuando es demasiado largo.
Streaming y no streaming: cómo manejar las respuestas
Las interfaces de generación devuelven por defecto en streaming, con formato NDJSON: cada línea es un objeto JSON independiente.
{"model":"qwen3.5","created_at":"...","response":"EJEMPLO","done":false}
{"model":"qwen3.5","created_at":"...","response":"(Ejemplo)","done":false}
{"model":"qwen3.5","created_at":"...","response":"是编程初学者的入门网站。","done":false}
{"model":"qwen3.5","created_at":"...","response":"","done":true,"done_reason":"stop"}
El cliente lee línea por línea, concatena los campos response y así obtiene la respuesta completa; el proceso de concatenación se puede renderizar en la interfaz en tiempo real.
Compensaciones entre los dos modos:
| Modo | Ventaja | Escenario de aplicación |
|---|---|---|
| Streaming (predeterminado) | Baja latencia del primer carácter, se puede mostrar en tiempo real | Interfaz de chat, generación de texto largo |
| No streaming stream:false | Obtener el resultado completo de una vez, procesamiento simple | Procesamiento por lotes, salida estructurada, llamadas de script |
En el modo streaming, los errores pueden ocurrir a mitad de la salida; en ese momento el código de estado HTTP ya no se puede cambiar. El error aparecerá como una línea {"error": "..."} al final del flujo de datos; el cliente debe comprobar esta línea al analizar.
Estadísticas de uso y manejo de errores
Al final de cada respuesta de generación se incluyen campos de estadísticas de rendimiento, que son los datos de primera mano para evaluar el coste de inferencia.
| Campo | Significado |
|---|---|
| total_duration | Tiempo total de solicitud (nanosegundos) |
| load_duration | Tiempo de carga del modelo (notable en la primera solicitud) |
| prompt_eval_count | Número de tokens consumidos en la entrada |
| prompt_eval_duration | Tiempo de procesamiento de entrada |
| eval_count | Número de tokens generados en la salida |
| eval_duration | Tiempo de generación de salida |
La fórmula para calcular la velocidad de generación (token/s): eval_count / eval_duration * 10^9, las unidades de tiempo de los campos son nanosegundos.
En cuanto al manejo de errores, la interfaz utiliza códigos de estado HTTP estándar para expresar los resultados:
| Código de estado | Significado |
|---|---|
| 200 | Éxito |
| 400 | Error de solicitud (faltan parámetros, JSON inválido, etc.) |
| 404 | El modelo no existe (ejecuta ollama pull o revisa el nombre) |
| 429 | Limitación de frecuencia por solicitudes excesivas |
| 500 | Error interno del servidor |
| 502 | Error de puerta de enlace (por ejemplo, modelo en la nube inalcanzable) |
El cuerpo de la respuesta de error tiene siempre la estructura {"error": "descripción del error"}; el cliente solo tiene que obtener el campo error.
Resumen de las API de gestión de modelos
Toda la gestión de modelos que se puede hacer por línea de comandos tiene su correspondiente API; es adecuada para paneles de administración o scripts de automatización.
| Endpoint | Método | Función |
|---|---|---|
| /api/tags | GET | Listar modelos locales (incluye número de parámetros, nivel de cuantificación) |
| /api/show | POST | Ver detalles del modelo, capacidades y plantilla |
| /api/pull | POST | Descargar el modelo, devuelve el progreso de descarga en streaming |
| /api/push | POST | Enviar el modelo al registro de modelos |
| /api/copy | POST | Copiar modelo (source / destination) |
| /api/delete | DELETE | Eliminar modelo |
| /api/create | POST | Crear modelo (incluye cuantificación, corresponde a la capacidad de Modelfile) |
| /api/ps | GET | Ver los modelos actualmente cargados y el uso de memoria de video |
| /api/version | GET | Consultar la versión de Ollama |
Tomando como ejemplo /api/tags, la respuesta incluye los detalles de especificación de cada modelo:
{
"models": [
{
"name": "qwen3.5:latest",
"size": 6600000000,
"details": {
"family": "qwen3.5",
"parameter_size": "9B",
"quantization_level": "Q4_K_M"
}
}
]
}
Los campos como quantization_level y parameter_size se pueden usar directamente para crear la interfaz del selector de modelos.
Interfaz compatible con OpenAI
Las aplicaciones OpenAI existentes que cambian a modelos locales generalmente solo necesitan cambiar una base_url.
Ejemplo
-H "Content-Type: application/json" \
-d '{
"model": "qwen3.5",
"messages": [{ "role": "user", "content": "Introduce Python en una oración" }]
}'
La compatibilidad cubre cinco endpoints:
| Endpoint | Descripción |
|---|---|
| /v1/chat/completions | Finalización de chat, soporta modo streaming, visión, herramientas y JSON |
| /v1/completions | Finalización de texto |
| /v1/responses | API de Responses (modo sin estado) |
| /v1/embeddings | Embeddings de vectores |
| /v1/models | Lista de modelos |
Hay dos diferencias frecuentes a tener en cuenta:
Primero, el protocolo OpenAI no tiene el concepto de num_ctx; si necesitas cambiar el contexto, primero crea un modelo con PARAMETER num_ctx y luego llámalo con el nuevo nombre (puedes usar el Modelfile del artículo 7 o cp para copiarlo con otro nombre).
Segundo, algunos campos no son compatibles por ahora: tool_choice, logit_bias, n, logprobs, etc. Antes de migrar, se recomienda consultar la lista de compatibilidad del manual.
Interfaz compatible con Anthropic
Ollama también proporciona una capa de compatibilidad con la API de Mensajes de Anthropic, por lo que herramientas como Claude Code pueden usar directamente modelos locales.
Ejemplo
-H "Content-Type: application/json" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "qwen3.5",
"max_tokens": 1024,
"messages": [{ "role": "user", "content": "Introduce Python en una oración" }]
}'
Al integrar herramientas como Claude Code, solo necesitas configurar dos variables de entorno:
Ejemplo
export ANTHROPIC_BASE_URL=http://localhost:11434
claude --model qwen3.5
Limitaciones a tener en cuenta: la especificación forzada de tool_choice, el caché de indicaciones, las interfaces por lotes, la entrada de PDF y otras funciones de Anthropic no son compatibles por ahora; el recuento de tokens es aproximado.
Otras extensiones