Chat Completions

Endpunkt: POST /v1/chat/completions. Request und Response entsprechen exakt der OpenAI-Chat-Completions-API — einschließlich Streaming und der optionalen Felder tool_calls / reasoning_tokens.

Einfacher Aufruf

resp = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[
        {"role": "system", "content": "You are a senior staff engineer."},
        {"role": "user", "content": "Pros and cons of postgres LISTEN/NOTIFY for a job queue?"},
    ],
    max_tokens=800,
)
print(resp.choices[0].message.content)

Parameter

Alle standardmäßigen OpenAI-Parameter werden akzeptiert. Einige sind nur für bestimmte Anbieter sinnvoll — der Übersetzer leitet die jeweils vom Upstream unterstützten Parameter weiter.

Streaming

Setzen Sie stream=True. Kunavo gibt Server-Sent Events exakt im OpenAI-Format aus: Jeder Chunk ist ein chat.completion.chunk mit choices[0].delta.content. Die abschließende Nutzungsangabe wird mit data: [DONE] übermittelt.

stream = client.chat.completions.create(
    model="claude-haiku-4-5",
    messages=[{"role": "user", "content": "Explain B-trees in one paragraph."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Tool- / Function-Aufrufe

Tool-Aufrufe funktionieren über alle Anbieter hinweg. Definieren Sie Tools als JSON-Schema. Das Modell gibt in seiner Nachricht tool_calls zurück. Sie führen die Tools aus und senden die Ergebnisse als role: "tool"-Nachrichten zurück.

tools = [{
    "type": "function",
    "function": {
        "name": "get_current_weather",
        "description": "Get current weather for a city",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string"},
                "unit": {"type": "string", "enum": ["c", "f"]},
            },
            "required": ["city"],
        },
    },
}]

resp = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
    tools=tools,
    tool_choice="auto",
)

# Inspect tool calls the model wants to make
for call in resp.choices[0].message.tool_calls or []:
    print(call.function.name, call.function.arguments)

JSON-Ausgabe (response_format)

response_format fordert JSON an. Was damit garantiert wird, hängt von der Modellfamilie ab, da die Anfrage für jede Familie in einen anderen Upstream-Mechanismus übersetzt wird:

import json

resp = client.chat.completions.create(
    model="claude-haiku-4-5",
    messages=[{"role": "user", "content": "Jane Doe <jane@example.com> wants the Pro plan."}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "signup",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "email": {"type": "string"},
                    "plan": {"type": "string", "enum": ["free", "pro", "enterprise"]},
                },
                "required": ["name", "email", "plan"],
                "additionalProperties": False,
            },
        },
    },
)
signup = json.loads(resp.choices[0].message.content)  # constrained to the schema

Bei Claude sind vier Dinge zu beachten:

• Das Schema wird fast genau so an Anthropic übermittelt, wie Sie es geschrieben haben. Anthropic verlangt bei Objekten additionalProperties: false. Kunavo fügt es daher jedem Objekt mit aufgeführten Properties hinzu und lässt es bei Objekten ohne Properties weg — so erzeugt es Pydantics model_json_schema(). Anthropic weist Folgendes weiterhin mit einem 400-Fehler zurück, der das Problem benennt: ein offenes Objekt (additionalProperties hat einen anderen Wert als false oder es sind keine Properties aufgeführt und additionalProperties ist nicht gesetzt) sowie oneOf — verwenden Sie anyOf. Die übrigen Einschränkungen sind auf der Seite Strukturierte Ausgaben von Anthropic aufgeführt.
• strict und name werden ignoriert: Anthropic erzwingt jedes akzeptierte Schema, unabhängig davon, ob es als strict markiert ist.
• Ein Schema kann nicht mit einer abschließenden assistant-Nachricht (einem Prefill) kombiniert werden. Anthropic antwortet mit 400.
• Wenn max_tokens mitten im Objekt ausgeschöpft ist, wird das JSON abgeschnitten und finish_reason ist "length".

Vision- / multimodale Eingabe

Modelle mit der Fähigkeit vision akzeptieren Bildinhaltsblöcke. Verwenden Sie entweder eine HTTPS-URL oder einen data:-Base64-URI.

# Pass an image URL or a base64 data URI as part of a multimodal message
resp = client.chat.completions.create(
    model="claude-haiku-4-5",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What's in this image?"},
            {"type": "image_url", "image_url": {
                "url": "https://example.com/cat.jpg"
            }},
        ],
    }],
)
print(resp.choices[0].message.content)

Der Katalog enthält Vision-fähige Modelle, darunter Claude Opus 5.5 — die übrigen finden Sie in der Modellliste.

Bei einem HTTPS-Bild lädt Kunavo die Datei selbst herunter und übergibt sie dem Modell inline, da manche Upstreams eine unverarbeitete Bild-URL ignorieren. Beschränkungen: 16 Bilder pro Anfrage, 5 MB pro Bild, insgesamt 20 MB und 10 Sekunden pro Download. Kann ein Bild nicht abgerufen werden, wird ein Fehler zurückgegeben, der es benennt, statt es zu überspringen.

Schlussfolgern

Die Wirkung einer Reasoning-Steuerung an diesem Endpunkt hängt von der Modellfamilie ab, da die Anfrage jeder Familie in eine andere Upstream-API übersetzt wird:

# GPT models: reasoning_effort is forwarded as the Responses API's
# reasoning.effort. Reasoning tokens are part of completion_tokens.
resp = client.chat.completions.create(
    model="gpt-6-sol",
    messages=[{"role": "user", "content": "Plan a 3-week MLOps migration."}],
    reasoning_effort="high",
)
details = resp.usage.completion_tokens_details   # absent when no reasoning ran
print(details.reasoning_tokens if details else 0)

Prompt-Caching

Ein langer System-Prompt, ein Referenzdokument, ein Few-Shot-Block – jeder stabile Präfix kann vorgelagert zwischengespeichert und bei späteren Aufrufen zu einem Bruchteil des Eingabepreises wiederverwendet werden. Cache-Treffer werden im Nutzungsobjekt als prompt_tokens_details.cached_tokens ausgewiesen.

GPT-Modelle cachen automatisch – eine Änderung an der Anfrage ist nicht erforderlich. cached_tokens ist eine Teilmenge von prompt_tokens und wird zu einem reduzierten Cache-Lesetarif abgerechnet.

Claude cacht nur bis zu einem cache_control-Breakpoint, und bei einem langen Prompt setzt dieser Endpunkt die Breakpoints für Sie: am System-Prompt, an den Tool-Definitionen und an der letzten Nachricht, sobald die Unterhaltung eine Assistentenantwort enthält. Um das Präfix selbst zu wählen, fügen Sie cache_control wie unten an einen Inhaltsblock an; Kunavo behält Ihre Breakpoints bei und fügt eigene nur an Positionen hinzu, die Sie frei gelassen haben:

# Claude caches prefixes you mark with cache_control. Attach it to a content
# block; later calls reusing that prefix read it at ~10% of the input price.
resp = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": LONG_DOCUMENT,            # the stable, reused prefix
                "cache_control": {"type": "ephemeral"},
            },
            {"type": "text", "text": "Summarize the document above."},
        ],
    }],
)
print(resp.usage.prompt_tokens_details.cached_tokens)

Nutzungsobjekt

Jede Antwort (und der letzte Streaming-Chunk) enthält ein usage-Objekt:

Ollama-OpenAI-Kompatibilität — /v1/chat/completions

Ollama stellt seine lokalen Modelle über eine OpenAI-kompatible API unter http://localhost:11434/v1 bereit und implementiert denselben /chat/completions-Vertrag, der auf dieser Seite dokumentiert ist. Dadurch sind beide auf Client-Seite austauschbar: Alles, was für Ollamas v1-API geschrieben wurde, funktioniert auch mit Kunavo, wenn Sie die Basis-URL und das Modell ändern.

from openai import OpenAI

# Before — Ollama's OpenAI-compatible API, local models
client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama",                       # ignored locally
)
resp = client.chat.completions.create(
    model="llama3.2",
    messages=[{"role": "user", "content": "Summarize this changelog."}],
)

# After — the same call against hosted frontier models.
# Two lines changed. Everything below them is untouched.
client = OpenAI(
    base_url="https://api.kunavo.com/v1",   # <- was localhost:11434/v1
    api_key=os.environ["KUNAVO_API_KEY"],
)
resp = client.chat.completions.create(
    model="claude-sonnet-5",  # <- was llama3.2
    messages=[{"role": "user", "content": "Summarize this changelog."}],
)

Die Dinge, die bei einem Anbieterwechsel üblicherweise Probleme bereiten, funktionieren hier, weil das Drahtformat identisch ist:

Nächste Schritte

• Native Anthropic Messages API
• Referenz zur Bildgenerierung
• So funktioniert die Abrechnung (Tokenpreise, Aufschlag)
• Ollamas OpenAI-kompatible API – und der Wechsel zu gehosteten Modellen
• Alle Chat-Modelle ansehen