{"slug": "ollama-api-a-practical-guide-with-examples", "title": "Ollama API: A Practical Guide with Examples", "summary": "Ollama's local HTTP server on port 11434 provides a REST API for interacting with models, with endpoints for generation, chat, embeddings, and model management. The API supports streaming responses, configurable options, JSON formatting, and tool calling, and offers an OpenAI-compatible route for easy integration.", "body_md": "Originally published on\n\n[DevToolHub].\n\nEvery Ollama install runs a local HTTP server on port `11434`\n\n, and that server is the real interface to the models. The `ollama run`\n\ncommand is a thin client on top of it. Once you know the two main endpoints, the streaming format, and the options object, you can wire a local model into any application.\n\nThere is also an OpenAI-compatible route, so existing code that talks to OpenAI can point at Ollama with a base-URL change.\n\nThe Ollama API is a plain REST API served at `http://localhost:11434`\n\n. You send JSON with `POST`\n\n, and by default you get a stream of newline-delimited JSON objects back. No API key is required for local access.\n\n| Endpoint | Method | Purpose |\n|---|---|---|\n`/api/generate` |\nPOST | Single-prompt text completion |\n`/api/chat` |\nPOST | Multi-turn chat with message history and tools |\n`/api/embed` |\nPOST | Generate embeddings |\n`/api/tags` |\nGET | List installed models |\n`/api/ps` |\nGET | List models currently loaded in memory |\n`/api/pull` |\nPOST | Download a model |\n\nCheck the server with `curl http://localhost:11434/api/version`\n\n.\n\nUse `/api/generate`\n\nfor a single prompt with no history:\n\n```\ncurl http://localhost:11434/api/generate -d '{\n  \"model\": \"llama3.1\",\n  \"prompt\": \"Summarize in one sentence: Ollama serves a local HTTP API on port 11434.\",\n  \"stream\": false\n}'\n```\n\nUse `/api/chat`\n\nfor turn-by-turn context or tool calling. Pass a `messages`\n\narray with `role`\n\nvalues of `system`\n\n, `user`\n\n, `assistant`\n\n, or `tool`\n\n, and send the whole history on each request:\n\n```\ncurl http://localhost:11434/api/chat -d '{\n  \"model\": \"llama3.1\",\n  \"messages\": [\n    {\"role\": \"system\", \"content\": \"You answer in one short sentence.\"},\n    {\"role\": \"user\", \"content\": \"What is the KV cache?\"}\n  ],\n  \"stream\": false\n}'\n```\n\nFor application code, `/api/chat`\n\nis the better default even for single questions.\n\nBy default `stream`\n\nis `true`\n\n, and Ollama returns one JSON object per chunk. The final chunk has `\"done\": true`\n\nplus timing data:\n\n```\n{\"model\":\"llama3.1\",\"response\":\"\",\"done\":true,\n \"total_duration\":4883583458,\"prompt_eval_count\":26,\n \"eval_count\":298,\"eval_duration\":3789981000}\n```\n\nAll durations are in nanoseconds. Tokens per second is `eval_count / eval_duration * 1e9`\n\n. Set `\"stream\": false`\n\nfor a single response object.\n\nThe `options`\n\nobject tunes sampling and context per request:\n\n```\ncurl http://localhost:11434/api/chat -d '{\n  \"model\": \"llama3.1\",\n  \"messages\": [{\"role\": \"user\", \"content\": \"Name three container runtimes.\"}],\n  \"stream\": false,\n  \"options\": {\"temperature\": 0.2, \"num_ctx\": 8192, \"num_predict\": 200, \"seed\": 42, \"stop\": [\"\\n\\n\"]}\n}'\n```\n\n`temperature`\n\n— lower is more deterministic`num_ctx`\n\n— context window in tokens for this request`num_predict`\n\n— cap on generated tokens`seed`\n\n— with `temperature: 0`\n\n, gives repeatable output`stop`\n\n— strings that end generationSetting `num_ctx`\n\nabove what your hardware holds forces a partial CPU offload. Confirm with `ollama ps`\n\n.\n\nSet `format`\n\nto `\"json\"`\n\nfor any valid JSON, or pass a JSON schema object to force a shape:\n\n```\ncurl http://localhost:11434/api/chat -d '{\n  \"model\": \"llama3.1\",\n  \"messages\": [{\"role\": \"user\", \"content\": \"List two Linux distros with release years. Respond in JSON.\"}],\n  \"stream\": false,\n  \"format\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"distros\": {\"type\": \"array\", \"items\": {\n        \"type\": \"object\",\n        \"properties\": {\"name\": {\"type\": \"string\"}, \"year\": {\"type\": \"integer\"}},\n        \"required\": [\"name\", \"year\"]\n      }}\n    },\n    \"required\": [\"distros\"]\n  }\n}'\n```\n\nKeep the word \"JSON\" in the prompt and use a low temperature.\n\n`/api/chat`\n\nsupports function calling through a `tools`\n\narray. The model replies with a `tool_calls`\n\nentry instead of text when it decides to use one:\n\n```\ncurl http://localhost:11434/api/chat -d '{\n  \"model\": \"llama3.1\",\n  \"messages\": [{\"role\": \"user\", \"content\": \"What is the weather in Toronto?\"}],\n  \"stream\": false,\n  \"tools\": [{\n    \"type\": \"function\",\n    \"function\": {\n      \"name\": \"get_weather\",\n      \"description\": \"Get the current weather for a city\",\n      \"parameters\": {\"type\": \"object\", \"properties\": {\"city\": {\"type\": \"string\"}}, \"required\": [\"city\"]}\n    }\n  }]\n}'\n```\n\nRun the function, then send the result back as a message with `\"role\": \"tool\"`\n\n. Tool support depends on the model.\n\nInstall with `pip install ollama`\n\n.\n\n``` python\nfrom ollama import chat\n\nresponse = chat(model='llama3.1', messages=[\n    {'role': 'user', 'content': 'Why is the sky blue?'},\n])\nprint(response.message.content)\n```\n\nStreaming:\n\n``` python\nfrom ollama import chat\n\nstream = chat(model='llama3.1',\n    messages=[{'role': 'user', 'content': 'Explain the KV cache in two sentences.'}],\n    stream=True)\nfor chunk in stream:\n    print(chunk['message']['content'], end='', flush=True)\n```\n\nRemote host:\n\n``` python\nfrom ollama import Client\nclient = Client(host='http://192.168.1.50:11434')\n```\n\nThere is an `AsyncClient`\n\nwith the same methods, plus `embed()`\n\n, `list()`\n\n, `ps()`\n\n, and `pull()`\n\n.\n\nOllama serves an OpenAI-style API at `http://localhost:11434/v1`\n\nwith `/v1/chat/completions`\n\n, `/v1/completions`\n\n, `/v1/embeddings`\n\n, and `/v1/models`\n\n:\n\n``` python\nfrom openai import OpenAI\n\nclient = OpenAI(base_url='http://localhost:11434/v1', api_key='ollama')\nresponse = client.chat.completions.create(\n    model='llama3.1',\n    messages=[{'role': 'user', 'content': 'Hello'}],\n)\nprint(response.choices[0].message.content)\n```\n\nThe `api_key`\n\nis required by the SDK but ignored by Ollama. Use `/v1`\n\nfor compatibility and `/api`\n\nfor full features.\n\nThe Ollama API has no built-in authentication. Anyone who can reach port `11434`\n\ncan use, pull, or delete your models. Keep it bound to `127.0.0.1`\n\nand put a reverse proxy in front with auth and TLS:\n\n```\nserver {\n    listen 443 ssl;\n    server_name ollama.example.com;\n    location / {\n        proxy_pass http://127.0.0.1:11434;\n        proxy_set_header Host localhost:11434;\n        auth_basic \"Ollama\";\n        auth_basic_user_file /etc/nginx/.htpasswd;\n    }\n}\n```\n\nSetting `OLLAMA_HOST=0.0.0.0`\n\nwithout a proxy puts an unauthenticated model server on the open network. Only do that inside a private network or behind an IP-restricted firewall.\n\n**Q: What port does the Ollama API use?**\n\nA: Port `11434`\n\non `127.0.0.1`\n\nby default. Change it with `OLLAMA_HOST`\n\n, for example `OLLAMA_HOST=0.0.0.0:11434`\n\n.\n\n**Q: Does the Ollama API need an API key?**\n\nA: No, not for local use. Ollama's hosted cloud models use a key; self-hosted remote access should sit behind a reverse proxy that adds authentication.\n\n**Q: What is the difference between /api/generate and /api/chat?**\n\nA: `/api/generate`\n\ntakes a single `prompt`\n\nstring. `/api/chat`\n\ntakes a `messages`\n\narray with roles and supports tool calling. Use `/api/chat`\n\nfor application code.\n\n**Q: How do I get JSON output from the Ollama API?**\n\nA: Set `format`\n\nto `\"json\"`\n\nor to a JSON schema object. Keep the word \"JSON\" in your prompt and use a low temperature.\n\n**Q: Can I use the OpenAI Python SDK with Ollama?**\n\nA: Yes. Point `base_url`\n\nat `http://localhost:11434/v1`\n\nand pass any non-empty `api_key`\n\n.", "url": "https://wpnews.pro/news/ollama-api-a-practical-guide-with-examples", "canonical_source": "https://dev.to/amareswer/ollama-api-a-practical-guide-with-examples-4di9", "published_at": "2026-09-04 11:35:17+00:00", "updated_at": "2026-09-04 11:54:21.046424+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools", "large-language-models"], "entities": ["Ollama", "llama3.1"], "alternates": {"html": "https://wpnews.pro/news/ollama-api-a-practical-guide-with-examples", "markdown": "https://wpnews.pro/news/ollama-api-a-practical-guide-with-examples.md", "text": "https://wpnews.pro/news/ollama-api-a-practical-guide-with-examples.txt", "jsonld": "https://wpnews.pro/news/ollama-api-a-practical-guide-with-examples.jsonld"}}