# Curl & HTTP mit Unsloth verbinden

Unsloth stellt drei OpenAI-/Anthropic-kompatible Wire-Formate unter derselben Basis-URL auf dem Port bereit, auf dem Unsloth gestartet wurde. Alle nehmen ein `Authorization: Bearer sk-unsloth-…` Header entgegen 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.

{% hint style="info" %}
Wenn du dir nicht sicher bist, welche URL / welcher Schlüssel / welcher 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.
{% endhint %}

### 🔑 Authentifizierung

Jede Anfrage benötigt ein `Authorization` Header:

```
Authorization: Bearer sk-unsloth-xxxxxxxxxxxx
```

Um Schlüssel aus dem Shell-Verlauf herauszuhalten, exportiere den Schlüssel einmal und verwende die Umgebungsvariable:

```bash
export UNSLOTH_STUDIO_AUTH_TOKEN=sk-unsloth-xxxxxxxxxxxx
```

Die folgenden Snippets betten den Schlüssel zur besseren Lesbarkeit direkt ein als `sk-unsloth-xxxxxxxxxxxx` . In der Praxis ersetze `$UNSLOTH_STUDIO_API_KEY`.

### 📋 Geladene Modelle auflisten

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

Antwort:

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

<figure><img src="/files/273071e49d1a5fe747d6bf65d6a0967cfd241fb6" alt=""><figcaption></figcaption></figure>

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 größte Kompatibilitätsfläche. Funktioniert mit dem OpenAI SDK, opencode, Cursor, Continue, Cline, Open WebUI, SillyTavern und den meisten OpenAI-kompatiblen Tools.

#### Einfache Anfrage

```bash
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"}]
  }'
```

<figure><img src="/files/74a7a5c51db386bc36ea40eed7b9ca4da2befe8c" alt=""><figcaption></figcaption></figure>

#### Streaming

Füge `"stream": true` hinzu und die Antwort wechselt zu Server-Sent Events (`text/event-stream`). Weise `curl` an, bei eintreffenden Bytes zu spülen mit `--no-buffer` (`-N`):

```bash
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 aus wie `data: {"choices":[{"delta":{"content":"..."}}]}`, endend mit `data: [DONE]`.

<figure><img src="/files/b55034fd03a70c4adac993658b4a781096da8704" alt=""><figcaption></figcaption></figure>

#### Bilder (Vision)

Füge ein Bild als `image_url` Content-Teil in der Benutzernachricht an. Die URL kann HTTPS oder eine Base64- `data:` URI sein:

```bash
# Bette eine lokale Datei als Base64 ein (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
```

{% hint style="info" %}
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.
{% endhint %}

<figure><img src="/files/f78926fb91191f1c84b658078763003ebb9055cc" alt=""><figcaption></figcaption></figure>

#### Funktionsaufrufe (OpenAI-Tools)

Übergib OpenAI-ähnliche `tools` und optional `tool_choice`. Dein Client führt jeden Tool-Aufruf aus und gibt das Ergebnis im nächsten Durchlauf zurück.

```bash
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":"Erhalte das aktuelle Wetter für eine Stadt.",
      "parameters":{
        "type":"object",
        "properties":{"city":{"type":"string"}},
        "required":["city"]
      }
    }],
    "tool_choice":"required"
  }' | jq '.output, .usage'
```

<figure><img src="/files/505f03570f222831f0ff012179e644c18757c001" alt=""><figcaption></figcaption></figure>

### 📨 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

```bash
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"}]
  }'
```

{% hint style="warning" %}
`max_tokens` ist erforderlich bei `/v1/messages` (es ist optional bei `/v1/chat/completions`).
{% endhint %}

<figure><img src="/files/f4ec9b6793116cbbf9304647dc11731700e7c005" alt=""><figcaption></figcaption></figure>

#### Streaming

```bash
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
  }'
```

Ereignisse folgen der SSE-Form 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-Ausgabe.

#### Bilder (Vision)

Anthropic-ähnlicher Bildinhalt verwendet einen `source` Block mit Base64-Daten:

```bash
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
```

<figure><img src="/files/20821d295fa9462e747b09ae4a6c4ff0d4dd36b7" alt=""><figcaption></figcaption></figure>

#### Tool-Aufrufe (Anthropic-Tools)

```bash
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": "Erhalte das aktuelle Wetter für eine Stadt",
        "input_schema": {
          "type": "object",
          "properties": {
            "city": {"type": "string"}
          },
          "required": ["city"]
        }
      }
    ],
    "tool_choice": {"type": "auto"}
  }'
```

`tool_choice` Werte werden wie folgt in 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`.

<figure><img src="/files/691b46d34ede50df04b8cac38b1e0ed0af2891e3" alt=""><figcaption></figcaption></figure>

### 🧬 Responses (`/v1/responses`)

Unsloth spricht auch die neuere **OpenAI Responses API**, das Protokoll, zu dem Codex und andere jüngere OpenAI-Clients gewechselt sind.

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

<figure><img src="/files/c1b70cf9e8723b7c471aceb72a3ab81ad4b676de" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/a171c9a06d419b76a75d11e855ee49fc7cc9df4e" alt=""><figcaption></figcaption></figure>

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

### 🧰 Unsloth-Server-Tools (Kurzform)

Zusätzlich zum clientseitigen Funktionsaufruf kann Unsloth **Python**, **bash**und **Websuche** serverseitig ausführen und die Ergebnisse als benutzerdefinierte `tool_result` Ereignisse zurückstreamen. Das ist die Funktion, die Unsloth sofort wie einen „echten“ Agenten erscheinen 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 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-Status (z. B. Python-Kernel) über Aufrufe hinweg bei.    |

#### Thinking-Modus

Der Thinking-Modus ist standardmäßig aktiviert.&#x20;

```bash
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 Quantentunneln in einem Satz zusammen"}],
    "stream": false,
  }'
```

Das Modell wird nachdenken, bevor es eine Antwort gibt.

<figure><img src="/files/6a704c2c9f78c37571f7d94df0189cc1346d910f" alt=""><figcaption></figcaption></figure>

Um das Denken zu deaktivieren, übergebe `enable_thinking: false` in deiner Anfrage. Das Modell wird eine Antwort geben, ohne vorher zu denken.

<figure><img src="/files/c057da1ba288cb2eb54e08d89fc656b1e2d117f3" alt=""><figcaption></figcaption></figure>

#### Python-Ausführung

```bash
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? Verwende Code, um es zu berechnen."}],
    "stream": false,
    "enable_tools": true,
    "enabled_tools": ["python"],
    "session_id": "my-session"
  }'
```

<figure><img src="/files/fa92f044fc11810c2a209edb5254db7c71ab3307" alt=""><figcaption></figcaption></figure>

#### Websuche + Python (Streaming)

```bash
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"
  }'
```

<figure><img src="/files/a7b84f5dcbb327cc2ea60c9d3d58ea6fbb996ed2" alt=""><figcaption></figcaption></figure>

#### Unter `/v1/messages`

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

```bash
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"
  }'
```

<figure><img src="/files/48bdf1910f6a6e40e5e1aec9156255ad1b549285" alt=""><figcaption></figcaption></figure>

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

### ❔ Fehlerbehebung

**`401 Nicht autorisiert`** **-** Der `Authorization` Header fehlt oder der Schlüssel ist falsch. Überprüfe Folgendes: `Authorization: Bearer sk-unsloth-…`.

**`curl` hängt bei Streaming-Anfragen -** Füge `-N` (genauso wie `--no-buffer`). Ohne ihn `curl` puffert die SSE-Übertragung und du siehst nichts bis zum Ende.

**Base64-Kodierung unterscheidet sich zwischen Betriebssystemen** **-** Unter Linux ist `base64` standardmäßig auf Zeilenumbruch eingestellt, macOS / BSD nicht. Verwende `base64 -w 0` unter Linux, `base64` unter macOS, oder leite die Ausgabe weiter durch `tr -d '\n'`.

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

**`max_tokens` Fehler bei `/v1/messages`** **-** Der Anthropic-Dialekt verlangt 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 getrennt, falscher Port) siehe die Seite mit der API-Übersicht.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://unsloth.ai/docs/de/integrationen/curl-and-http-mit-unsloth-verbinden.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.