> For the complete documentation index, see [llms.txt](https://unsloth.ai/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://unsloth.ai/docs/de/integrationen/curl-and-http-mit-unsloth-verbinden.md).

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

{% 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 Schritt für Schritt 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 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:

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

```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 breiteste Kompatibilitätsoberflä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": "Hello"}]
  }'
```

<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`). Sage `curl` 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": "Write a haiku about locally-run LLMs."}],
    "stream": true
  }'
```

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

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

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

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

{% 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)

Ü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.

```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":"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'
```

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

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

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

{% 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": "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:

```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://localhost/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": "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`.

<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 neuere 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": "Write a one-sentence greeting."
  }'
```

<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 mit `-N`.

### 🧰 Unsloth-Server-seitige 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. 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.&#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": "summarize quantum tunneling in one sentence"}],
    "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 liefern, ohne vorher nachzudenken.

<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": "What is 123 * 456? Use code to compute it."}],
    "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": "Search for Python 3.13 features"}],
    "stream": true,
    "enable_tools": true,
    "enabled_tools": ["web_search", "python"],
    "session_id": "my-session"
  }'
```

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

#### Bei `/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": "Search for Python 3.13 features"}],
    "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 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`.

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

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

```bash
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_tokens`und `stream` überschreiben die Server-Standardeinstellungen für diese Anfrage.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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