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.

Ollama API 全景:调用方、服务端点、本地模型与 Cloud

EntradaBase URLAutenticación
Servicio localhttp://localhost:11434/apiSin autenticación
Servicio local (protocolo compatible)http://localhost:11434/v1Sin autenticación, api_key se puede rellenar con cualquier valor
Ollama Cloudhttps://ollama.com/apiAuthorization: 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

curl http://localhost:11434/api/generate -d '{
  "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ámetroDescripción
modelObligatorio, nombre del modelo
promptPrompt; se puede dejar vacío para precargar el modelo
streamPor defecto true devuelve en streaming; cuando es false devuelve el resultado completo de una vez
systemEspecificar temporalmente el prompt del sistema, sobrescribiendo la configuración en Modelfile
optionsObjeto 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_aliveDuración de la permanencia del modelo después de la solicitud, como "10m", -1 para permanente, 0 para descargar inmediatamente
rawCuando es true, omite el ensamblaje de la plantilla y usa directamente el prompt completo que proporcionaste
suffixTexto que se añade después de la salida del modelo, para escenarios de autocompletado de texto
imagesArray 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

# Precargar el modelo (no genera contenido)
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

curl http://localhost:11434/api/chat -d '{
  "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:

CampoDescripción
roleCuatro roles: system / user / assistant / tool
contentContenido del mensaje
imagesOpcional, lista de imágenes en base64 (modelos multimodales)
thinkingOpcional, proceso de razonamiento del modelo de pensamiento (junto con el parámetro think)
tool_callsOpcional, 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

# Texto único
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:

ModoVentajaEscenario de aplicación
Streaming (predeterminado)Baja latencia del primer carácter, se puede mostrar en tiempo realInterfaz de chat, generación de texto largo
No streaming stream:falseObtener el resultado completo de una vez, procesamiento simpleProcesamiento 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.

CampoSignificado
total_durationTiempo total de solicitud (nanosegundos)
load_durationTiempo de carga del modelo (notable en la primera solicitud)
prompt_eval_countNúmero de tokens consumidos en la entrada
prompt_eval_durationTiempo de procesamiento de entrada
eval_countNúmero de tokens generados en la salida
eval_durationTiempo 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 estadoSignificado
200Éxito
400Error de solicitud (faltan parámetros, JSON inválido, etc.)
404El modelo no existe (ejecuta ollama pull o revisa el nombre)
429Limitación de frecuencia por solicitudes excesivas
500Error interno del servidor
502Error 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.

EndpointMétodoFunción
/api/tagsGETListar modelos locales (incluye número de parámetros, nivel de cuantificación)
/api/showPOSTVer detalles del modelo, capacidades y plantilla
/api/pullPOSTDescargar el modelo, devuelve el progreso de descarga en streaming
/api/pushPOSTEnviar el modelo al registro de modelos
/api/copyPOSTCopiar modelo (source / destination)
/api/deleteDELETEEliminar modelo
/api/createPOSTCrear modelo (incluye cuantificación, corresponde a la capacidad de Modelfile)
/api/psGETVer los modelos actualmente cargados y el uso de memoria de video
/api/versionGETConsultar 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

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.5",
"messages": [{ "role": "user", "content": "Introduce Python en una oración" }]
  }'

La compatibilidad cubre cinco endpoints:

EndpointDescripción
/v1/chat/completionsFinalización de chat, soporta modo streaming, visión, herramientas y JSON
/v1/completionsFinalización de texto
/v1/responsesAPI de Responses (modo sin estado)
/v1/embeddingsEmbeddings de vectores
/v1/modelsLista 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

curl http://localhost:11434/v1/messages \
  -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_AUTH_TOKEN=ollama
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