Programmgesteuerter Zugriff auf die Ollama-REST-API

Nach der Installation stellt Ollama eine vollständige REST-API auf dem lokalen Port 11434 bereit, die Textgenerierung, Chat, Vektor-Embeddings und Modellverwaltung sowie zwei kompatible Protokolle abdeckt: OpenAI und Anthropic.

Dieser Artikel erklärt die Kern-APIs einzeln: Anfragestruktur, Streaming-Verarbeitung, Nutzungsstatistiken und Fehlerbehandlung, sodass jede Sprache lokale Modelle integrieren kann.

---

Zwei Basis-URLs und Authentifizierungsmethoden

Die API von Ollama hat zwei Endpunkte: lokal und Cloud, mit unterschiedlichen Authentifizierungsregeln.

Endpunkt	Basis-URL	Authentifizierung
Lokaler Dienst	http://localhost:11434/api	Keine Authentifizierung erforderlich
Lokaler Dienst (kompatibles Protokoll)	http://localhost:11434/v1	Keine Authentifizierung erforderlich, api_key kann beliebig ausgefüllt werden
Ollama Cloud	https://ollama.com/api	Authorization: Bearer + API Key

Lokale Dienste erfordern standardmäßig keine Authentifizierung und funktionieren sofort; wenn Sie direkt eine Verbindung zur Cloud-API von Ollama unter ollama.com herstellen, erstellen Sie zuerst einen API-Schlüssel auf der Einstellungsseite der offiziellen Website und fügen ihn in den Anfrage-Header ein.

---

Textgenerierung: /api/generate

generate ist die grundlegendste Single-Turn-Generierungs-API; übergeben Sie einfach den Modellnamen und den Prompt:

Wenn stream auf false gesetzt ist, wird ein einzelnes JSON-Objekt zurückgegeben:

{
  "model": "qwen3.5",
  "created_at": "2026-08-29T03:20:00.499127Z",
  "response": "Example是一个面向编程初学者的免费中文教程网站。",
  "done": true,
  "total_duration": 10706818083,
  "load_duration": 6338219291,
  "prompt_eval_count": 26,
  "prompt_eval_duration": 130079000,
  "eval_count": 42,
  "eval_duration": 4232710000
}

Übliche Parameter sind wie folgt:

Parameter	Beschreibung
model	Erforderlich, Modellname
prompt	Prompt; kann leer gelassen werden, um das Modell vorab zu laden
stream	Standardmäßig true gibt Streaming zurück; bei false wird das vollständige Ergebnis auf einmal zurückgegeben
system	Vorübergehend einen System-Prompt angeben, der die Einstellung in Modelfile überschreibt
options	Generierungsparameter-Objekt, z. B. temperature, num_ctx (identisch mit Modelfile-Parametern)
format	"json" oder ein vollständiges JSON-Schema, erzwingt strukturierte Ausgabe
keep_alive	Dauer, die das Modell nach der Anfrage im Speicher bleibt, z. B. "10m", -1 für dauerhaften Verbleib, 0 für sofortiges Entladen
raw	Wenn true, wird die Template-Zusammenstellung übersprungen und direkt der vollständige Prompt verwendet, den Sie angeben
suffix	Text, der nach der Modellausgabe angehängt wird, für Textvervollständigungs-Szenarien
images	Base64-Bildarray, verwendet bei multimodalen Modellen

Zwei praktische Tipps: Das Senden eines leeren Prompts kann das Modell in den Speicher vorladen, wodurch die Lade-Wartezeit für die erste Anfrage entfällt; das Setzen von keep_alive auf 0 zusammen mit einem leeren Prompt kann das Modell sofort entladen und VRAM freigeben.

---

Chat-Generierung: /api/chat

chat ist eine API für mehrstufige Konversationen; der Nachrichtenverlauf wird vom Aufrufer verwaltet, was der wesentliche Unterschied zu generate ist.

Vom message-Objekt unterstützte Felder:

Feld	Beschreibung
role	Vier Rollen: system / user / assistant / tool
content	Nachrichteninhalt
images	Optional, base64-Bildliste (multimodale Modelle)
thinking	Optional, der Denkprozess von Thinking-Modellen (wird mit dem think-Parameter verwendet)
tool_calls	Optional: die Liste der Tools, deren Aufruf das Modell anfordert (siehe Abschnitt zum Tool-Aufruf für praktische Übungen)

Der korrekte Weg für eine Multi-Turn-Konversation: Hänge die vom Modell in jeder Runde zurückgegebene Assistant-Nachricht wieder an das messages-Array an und sende sie dann zusammen mit der neuen Frage; das Modell kann sich dann an den vollständigen Kontext „erinnern“.

Da die messages vollständig von dir verwaltet werden, kann der Verlauf in einer Datenbank gespeichert, durch Zusammenfassung komprimiert oder über Sitzungen hinweg wiederhergestellt werden — das in Teil 5 von „Befehlszeilen-Beendigungen verlieren den Speicher“ erwähnte Problem hat hier nun eine technische Lösung.

---

Vektor-Embeddings: /api/embed

Die embed-API wandelt Text in Vektoren um und dient als Rohstoffwerkstatt für RAG und semantische Suche.

Die Embeddings in der Antwort sind ein 2D-Array, wobei jeder Vektor bereits L2-normalisiert (Einheitslänge) ist, sodass die Kosinusähnlichkeit direkt zum Vergleich verwendet werden kann.

Zwei erwähnenswerte Parameter: dimensions kann die Dimension des Ausgabevektors angeben (wenn vom Modell unterstützt, spart eine Reduzierung der Dimensionen Speicherplatz); truncate ist standardmäßig true und kürzt automatisch übermäßig langen Text, und das Setzen auf false führt zu einem Fehler, wenn der Text zu lang ist.

---

Streaming vs. Non-Streaming: Wie man Antworten verarbeitet

Generierungs-APIs geben standardmäßig Streaming zurück, im NDJSON-Format: Jede Zeile ist ein eigenständiges JSON-Objekt.

{"model":"qwen3.5","created_at":"...","response":"EXAMPLE","done":false}
{"model":"qwen3.5","created_at":"...","response":"（Example）","done":false}
{"model":"qwen3.5","created_at":"...","response":"是编程初学者的入门网站。","done":false}
{"model":"qwen3.5","created_at":"...","response":"","done":true,"done_reason":"stop"}

Der Client liest Zeile für Zeile und verkettet die Antwortfelder, um die vollständige Antwort zu bilden; der Verkettungsprozess kann in Echtzeit auf der Oberfläche dargestellt werden.

Abwägungen zwischen den beiden Modi:

Mode	Vorteil	Anwendungsfall
Streaming (Standard)	Geringe Zeit bis zum ersten Token, kann in Echtzeit angezeigt werden	Chat-Oberflächen, Langtextgenerierung
Nicht-Streaming stream:false	Vollständiges Ergebnis auf einmal, einfach zu verarbeiten	Batch-Verarbeitung, strukturierte Ausgabe, Skriptaufrufe

Im Streaming-Modus können Fehler mitten in der Ausgabe auftreten; zu diesem Zeitpunkt kann der HTTP-Statuscode nicht mehr geändert werden. Der Fehler erscheint als Zeile {"error": "..."} am Ende des Datenstroms, und der Client sollte diese Zeile beim Parsen prüfen.

---

Nutzungsstatistiken und Fehlerbehandlung

Jede Generierungsantwort endet mit Feldern für Leistungsstatistiken, die Daten aus erster Hand zur Bewertung des Inferenz-Overheads liefern.

Feld	Bedeutung
total_duration	Gesamte Anfragezeit (Nanosekunden)
load_duration	Modellladezeit (spürbar bei der ersten Anfrage)
prompt_eval_count	Anzahl der durch die Eingabe verbrauchten Tokens
prompt_eval_duration	Verarbeitungszeit der Eingabe
eval_count	Anzahl der durch die Ausgabe generierten Tokens
eval_duration	Zeit für die Ausgabegenerierung

Die Formel für die Generierungsgeschwindigkeit (token/s): eval_count / eval_duration * 10^9; alle Zeiteinheiten sind Nanosekunden.

In Bezug auf die Fehlerbehandlung verwendet die API Standard-HTTP-Statuscodes, um Ergebnisse auszudrücken:

Statuscode	Bedeutung
200	Erfolg
400	Anfragefehler (fehlende Parameter, ungültiges JSON usw.)
404	Modell existiert nicht (führen Sie zuerst ollama pull aus oder überprüfen Sie den Namen)
429	Ratenlimitierung aufgrund zu häufiger Anfragen
500	Interner Serverfehler
502	Gateway-Fehler (z. B. Cloud-Modell nicht erreichbar)

Der Fehlerantworttext ist auf die Struktur {"error": "error description"} festgelegt; Clients können das Feld error einfach einheitlich extrahieren.

---

Überblick über die Modellverwaltungs-API

Die API bietet ein Gegenstück für jede in der Befehlszeile verfügbare Modellverwaltungsoperation, geeignet für den Aufbau von Admin-Dashboards oder Automatisierungsskripten.

Endpunkt	Methode	Zweck
/api/tags	GET	Lokale Modelle auflisten (einschließlich Parameteranzahl, Quantisierungsstufe)
/api/show	POST	Modelldetails, Fähigkeiten, Template anzeigen
/api/pull	POST	Ein Modell pullen, gibt Download-Fortschritt als Stream zurück
/api/push	POST	Modell in die Modellbibliothek pushen
/api/copy	POST	Modell kopieren (Quelle / Ziel)
/api/delete	DELETE	Ein Modell löschen
/api/create	POST	Ein Modell erstellen (einschließlich Quantisierung, entsprechend den Modelfile-Fähigkeiten)
/api/ps	GET	Aktuell geladene Modelle und VRAM-Nutzung anzeigen
/api/version	GET	Ollama-Version abfragen

Am Beispiel von /api/tags enthält die Antwort Spezifikationsdetails für jedes Modell:

{
  "models": [
    {
      "name": "qwen3.5:latest",
      "size": 6600000000,
      "details": {
        "family": "qwen3.5",
        "parameter_size": "9B",
        "quantization_level": "Q4_K_M"
      }
    }
  ]
}

Felder wie quantization_level und parameter_size können direkt verwendet werden, um eine Modellauswahl-Oberfläche zu erstellen.

---

OpenAI-kompatible Schnittstelle

Für bestehende OpenAI-Anwendungen, die auf lokale Modelle umsteigen möchten, muss normalerweise nur eine base_url geändert werden.

Kompatibilität umfasst fünf Endpunkte:

Endpunkt	Beschreibung
/v1/chat/completions	Chat-Vervollständigungen mit Unterstützung für Streaming, Vision, Tools und JSON-Modus
/v1/completions	Text-Vervollständigungen
/v1/responses	Responses-API (zustandsloser Modus)
/v1/embeddings	Vektor-Einbettungen
/v1/models	Modellliste

Beachten Sie zwei häufige Unterschiede:

Erstens kennt das OpenAI-Protokoll kein num_ctx-Konzept. Wenn Sie den Kontext ändern müssen, erstellen Sie zuerst ein Modell mit PARAMETER num_ctx und rufen Sie es dann unter einem neuen Namen auf (Sie können die Modelfile aus Teil 7 verwenden oder mit cp einen Namen ausleihen).

Zweitens werden einige Felder noch nicht unterstützt: tool_choice, logit_bias, n, logprobs usw. Vor der Migration empfiehlt es sich, die Support-Liste des Handbuchs zu prüfen.

---

Anthropic-kompatible Schnittstelle

Ollama bietet außerdem eine Kompatibilitätsschicht für die Anthropic Messages API, mit der Tools wie Claude Code lokale Modelle direkt verwenden können.

Bei der Integration von Tools wie Claude Code müssen Sie nur zwei Umgebungsvariablen festlegen:

Beachten Sie die Fähigkeitsgrenzen: Anthropic-Funktionen wie erzwungenes tool_choice, Prompt-Caching, Batch-Schnittstelle und PDF-Eingabe werden noch nicht unterstützt; die Token-Anzahl ist ungefähr.

Weitere Erweiterungen