Curl & HTTP mit Unsloth verbinden

Leitfaden, um Unsloths API mit curl (oder jedem HTTP-Client) anzusprechen, komplett mit kopierbaren Rezepten für jeden Endpunkt und jede Funktion.

Unsloth stellt drei OpenAI/Anthropic-kompatible Wire-Formate unter derselben Basis-URL auf dem Port bereit, auf dem Unsloth gestartet wurde. Alle verwenden einen Authorization: Bearer sk-unsloth-… Header und geben je nach Einstellung von stream entweder JSON oder SSE zurück. Diese Seite gruppiert die Rezepte nach Endpunkt (/v1/chat/completions, /v1/messages, /v1/responses, /v1/models) und endet mit einem gemeinsamen Abschnitt über Unsloths integrierte serverseitige Tools, die über alle Chat-Endpunkte hinweg funktionieren.

Wenn du dir nicht sicher bist, welche URL / welcher Schlüssel / Modellname verwendet werden soll, lies zuerst die API-Übersicht. Dort wirst du durch das Starten von Unsloth, das Laden eines Modells und das Erstellen eines sk-unsloth-… Schlüssels geführt.

🔑 Authentifizierung

Jede Anfrage benötigt einen Authorization -Header:

Authorization: Bearer sk-unsloth-xxxxxxxxxxxx

Um Schlüssel aus deinem Shell-Verlauf fernzuhalten, exportiere den Schlüssel einmal und verweise dann auf die Umgebungsvariable:

export UNSLOTH_STUDIO_AUTH_TOKEN=sk-unsloth-xxxxxxxxxxxx

Die Snippets unten binden den Schlüssel der Klarheit halber direkt als sk-unsloth-xxxxxxxxxxxx ein. In der Praxis ersetzt du $UNSLOTH_STUDIO_API_KEY.

📋 Geladene Modelle auflisten

curl http://localhost:8888/v1/models \\
  -H "Authorization: Bearer sk-unsloth-xxxxxxxxxxxx"

Antwort:

{
  "object": "list",
  "data": [
    {"id": "unsloth/gemma-3-27b-it-GGUF", "object": "model", "owned_by": "local"}
  ]
}

Verwende das id -Feld immer dann, wenn eine Anfrage einen "model" -Wert benötigt (oder wenn ein Client wie opencode nach einer Modell-ID).

💬 Chat Completions (/v1/chat/completions)

Der OpenAI-Chat-Completions-Dialekt. Die breiteste Kompatibilitätsfläche. Funktioniert mit dem OpenAI SDK, opencode, Cursor, Continue, Cline, Open WebUI, SillyTavern und den meisten OpenAI-kompatiblen Tools.

Einfache Anfrage

curl http://localhost:8888/v1/chat/completions \\
  -H "Authorization: Bearer sk-unsloth-xxxxxxxxxxxx" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "default",
    "messages": [{"role": "user", "content": "Hallo"}]
  }'

Streaming

Füge "stream": true hinzu, und die Antwort wechselt zu Server-Sent Events (text/event-stream ). Sag curl an, beim Eintreffen von Bytes mit --no-buffer (-N):

curl -N http://localhost:8888/v1/chat/completions \\
  -H "Authorization: Bearer sk-unsloth-xxxxxxxxxxxx" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "qwen-local",
    "messages": [{"role": "user", "content": "Schreibe ein Haiku über lokal ausgeführte LLMs."}],
    "stream": true
  }'

Jede Zeile der Antwort sieht so aus wie data: {"choices":[{"delta":{"content":"..."}}]} und endet mit data: [DONE].

Bilder (Vision)

Füge ein Bild als image_url -Inhaltsabschnitt in die Benutzernachricht ein. Die URL kann HTTPS oder eine Base64- data: URI sein:

# Lokale Datei als Base64 einbetten (aus Platzgründen gekürzt)
IMG=$(base64 -w 0 test.jpg)

cat > /tmp/request.json <<EOF
{
  "model":"default",
  "messages":[{"role":"user","content":[
    {"type":"text","text":"Beschreibe das Bild."},
    {"type":"image_url","image_url":{"url":"data:image/jpeg;base64,$IMG"}}
  ]}],
  "max_tokens":200,
  "stream":false
}
EOF

curl http://localhost:8888/v1/chat/completions \\
  -H "Authorization: Bearer sk-unsloth-xxxxxxxxxxxx" \\
  -H "Content-Type: application/json" \\
  -d @/tmp/request.json

Das geladene Modell muss multimodal sein. Wenn du ein reines Textmodell lädst, ist die Anfrage strukturell erfolgreich, aber das Modell verarbeitet das Bild nicht.

Funktionsaufrufe (OpenAI-Tools)

Übergebe OpenAI-artige tools und (optional) tool_choice. Dein Client führt jeden Tool-Aufruf aus und gibt das Ergebnis im nächsten Durchgang zurück.

curl http://localhost:8888/v1/chat/completions \\
  -H "Authorization: Bearer sk-unsloth-xxxxxxxxxxxx" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model":"default",
    "input":[{"role":"user","content":"Wie ist das Wetter in Paris?"}],
    "tools":[{
      "type":"function",
      "name":"get_weather",
      "description":"Aktuelles Wetter für eine Stadt abrufen.",
      "parameters":{
        "type":"object",
        "properties":{"city":{"type":"string"}},
        "required":["city"]
      }
    }],
    "tool_choice":"required"
  }' | jq '.output, .usage'

📨 Anthropic Messages (/v1/messages)

Unsloths Anthropic-kompatibler Dialekt, verwendet von Claude Code, dem Anthropic SDK, OpenClaw und jedem Client, der die Messages-API spricht.

Einfache Anfrage

curl http://localhost:8888/v1/messages \\
  -H "Authorization: Bearer sk-unsloth-xxxxxxxxxxxx" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "default",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hallo"}]
  }'

max_tokens ist erforderlich bei /v1/messages (ist optional bei /v1/chat/completions).

Streaming

curl -N http://localhost:8888/v1/messages \\
  -H "Authorization: Bearer sk-unsloth-xxxxxxxxxxxx" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "qwen-local",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Erkläre LoRA in zwei Sätzen."}],
    "stream": true
  }'

Events folgen der SSE-Struktur von Anthropic: message_start, content_block_start, content_block_delta, content_block_stop, message_delta, message_stop, plus Unsloths benutzerdefiniertem tool_result -Event für serverseitige Tool-Ausgaben.

Bilder (Vision)

Anthropic-artige Bildinhalte verwenden einen source -Block mit Base64-Daten:

IMG=$(base64 -w 0 test.jpg)

cat > /tmp/request.json <<EOF
{
  "messages":[{"role":"user","content":[
    {"type":"text","text":"Beschreibe das Bild."},
    {"type":"image","source":{"type":"base64","media_type":"image/jpeg","data":"$IMG"}}
  ]}],
  "max_tokens":200,
  "stream":true
}
EOF

curl -s http://3.128.175.236:8888/v1/messages \\
  -H "Authorization: Bearer sk-unsloth-xxxxxxxx" \\
  -H "Content-Type: application/json" \\
  -d @/tmp/request.json

Tool-Aufrufe (Anthropic-Tools)

curl http://localhost:8888/v1/messages \\
  -H "Authorization: Bearer sk-unsloth-xxxxxxxxxx" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "qwen-local",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Wie ist das Wetter in Tokio?"}],
    "tools": [
      {
        "name": "get_weather",
        "description": "Das aktuelle Wetter für eine Stadt abrufen",
        "input_schema": {
          "type": "object",
          "properties": {
            "city": {"type": "string"}
          },
          "required": ["city"]
        }
      }
    ],
    "tool_choice": {"type": "auto"}
  }'

tool_choice Werte werden wie folgt auf den OpenAI-Dialekt abgebildet: Anthropic auto → OpenAI auto, Anthropic any → OpenAI required, Anthropic {type: "tool", name: "x"} → OpenAI {type: "function", function: {name: "x"}}, Anthropic none → OpenAI none.

🧬 Responses (/v1/responses)

Unsloth unterstützt auch die neuere OpenAI Responses API, , das Protokoll, zu dem Codex und andere aktuelle OpenAI-Clients gewechselt sind.

curl http://localhost:8888/v1/responses \\
  -H "Authorization: Bearer sk-unsloth-xxxxxxxxxxxx" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "qwen-local",
    "input": "Schreibe eine Begrüßung in einem Satz."
  }'

Streaming funktioniert genauso wie bei Chat Completions. Füge "stream": true hinzu und leite mit -N.

🧰 Unsloth-Server-Tools (Kurzform)

Zusätzlich zum clientseitigen Funktionsaufruf kann Unsloth Python, bashund Websuche serverseitig ausführen und die Ergebnisse als benutzerdefinierte tool_result Events zurückstreamen. Das ist die Funktion, die Unsloth sofort wie einen „echten“ Agenten wirken lässt, ohne Tool-Aufrufe über deinen Client hin- und herzuschicken.

Aktiviere dies, indem du diese zusätzlichen Felder an entweder /v1/chat/completions oder /v1/messages:

Feld	Typ	Hinweise
enable_thinking	boolean	false um Thinking zu deaktivieren. true standardmäßig
enable_tools	boolean	true um die serverseitige Tool-Ausführung zu aktivieren.
enabled_tools	array<string>	Welche Tools das Modell aufrufen kann. Unterstützt python, bash, web_search.
session_id	string	Optional. Persistiert den Tool-Zustand (z. B. den Python-Kernel) über mehrere Aufrufe hinweg.

Thinking-Modus

Der Thinking-Modus ist standardmäßig aktiviert.

curl http://localhost:8888/v1/chat/completions \\
  -H "Authorization: Bearer sk-unsloth-xxxxxxxxxxxx" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "default",
    "messages": [{"role": "user", "content": "Fasse Quanten-Tunneln in einem Satz zusammen"}],
    "stream": false,
  }'

Das Modell wird vor der Antwort nachdenken.

Um Thinking zu deaktivieren, übergebe enable_thinking: false in deiner Anfrage. Das Modell gibt dann eine Antwort, ohne zuerst nachzudenken.

Python-Ausführung

curl http://localhost:8888/v1/chat/completions \\
  -H "Authorization: Bearer sk-unsloth-xxxxxxxxxxxx" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "qwen-local",
    "messages": [{"role": "user", "content": "Was ist 123 * 456? Benutze Code, um es zu berechnen."}],
    "stream": false,
    "enable_tools": true,
    "enabled_tools": ["python"],
    "session_id": "my-session"
  }'

Websuche + Python (Streaming)

curl http://localhost:8888/v1/chat/completions \\
  -H "Authorization: Bearer sk-unsloth-xxxxxx" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "qwen-local",
    "messages": [{"role": "user", "content": "Suche nach Python-3.13-Funktionen"}],
    "stream": true,
    "enable_tools": true,
    "enabled_tools": ["web_search", "python"],
    "session_id": "my-session"
  }'

Ein /v1/messages

Die gleiche Kurzform funktioniert auch gegen den Anthropic-Messages-Endpunkt:

curl http://localhost:8888/v1/messages \\
  -H "Authorization: Bearer sk-unsloth-xxxxxxxxxxx" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "qwen-local",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Suche nach Python-3.13-Funktionen"}],
    "stream": true,
    "enable_tools": true,
    "enabled_tools": ["web_search", "python"],
    "session_id": "my-session"
  }'

Unsloth streamt zusätzlich zu den standardmäßigen Anthropic-/OpenAI-Ereignistypen seine eigenen tool_result SSE-Events. Das Modell sieht die Ausgabe jedes Tools im nächsten Durchgang.

❔ Fehlerbehebung

401 Nicht autorisiert - Der Authorization -Header fehlt oder der Schlüssel ist falsch. Prüfe Folgendes noch einmal: Authorization: Bearer sk-unsloth-….

curl hängt bei Streaming-Anfragen - Füge -N (gleich wie --no-buffer). Ohne ihn curl puffert den SSE-Stream und du siehst bis zum Ende nichts.

Base64-Kodierung unterscheidet sich zwischen Betriebssystemen - Linuxs base64 fügt standardmäßig Zeilenumbrüche ein, macOS / BSD nicht. Verwende base64 -w 0 unter Linux, base64 unter macOS, oder leite die Ausgabe durch tr -d '\n'.

JSON-Escaping in Shells - Heredocs (-d @file.json) sind sauberer als Inline-Strings, sobald der Body komplexer wird. Beispiel: curl ... -d @body.json.

max_tokens Fehler bei /v1/messages - Der Anthropic-Dialekt erfordert es. Füge "max_tokens": 1024 hinzu (oder welches Limit du auch immer möchtest).

Bei Problemen auf Endpunkt-Ebene (Modell lädt nicht, Verbindung unterbrochen, falscher Port) siehe die API-Übersichtsseite.

Optional: Server-Standardeinstellungen anpassen

Du kannst das Standardverhalten beim Starten des Servers mit unsloth run.

# Starte den Server mit benutzerdefinierten Standardwerten
unsloth run \\
  --model unsloth/Qwen3-1.7B-GGUF \\
  --reasoning off \\
  --temp 0.6 \\
  -p 8888

Verwende --reasoning off um Thinking auszuschalten, oder --reasoning on um es für Modelle einzuschalten, die Reasoning unterstützen.

# Die API im lokalen Netzwerk freigeben
unsloth run \\
  --model unsloth/Qwen3-1.7B-GGUF \\
  -H 0.0.0.0 \\
  -p 8888

Dadurch startet der Server auf 0.0.0.0:8888, sodass sich andere Geräte in deinem lokalen Netzwerk verbinden können.

Einstellungen pro Anfrage überschreiben

Du kannst auch Generierungseinstellungen direkt in jeder API-Anfrage überschreiben.

curl http://localhost:8888/v1/chat/completions \\
  -H "Authorization: Bearer $UNSLOTH_STUDIO_AUTH_TOKEN" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "default",
    "messages": [
      {
        "role": "user",
        "content": "Schreibe ein kurzes Gedicht über lokale KI."
      }
    ],
    "temperature": 0.8,
    "top_p": 0.9,
    "max_tokens": 512
  }'

Anfragebezogene Werte wie temperature, top_p, max_tokensund stream überschreiben die Server-Standardeinstellungen für diese Anfrage.