curl und HTTP mit Unsloth verbinden

Leitfaden für den Zugriff auf Unsloths API mit curl (oder jedem anderen HTTP-Client), inklusive kopierbarer Beispiele 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 von ihnen verwenden ein Authorization: Bearer sk-unsloth-… Header und geben je nach Einstellung entweder JSON oder SSE zurück, stream. Diese Seite gruppiert die Rezepte nach Endpunkt (/v1/chat/completions, /v1/messages, /v1/responses, /v1/models) und endet mit einem gemeinsamen Abschnitt über die integrierten serverseitigen Tools, die über alle Chat-Endpunkte hinweg funktionieren.

Wenn du dir nicht sicher bist, welche URL / welcher Schlüssel / welcher Modellname verwendet werden soll, lies zuerst die API-Übersicht. Dort wirst du Schritt für Schritt 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 herauszuhalten, exportiere den Schlüssel einmal und verweise dann auf die Umgebungsvariable:

export UNSLOTH_STUDIO_AUTH_TOKEN=sk-unsloth-xxxxxxxxxxxx

Die folgenden Snippets betten den Schlüssel der Klarheit halber direkt als sk-unsloth-xxxxxxxxxxxx ein. In der Praxis ersetze $UNSLOTH_STUDIO_AUTH_TOKEN.

📋 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 Model-ID).

💬 Chat-Completions (/v1/chat/completions)

Der OpenAI-Chat-Completions-Dialekt. Die breiteste Kompatibilitätsoberflä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": "Hello"}]
  }'

Streaming

Füge "stream": true hinzu und die Antwort wechselt zu Server-Sent Events (text/event-stream). Sage curl 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": "Write a haiku about locally-run LLMs."}],
    "stream": true
  }'

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

Bilder (Vision)

Hänge ein Bild als image_url Content-Teil in der Nutzermeldung an. Die URL kann HTTPS oder eine Base64- data: URI sein:

# Lokale Datei als Base64 einbetten (der Kürze halber 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-stilistische tools und (optional) tool_choice. Dein Client führt jeden Tool-Aufruf aus und gibt das Ergebnis im nächsten Durchlauf zurück.

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":"What is the weather in Paris?"}],
    "tools":[{
      "type":"function",
      "function":{
        "name":"get_weather",
        "description":"Get current weather for a city.",
        "parameters":{
          "type":"object",
          "properties":{"city":{"type":"string"}},
          "required":["city"]
        }
      }
    }],
    "tool_choice":"required"
  }' | jq '.choices[0].message, .usage'

📨 Anthropic Messages (/v1/messages)

Unsloths Anthropic-kompatibler Dialekt, der von Claude Code, dem Anthropic SDK, OpenClaw und jedem Client verwendet wird, 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": "Hello"}]
  }'

max_tokens ist erforderlich bei /v1/messages (es 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": "Explain LoRA in two sentences."}],
    "stream": true
  }'

Ereignisse folgen der SSE-Struktur von Anthropic: message_start, content_block_start, content_block_delta, content_block_stop, message_delta, message_stop, plus Unsloths benutzerdefiniertes tool_result Ereignis für serverseitige Tool-Ausgabe.

Bilder (Vision)

Anthropic-artiger Bildinhalt verwendet 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://localhost/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": "Whats the weather in Tokyo?"}],
    "tools": [
      {
        "name": "get_weather",
        "description": "Get the current weather for a city",
        "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 spricht auch die neuere OpenAI Responses API, das Protokoll, zu dem Codex und andere neuere 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": "Write a one-sentence greeting."
  }'

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

🧰 Unsloth-Server-seitige Tools (Kurzform)

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

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

Feld	Typ	Hinweise
enable_thinking	boolean	false um das Denken 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. Behält den Tool-Zustand (z. B. Python-Kernel) über Aufrufe hinweg bei.

Denken-Modus

Der Denken-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": "summarize quantum tunneling in one sentence"}],
    "stream": false
  }'

Das Modell wird nachdenken, bevor es eine Antwort gibt.

Um das Denken zu deaktivieren, übergebe enable_thinking: false in deiner Anfrage. Das Modell wird eine Antwort liefern, ohne vorher 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": "What is 123 * 456? Use code to compute it."}],
    "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": "Search for Python 3.13 features"}],
    "stream": true,
    "enable_tools": true,
    "enabled_tools": ["web_search", "python"],
    "session_id": "my-session"
  }'

Bei /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": "Search for Python 3.13 features"}],
    "stream": true,
    "enable_tools": true,
    "enabled_tools": ["web_search", "python"],
    "session_id": "my-session"
  }'

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

❔ Fehlerbehebung

401 Nicht autorisiert - Das Authorization Header fehlt oder der Schlüssel ist falsch. Prüfe Folgendes: 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 - Das base64 unter Linux bricht standardmäßig Zeilen um, 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 verlangt dies. Füge "max_tokens": 1024 hinzu (oder welches Limit du auch immer möchtest).

Bei Problemen auf Endpunktebene (Modell lädt nicht, Verbindung getrennt, falscher Port) siehe die Seite mit der API-Übersicht.

Optional: Server-Standardeinstellungen anpassen

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

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

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

# 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 andere Geräte in deinem lokalen Netzwerk verbinden können.

Einstellungen pro Anfrage überschreiben

Du kannst Generierungseinstellungen auch 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": "Write a short poem about local AI."
      }
    ],
    "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.