Introducción a la API REST de Ollama

Base URL y acceso en local

El servidor de Ollama expone una API REST sobre HTTP. En una instalación local, por defecto escucha en http://localhost:11434. Cualquier cliente que pueda hacer peticiones HTTP (curl, Postman, código en Python o JavaScript, etc.) puede hablar con el servidor usando esa base URL.

No necesitas API key en local: el servidor acepta peticiones desde la misma máquina sin autenticación. Eso facilita probar la API desde scripts o desde herramientas de desarrollo. Si cambias el puerto o el host (por ejemplo al desplegar en Docker o en otra máquina), la base URL será la que hayas configurado (por ejemplo http://host:11434).

En local, la API está pensada para uso en tu entorno de desarrollo o en tu red. Si expones el puerto a internet, conviene proteger el acceso (proxy, firewall o autenticación adicional).

Endpoints principales

La API de Ollama organiza la funcionalidad en endpoints concretos. Los más usados son:

| Endpoint | Método | Uso | |----------|--------|-----| | /api/generate | POST | Generar texto a partir de un prompt (una sola vuelta, con o sin streaming). | | /api/chat | POST | Conversación con historial de mensajes (user/assistant/system), ideal para chatbots. | | /api/embed | POST | Obtener embeddings (vectores) de un texto para RAG o búsqueda semántica. | | /api/tags | GET | Listar los modelos disponibles en el servidor (equivalente a ollama list). | | /api/ps | GET | Ver qué modelos están cargados en memoria en ese momento. |

Todas las peticiones de generación o embeddings van con POST y cuerpo en JSON. Las respuestas son también JSON (o líneas de JSON si usas streaming). En las siguientes lecciones se verá en detalle cómo usar /api/generate, /api/chat, /api/embed y la compatibilidad con la API de OpenAI.

Comprobar que la API responde

Puedes comprobar que el servidor está en marcha y que la API responde haciendo una petición GET al endpoint de listado de modelos:

curl http://localhost:11434/api/tags

Si el servidor está activo, recibirás un JSON con la lista de modelos instalados (o disponibles en la nube si aplica). Si no está en marcha, obtendrás un error de conexión. En ese caso, arranca Ollama (por ejemplo abriendo la aplicación de escritorio o ejecutando ollama serve) y vuelve a probar.

flowchart LR
  subgraph Cliente
    C[Cliente HTTP]
  end
  subgraph Servidor
    T["/api/tags"]
    G["/api/generate"]
    H["/api/chat"]
    E["/api/embed"]
  end
  C -->|GET| T
  C -->|POST| G
  C -->|POST| H
  C -->|POST| E

El cliente envía peticiones a la base URL y el servidor enruta cada petición al endpoint correspondiente según el path.

Uso con Ollama Cloud

Cuando usas Ollama Cloud (servicio gestionado en la nube), la base URL no es localhost. Debes usar la URL que proporciona el servicio (por ejemplo https://api.ollama.com o la indicada en la documentación actual) y, en ese caso, sí se requiere autenticación mediante API key.

La API key se envía normalmente en la cabecera Authorization (por ejemplo Bearer TU_API_KEY). Sin ella, las peticiones a los endpoints de la nube serán rechazadas. La lógica de los endpoints (generate, chat, embed, etc.) es la misma que en local. Solo cambian la base URL y la necesidad de enviar la API key en cada petición.

Si en tu entorno no debe usarse la nube, puedes definir OLLAMA_NO_CLOUD=1 para que el cliente no intente conectar con Ollama Cloud.

En local usas http://localhost:11434 y no necesitas API key. En Ollama Cloud usas la URL del servicio y envías tu API key en las cabeceras. A partir de ahí, los endpoints y el formato de las peticiones son coherentes en ambos entornos.