Contenido

Tutorial de la API de Ollama: llama a /api/chat y /api/generate con curl

Ollama ofrece una API HTTP en segundo plano. La dirección predeterminada es http://localhost:11434. La CLI, Open WebUI y varias bibliotecas se comunican con los modelos a través de esta API.

/api/chat: chat

curl http://localhost:11434/api/chat -d '{
  "model": "qwen3:8b",
  "messages": [
    { "role": "system", "content": "Responde en español." },
    { "role": "user", "content": "¿Por qué el cielo es azul? Explícalo en dos frases." }
  ],
  "stream": false
}'

La respuesta tiene el siguiente formato. Es una respuesta real a un hi enviado a qwen3:0.6b (Ollama 0.40):

{
  "model": "qwen3:0.6b",
  "created_at": "2026-10-12T14:04:31.457272357Z",
  "message": {
    "role": "assistant",
    "content": "Hello! How can I assist you today? 😊 If you have any questions or need help, feel free to ask!",
    "thinking": "Okay, the user just said \"hi\" and I need to respond. ..."
  },
  "done": true,
  "done_reason": "stop",
  "total_duration": 10507470186,
  "load_duration": 26072287,
  "prompt_eval_count": 11,
  "prompt_eval_duration": 274566000,
  "eval_count": 112,
  "eval_duration": 10179865000
}

message.content: la respuesta del modelo.
message.thinking: el razonamiento del modelo. Qwen3 razona de forma predeterminada; si no lo necesitas, añade "think": false a la solicitud.
done_reason: stop indica que terminó con normalidad; length indica que se alcanzó el límite de longitud y la respuesta se truncó.
Todas las unidades de tiempo son nanosegundos (10507470186 ≈ 10.5 segundos). eval_count ÷ eval_duration indica la cantidad de tokens generados por segundo.

Conversación de varios turnos

La API no recuerda las conversaciones anteriores. Para continuar una conversación, debes incluir todo el historial de mensajes:

{
  "model": "qwen3:8b",
  "messages": [
    { "role": "user", "content": "Me llamo Alex" },
    { "role": "assistant", "content": "¡Hola, Alex!" },
    { "role": "user", "content": "¿Cómo me llamo?" }
  ]
}

role puede ser system, user, assistant o tool (resultado de una herramienta; consulta Llamadas a herramientas).

/api/generate: generación de texto puntual

Si no necesitas la estructura de conversación, puedes usar /api/generate:

curl http://localhost:11434/api/generate -d '{
  "model": "qwen3:8b",
  "prompt": "Traduce esta frase al inglés: Hoy hace muy buen tiempo",
  "stream": false
}'

La respuesta aparece en el campo response. Por lo general, se recomienda usar /api/chat.

Respuestas en streaming

stream es true de forma predeterminada: el modelo devuelve una línea JSON cada vez que genera un fragmento de texto. El valor de done en la última línea es true.

curl http://localhost:11434/api/chat -d '{
  "model": "qwen3:8b",
  "messages": [{ "role": "user", "content": "Cuenta del 1 al 5" }]
}'

{"message":{"role":"assistant","content":"1"},"done":false}
{"message":{"role":"assistant","content":"、2"},"done":false}
...
{"message":{"role":"assistant","content":""},"done":true,"eval_count":12}

El streaming permite que el usuario vea la respuesta de inmediato. Casi todas las interfaces de chat lo utilizan.

options: ajustar parámetros

{
  "model": "qwen3:8b",
  "messages": [{ "role": "user", "content": "Escribe un eslogan" }],
  "options": {
    "temperature": 0.9,
    "num_ctx": 8192,
    "num_predict": 100,
    "seed": 42
  },
  "stream": false
}

Los parámetros disponibles son los mismos que PARAMETER en Modelfile. Consulta el tutorial de Modelfile.

keep_alive: mantener el modelo cargado

{ "model": "qwen3:8b", "keep_alive": "1h" }

Si envías solo model, sin mensajes, puedes precargar el modelo.
"keep_alive": 0 lo descarga inmediatamente después de responder.
"keep_alive": -1 evita que se descargue.

Entrada de imágenes

Los modelos de visión pueden recibir imágenes codificadas en base64 en un mensaje:

IMG=$(base64 -w0 photo.jpg)   # en macOS, usa base64 -i photo.jpg
curl http://localhost:11434/api/chat -d "{
  \"model\": \"gemma3\",
  \"messages\": [{
    \"role\": \"user\",
    \"content\": \"Describe esta imagen\",
    \"images\": [\"$IMG\"]
  }],
  \"stream\": false
}"

Modo de razonamiento

Los modelos compatibles con el razonamiento permiten controlarlo con think:

{
  "model": "qwen3:8b",
  "messages": [{ "role": "user", "content": "¿Cuántas r tiene strawberry?" }],
  "think": true,
  "stream": false
}

El razonamiento aparece en message.thinking y la respuesta final en message.content. think también puede ser false; algunos modelos admiten niveles como "low", "medium" y "high".

Otros endpoints habituales

Método y ruta	Función
`GET /api/tags`	Muestra los modelos descargados (equivale a `ollama list`)
`GET /api/ps`	Muestra los modelos cargados
`POST /api/show`	Información del modelo
`POST /api/pull`	Descarga un modelo
`DELETE /api/delete`	Elimina un modelo
`POST /api/embed`	Genera embeddings de texto; consulta Embeddings de texto y RAG
`GET /api/version`	Versión de Ollama

curl http://localhost:11434/api/tags
curl http://localhost:11434/api/show -d '{"model": "qwen3:8b"}'

API compatible con OpenAI

Ollama también ofrece endpoints compatibles con la API de OpenAI en /v1:

Endpoint	Descripción
`/v1/chat/completions`	Chat
`/v1/completions`	Compleción de texto
`/v1/embeddings`	Embeddings
`/v1/models`	Lista de modelos
`/v1/responses`	API de Responses

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3:8b",
    "messages": [{ "role": "user", "content": "Hola" }]
  }'

Muchos programas y herramientas creados originalmente para OpenAI pueden usar modelos locales si cambias la URL base a http://localhost:11434/v1 y escribes cualquier valor como API key. Consulta el ejemplo de Python en la siguiente sección.

Actualizado 12 de octubre de 2026