Ollama API REST: referencia completa de endpoints (2026)

Petición mínima con curl

curl http://localhost:11434/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2",
    "prompt": "Explica qué es un agente de IA en dos párrafos",
    "stream": false
  }'

Estructura de la respuesta

{
  "model": "llama3.2",
  "created_at": "2026-05-13T10:00:00.000Z",
  "response": "Un agente de IA es un sistema software que...",
  "done": true,
  "done_reason": "stop",
  "context": [1, 2, 3, ...],
  "total_duration": 4823811250,
  "load_duration": 1234567,
  "prompt_eval_count": 26,
  "prompt_eval_duration": 234567890,
  "eval_count": 298,
  "eval_duration": 3456789012
}

El campo context contiene el estado interno del modelo tras procesar el prompt. Puedes pasarlo de vuelta en la siguiente petición para mantener el contexto sin usar /api/chat.

Respuesta con streaming (por defecto)

Sin "stream": false, el endpoint devuelve una serie de objetos JSON separados por saltos de línea (newline-delimited JSON). Cada objeto contiene un fragmento de la respuesta en el campo "response":

{"model":"llama3.2","created_at":"...","response":"Un ","done":false}
{"model":"llama3.2","created_at":"...","response":"agente ","done":false}
{"model":"llama3.2","created_at":"...","response":"de IA ","done":false}
...
{"model":"llama3.2","created_at":"...","response":"","done":true,"total_duration":4823811250,...}

Petición con imagen (modelos multimodales)

# Con modelos como llava o moondream2 puedes incluir imágenes en base64
curl http://localhost:11434/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llava",
    "prompt": "¿Qué hay en esta imagen?",
    "images": ["'$(base64 -w0 imagen.jpg)'"],
    "stream": false
  }'

Estructura de mensajes

curl http://localhost:11434/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2",
    "messages": [
      {
        "role": "system",
        "content": "Eres un asistente técnico experto en Python. Responde siempre en español."
      },
      {
        "role": "user",
        "content": "¿Cómo ordeno una lista de diccionarios por un campo específico?"
      }
    ],
    "stream": false
  }'

Estructura de la respuesta de chat

{
  "model": "llama3.2",
  "created_at": "2026-05-13T10:00:00.000Z",
  "message": {
    "role": "assistant",
    "content": "Para ordenar una lista de diccionarios en Python..."
  },
  "done": true,
  "done_reason": "stop",
  "total_duration": 5312678234,
  "eval_count": 312
}

Conversación multi-turno

Para mantener el contexto entre turnos, debes enviar el historial completo de mensajes en cada petición. El cliente es responsable de acumular el historial:

import requests

BASE_URL = "http://localhost:11434"
historial = [
    {"role": "system", "content": "Eres un asistente de programación en español."}
]

def chat(mensaje: str) -> str:
    historial.append({"role": "user", "content": mensaje})

    respuesta = requests.post(
        f"{BASE_URL}/api/chat",
        json={
            "model": "llama3.2",
            "messages": historial,
            "stream": False,
        }
    )

    contenido = respuesta.json()["message"]["content"]
    historial.append({"role": "assistant", "content": contenido})
    return contenido

# Conversacion de ejemplo
print(chat("¿Qué es una list comprehension en Python?"))
print(chat("¿Puedes darme un ejemplo con filtrado?"))
print(chat("¿Y cómo la transformaría en un bucle for equivalente?")

Chat con herramientas (tool calling)

curl http://localhost:11434/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2",
    "messages": [
      {"role": "user", "content": "¿Cuál es el tiempo en Madrid ahora mismo?"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "obtener_tiempo",
          "description": "Obtiene el tiempo actual para una ciudad",
          "parameters": {
            "type": "object",
            "properties": {
              "ciudad": {
                "type": "string",
                "description": "Nombre de la ciudad"
              }
            },
            "required": ["ciudad"]
          }
        }
      }
    ],
    "stream": false
  }'

Embedding de un texto

curl http://localhost:11434/api/embed \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nomic-embed-text",
    "input": "Ollama permite ejecutar modelos de lenguaje en local"
  }'

Respuesta

{
  "model": "nomic-embed-text",
  "embeddings": [
    [0.010071029, -0.0017594862, 0.05007221, 0.04692972, 0.054916814, ...]
  ],
  "total_duration": 14143917,
  "load_duration": 1019180,
  "prompt_eval_count": 8
}

Embeddings de múltiples textos en batch

curl http://localhost:11434/api/embed \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nomic-embed-text",
    "input": [
      "Ollama ejecuta modelos localmente",
      "Docker permite contenerizar aplicaciones",
      "Python es un lenguaje de programacion versatil"
    ]
  }'

Ejemplos de gestión de modelos con curl

# Listar todos los modelos instalados
curl http://localhost:11434/api/tags

# Descargar un modelo (con streaming de progreso)
curl http://localhost:11434/api/pull \
  -H "Content-Type: application/json" \
  -d '{"model": "llama3.2:3b"}'

# Informacion detallada de un modelo
curl http://localhost:11434/api/show \
  -H "Content-Type: application/json" \
  -d '{"model": "llama3.2"}'

# Eliminar un modelo
curl -X DELETE http://localhost:11434/api/delete \
  -H "Content-Type: application/json" \
  -d '{"model": "llama3.2"}'

# Ver modelos cargados en memoria ahora mismo
curl http://localhost:11434/api/ps

curl http://localhost:11434/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2",
    "prompt": "Escribe un haiku sobre la programación",
    "stream": false,
    "options": {
      "temperature":   0.9,
      "top_p":         0.95,
      "top_k":         50,
      "num_ctx":       4096,
      "num_predict":   200,
      "repeat_penalty": 1.1,
      "seed":          42
    }
  }'

Python con httpx (asíncrono)

import httpx
import asyncio
import json

OLLAMA_URL = "http://localhost:11434"

async def generar_streaming(prompt: str, modelo: str = "llama3.2"):
    """Genera texto con streaming y va imprimiendo los tokens conforme llegan."""
    async with httpx.AsyncClient(timeout=60.0) as client:
        async with client.stream(
            "POST",
            f"{OLLAMA_URL}/api/generate",
            json={
                "model":  modelo,
                "prompt": prompt,
                "stream": True,
                "options": {"temperature": 0.7, "num_predict": 500},
            }
        ) as respuesta:
            async for linea in respuesta.aiter_lines():
                if linea:
                    datos = json.loads(linea)
                    print(datos["response"], end="", flush=True)
                    if datos.get("done"):
                        print()  # salto de linea al terminar
                        print(f"\nTokens generados: {datos.get('eval_count', 0)}")
                        break

asyncio.run(generar_streaming("Explica los beneficios de usar Docker en desarrollo"))

JavaScript con fetch nativo

const OLLAMA_URL = 'http://localhost:11434';

// Funcion para chat con streaming en el navegador o Node.js
async function chat(mensajes, modelo = 'llama3.2') {
  const respuesta = await fetch(`${OLLAMA_URL}/api/chat`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      model: modelo,
      messages: mensajes,
      stream: true,
    }),
  });

  const lector = respuesta.body.getReader();
  const decodificador = new TextDecoder();
  let textoCompleto = '';

  while (true) {
    const { done, value } = await lector.read();
    if (done) break;

    const lineas = decodificador.decode(value).split('\n').filter(Boolean);
    for (const linea of lineas) {
      const datos = JSON.parse(linea);
      if (datos.message?.content) {
        textoCompleto += datos.message.content;
        process.stdout.write(datos.message.content); // o actualiza el DOM
      }
      if (datos.done) break;
    }
  }

  return textoCompleto;
}

// Uso
const mensajes = [
  { role: 'system', content: 'Eres un asistente útil en español.' },
  { role: 'user', content: '¿Qué es Ollama y para qué sirve?' },
];

chat(mensajes).then(respuesta => {
  console.log('\n\nRespuesta completa:', respuesta.length, 'caracteres');
});

Python con requests (síncrono, sin streaming)

import requests

def consulta_simple(prompt: str, modelo: str = "llama3.2") -> dict:
    """Peticion sincrona que devuelve la respuesta completa."""
    respuesta = requests.post(
        "http://localhost:11434/api/generate",
        json={
            "model":  modelo,
            "prompt": prompt,
            "stream": False,
            "options": {
                "temperature":  0.7,
                "num_ctx":      4096,
                "num_predict":  1000,
            }
        },
        timeout=120,
    )
    respuesta.raise_for_status()
    datos = respuesta.json()
    return {
        "texto":       datos["response"],
        "tokens":      datos.get("eval_count", 0),
        "duracion_ms": datos.get("total_duration", 0) // 1_000_000,
    }

resultado = consulta_simple("Resume en tres puntos las ventajas de los LLMs locales")
print(resultado["texto"])
print(f"Tokens: {resultado['tokens']} | Duracion: {resultado['duracion_ms']} ms")

Migración del cliente de Python

# Antes (con OpenAI)
from openai import OpenAI
client = OpenAI(api_key="sk-...")

# Despues (con Ollama, cambios minimos)
from openai import OpenAI
client = OpenAI(
    base_url="http://localhost:11434/v1",  # <- unico cambio
    api_key="ollama",                       # <- cualquier string no vacio
)

# El resto del codigo es identico
respuesta = client.chat.completions.create(
    model="llama3.2",  # nombre del modelo en Ollama
    messages=[
        {"role": "system", "content": "Eres un asistente en español."},
        {"role": "user",   "content": "Hola, como estas?"},
    ],
    temperature=0.7,
    max_tokens=500,
)
print(respuesta.choices[0].message.content)

Migración del cliente de JavaScript

import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: 'http://localhost:11434/v1',  // <- unico cambio
  apiKey: 'ollama',                       // <- cualquier string
});

const completion = await openai.chat.completions.create({
  model: 'llama3.2',
  messages: [
    { role: 'user', content: 'Explica el concepto de embeddings en dos párrafos' }
  ],
  temperature: 0.8,
});

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

Endpoints compatibles con OpenAI