> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.deepmask.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat Completions

> Referenz der OpenAI-kompatiblen Endpunkte für Chat Completions und Modelle, einschließlich Anfrageregeln, Sampling-Optionen, Bildeingabe, Streaming und Tool-Aufrufen.

Die DeepMask API ist OpenAI-kompatibel. Chat-Anfragen senden Sie an `POST /v1/chat/completions`, und mit `GET /v1/models` listen Sie die Modelle auf, die Ihr Schlüssel verwenden kann. Da die API dem OpenAI-Format folgt, können Sie die offiziellen OpenAI-SDKs verwenden. Sie ändern dafür nur die Basis-URL und den API-Schlüssel.

DeepMask akzeptiert eine festgelegte Teilmenge der OpenAI-Parameter. Enthält eine Anfrage einen nicht unterstützten Parameter, wird sie abgelehnt, statt ohne diesen Parameter ausgeführt zu werden. Manche Modelle ignorieren einzelne Sampling-Optionen wie `top_p` oder `seed`, ohne einen Fehler zurückzugeben. Siehe [Sampling-Optionen](#sampling-optionen). Für Ihren ersten Aufruf folgen Sie dem [Schnellstart](https://documentation.deepmask.io/de/api/quickstart.md).

> [!NOTE]
>
> Sie benötigen einen API-Schlüssel, den ein Administrator Ihrer Organisation erstellt hat. Außerdem braucht Ihre Organisation einen aktiven Pro-, Power- oder Enterprise-Tarif mit aktivierter API-Abrechnung.

> [!NOTE]
>
> Die Basis-URL lautet `https://api.deepmask.io/v1`. Administratoren der Organisation können sie auch unter **Basis-URL** in **Benutzereinstellungen** > **API** kopieren.

## Endpunkte

| Methode | Pfad | Beschreibung |
| - | - | - |
| `POST` | `/v1/chat/completions` | Erzeugt eine Modellantwort für eine Unterhaltung. |
| `GET` | `/v1/models` | Listet die Modelle auf, die Ihr API-Schlüssel verwenden kann. |

Nur diese beiden Endpunkte sind verfügbar. Andere OpenAI-Endpunkte, darunter Embeddings und Bilderzeugung, werden nicht angeboten.

* **Die meisten anderen Endpunkte:** Pfade wie `/v1/responses`, `/v1/completions` und `/v1/images/generations` geben `404` mit `API_ENDPOINT_NOT_FOUND` zurück. SDK-Methoden, die auf diese Pfade angewiesen sind, funktionieren nicht. Dazu gehören die Responses API (`client.responses`) und `client.models.retrieve()`.
* **Embeddings:** Der Katalog enthält keine Embedding-Modelle. Daher schlägt `client.embeddings.create()` mit einem Zugriffsfehler fehl, meist `403` mit `API_MODEL_NOT_ALLOWED`.

Bei Pfaden wird zwischen Groß- und Kleinschreibung unterschieden. Ein Pfad mit abschließendem Schrägstrich, etwa `/v1/chat/completions/`, gibt ebenfalls `404` zurück.

## Authentifizierung

Senden Sie Ihren API-Schlüssel bei jeder Anfrage als Bearer-Token im Header `Authorization`. `POST`-Anfragen benötigen außerdem einen JSON-Content-Type.

```text theme={null}
Authorization: Bearer sk-...
Content-Type: application/json
```

* Schlüssel beginnen mit `sk-`, gefolgt von 64 hexadezimalen Zeichen in Kleinbuchstaben.
* Senden Sie genau einen `Authorization`-Header. Beim Präfix `Bearer` wird zwischen Groß- und Kleinschreibung unterschieden.
* Bei einem fehlenden, fehlerhaft formatierten, unbekannten oder widerrufenen Schlüssel erhalten Sie `401` mit `API_CREDENTIAL_INVALID`.

Wie Sie Schlüssel erstellen oder widerrufen, erfahren Sie unter [API-Schlüssel](https://documentation.deepmask.io/de/api/keys.md). Die Beispiele auf dieser Seite lesen den Schlüssel aus der Umgebungsvariable `DEEPMASK_API_KEY`.

> [!WARNING]
>
> Bewahren Sie Ihren API-Schlüssel auf Ihrem Server auf. Fügen Sie ihn nicht in den Code einer Browser- oder Mobile-App ein, denn dort kann ihn jede Person lesen, die Ihre App nutzt. Browser blockieren außerdem Aufrufe der API von Ihren eigenen Webseiten (CORS). Rufen Sie die API deshalb aus Ihrem Backend auf.

## Chat Completion erstellen

Diese Anfrage sendet eine Systemnachricht und eine Benutzernachricht an `gpt-4o`. Die Beispiele für Python und Node.js verwenden das offizielle Paket `openai`. Installieren Sie es mit `pip install openai` oder `npm install openai`. Die Node.js-Beispiele verwenden ES-Module. Speichern Sie sie daher als `.mjs`-Dateien oder setzen Sie `"type": "module"` in `package.json`.

```bash cURL theme={null}
curl https://api.deepmask.io/v1/chat/completions \
  -H "Authorization: Bearer $DEEPMASK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Explain what an API key is in one sentence."}
    ],
    "max_tokens": 200
  }'
```

```python Python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPMASK_API_KEY"],
    base_url="https://api.deepmask.io/v1",
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Explain what an API key is in one sentence."},
    ],
    max_tokens=200,
)

print(response.choices[0].message.content)
```

```javascript Node.js theme={null}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.DEEPMASK_API_KEY,
  baseURL: "https://api.deepmask.io/v1",
});

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "system", content: "You are a concise assistant." },
    { role: "user", content: "Explain what an API key is in one sentence." },
  ],
  max_tokens: 200,
});

console.log(response.choices[0].message.content);
```

Die Antwort folgt dem OpenAI-Format. Die einzelnen Felder finden Sie unter [Antwort](#antwort).

## Anfragetext

| Feld | Typ | Erforderlich | Regeln |
| - | - | - | - |
| `model` | string | Ja | Die API-Modell-ID, etwa `gpt-4o`. Ihr Schlüssel muss Zugriff auf das Modell haben. |
| `messages` | array | Ja | Die bisherige Unterhaltung mit mindestens einer Nachricht. Siehe [Nachrichten](#nachrichten). |
| `max_tokens` | integer | Nein | Die maximale Anzahl an Ausgabe-Tokens, von 1 bis zum Maximum des Modells. Siehe [Ausgabelänge](#ausgabelänge). |
| `max_completion_tokens` | integer | Nein | Ein Alias für `max_tokens` mit denselben Grenzen. Wenn Sie beide senden, erhalten Sie `400` mit `API_REQUEST_UNBOUNDED`. |
| `stream` | boolean | Nein | Setzen Sie den Wert auf `true`, um die Antwort als Server-Sent Events zu erhalten. Siehe [Streaming](#streaming). |
| `stream_options` | object | Nein | Nur mit `stream: true` erlaubt. Das einzige Feld ist `include_usage`, ein boolescher Wert. |
| `user` | string | Nein | Eine Kennung für Ihren Endnutzer, bis zu 100 Zeichen. Sie darf das NUL-Zeichen (`U+0000`) nicht enthalten. |
| `tools` | array | Nein | 1 bis 128 Funktions-Tools. Siehe [Tool-Aufrufe](#tool-aufrufe). |
| `tool_choice` | string oder object | Nein | `"auto"`, `"none"`, `"required"` oder eine benannte Funktion. Erfordert `tools`. |
| `parallel_tool_calls` | boolean | Nein | Legt fest, ob das Modell mehrere Tool-Aufrufe in einer Antwort zurückgeben darf. Erfordert `tools`. |
| `temperature` | number | Nein | Von 0 bis 2. |
| `top_p` | number | Nein | Von 0 bis 1. |
| `presence_penalty` | number | Nein | Von −2 bis 2. |
| `frequency_penalty` | number | Nein | Von −2 bis 2. |
| `seed` | integer | Nein | Eine ganze Zahl, die in einen vorzeichenbehafteten 64-Bit-Integer passt. |
| `stop` | string oder array aus strings | Nein | 1 bis 4 Stoppsequenzen. Jede Sequenz ist ein nicht leerer String. |
| `n` | integer | Nein | Nur `1`, was auch der Standardwert ist. |

Die letzten sieben Felder sind Sampling-Optionen. Sie können jede dieser Optionen als `null` senden. Das bedeutet „nicht gesetzt“. Manche Modelle ignorieren einige davon. Siehe [Sampling-Optionen](#sampling-optionen).

Jedes andere Feld auf oberster Ebene führt zu `400` mit `API_REQUEST_UNBOUNDED`. Dasselbe gilt für ein Feld mit falschem Typ oder mit einem Wert außerhalb seiner Grenzen. Drei Ausnahmen führen zu `400` mit `API_REQUEST_INVALID`: wenn `model` fehlt oder kein String ist, wenn `user` das NUL-Zeichen enthält und wenn ein String ungültige Unicode-Zeichen enthält.

Administratoren der Organisation können die ID jedes Modells unter **API-Modell-ID** auf der Registerkarte **Modelle** in **Benutzereinstellungen** > **API** kopieren. Wenn Sie diese Seite nicht öffnen können, rufen Sie mit Ihrem Schlüssel [`GET /v1/models`](#modelle-auflisten) auf. So erhalten Sie die Modell-IDs, die der Schlüssel verwenden kann. Für ein Modell, das Ihrem Schlüssel nicht zugewiesen ist, erhalten Sie `403` mit `API_MODEL_NOT_ALLOWED`. Einem bestehenden Schlüssel können Sie keine Modelle hinzufügen. Erstellen Sie daher einen neuen Schlüssel, um andere Modelle zu verwenden. Den Katalog finden Sie unter [Modelle](https://documentation.deepmask.io/de/api/models.md).

### Nachrichten

Jede Nachricht hat die Felder `role` und `content`. In System- und Benutzernachrichten kann `content` ein String oder ein Array aus Content-Parts sein.

| Rolle | Felder | Regeln |
| - | - | - |
| `system` | `role`, `content` | `content` ist ein String oder ein Array aus Text-Parts. |
| `user` | `role`, `content` | `content` ist ein String oder ein Array aus Text-Parts und Bild-Parts. Siehe [Bildeingabe](#bildeingabe). |
| `assistant` | `role`, `content`, `tool_calls` | `content` muss ein String sein. Wenn die Nachricht `tool_calls` enthält, darf `content` `null` sein. |
| `tool` | `role`, `tool_call_id`, `content`, optional `name` | `tool_call_id` ist die `id` des Tool-Aufrufs, auf den Sie antworten, 1–100 Zeichen. `content` muss ein String sein. |

* **Text-Parts:** Ein Text-Part hat genau zwei Felder: `type` mit dem Wert `"text"` und `text` mit einem String. Text-Parts funktionieren bei allen Modellen.
* **Content-Arrays:** Ein Array enthält 1–256 Parts. Ein leeres Array wird abgelehnt.
* **Bilder:** Bild-Parts funktionieren nur in Benutzernachrichten und nur bei den sieben Modellen, die unter [Bildeingabe](#bildeingabe) aufgeführt sind. Andere Modelle lehnen sie ab, auch wenn sie in DeepMask Chat Bilder verarbeiten.
* **Keine anderen Inhalte:** Datei-, Audio- und Dokument-Parts werden abgelehnt. Dasselbe gilt für `cache_control` in jedem Part. Siehe [Nicht unterstützte Parameter](#nicht-unterstützte-parameter).
* **Keine `developer`-Rolle:** Verwenden Sie stattdessen `system`.
* **`name` nur bei Tool-Nachrichten:** Entfernen Sie `name` aus System-, Benutzer- und Assistant-Nachrichten.
* **Tool-Aufrufe:** Eine Assistant-Nachricht kann 1–128 Tool-Aufrufe enthalten. Jeder Aufruf hat eine `id` mit 1–100 Zeichen, `type: "function"` und ein `function`-Objekt mit `name` und `arguments`, einem JSON-String.
* **Mindestens eine Benutzernachricht:** Manche Modelle lehnen eine Anfrage ab, die nur eine `system`-Nachricht enthält.
* **Kein Nachrichtenlimit:** Sie können so viele Nachrichten senden, wie in das Kontextfenster des Modells passen.

> [!TIP]
>
> Sie können die Assistant-`message` aus einer Antwort unverändert an `messages` anhängen, so wie Ihr SDK sie zurückgibt. SDKs und Reasoning-Modelle fügen zusätzliche Felder hinzu, etwa leere `refusal`- und `annotations`-Felder sowie Reasoning-Inhalte. DeepMask akzeptiert diese Felder und entfernt sie. Wenn `refusal` Text enthält, senden Sie stattdessen Ihre eigene Assistant-Nachricht.

### Sampling-Optionen

Viele SDKs, Frameworks und Coding-Agents senden bei jeder Anfrage Sampling-Optionen mit. DeepMask akzeptiert `temperature`, `top_p`, `presence_penalty`, `frequency_penalty`, `seed`, `stop` und `n`. Typ und Wertebereich jeder Option finden Sie unter [Anfragetext](#anfragetext).

* **Wertebereiche:** Jeder Wertebereich schließt seine Grenzwerte ein. DeepMask akzeptiert also `temperature: 2`. Ein Wert außerhalb seines Bereichs führt zu `400` mit `API_REQUEST_UNBOUNDED`. Manche Modelle akzeptieren für `temperature` einen engeren Bereich. Siehe [Optionen, die manche Modelle ignorieren](#optionen-die-manche-modelle-ignorieren).
* **Nur Zahlen:** Senden Sie Zahlen als JSON-Zahlen. Ein String wie `"0.5"` oder ein boolescher Wert wird abgelehnt.
* **Ganze Zahlen für `seed`:** Ein Wert wie `1.5` oder `"42"` wird abgelehnt. Dasselbe gilt für einen Wert, der nicht in einen vorzeichenbehafteten 64-Bit-Integer passt. Sehr große Seeds können an Genauigkeit verlieren. Halten Sie `seed` daher für exakte Ergebnisse im Bereich von ±9.007.199.254.740.991.
* **`null` bedeutet nicht gesetzt:** DeepMask behandelt eine Option mit dem Wert `null` so, als hätten Sie sie weggelassen.
* **`n` nur als 1:** `n: 1` wird akzeptiert, weil es der Standardwert ist. Jeder andere Wert, etwa `2` oder `0`, führt zu `400` mit `API_REQUEST_UNBOUNDED`. Wenn Sie mehrere Antworten benötigen, senden Sie für jede eine eigene Anfrage.
* **`stop` als String oder Array:** Ein String zählt als eine Stoppsequenz. Ein Array kann 1 bis 4 Strings enthalten. Ein leeres Array oder ein Array mit mehr als 4 Strings wird abgelehnt.
* **Keine leeren Stoppsequenzen:** Ein leerer String (`""`) wird abgelehnt, sowohl allein als auch in einem Array.
* **Stoppsequenzen aus Leerraum:** Bei den Claude-Modellen entfernt DeepMask Stoppsequenzen, die nur aus Leerraumzeichen bestehen, etwa `"\n\n"`. Bleibt keine Sequenz übrig, läuft die Anfrage ohne `stop`. `gpt-4o`, `gpt-4.1`, `o3-mini` und `mistral-large-3` erhalten solche Sequenzen unverändert. Die anderen Modelle ignorieren `stop`. Siehe [Optionen, die manche Modelle ignorieren](#optionen-die-manche-modelle-ignorieren).
* **Anfragegröße:** `stop` zählt zum Limit von 32 MiB für Nachrichten und Tools. Siehe [Anfragegröße](#anfragegröße).

#### Optionen, die manche Modelle ignorieren

Nicht jedes Modell unterstützt jede Sampling-Option. Unterstützt ein Modell eine Option nicht, akzeptiert DeepMask sie, sendet sie aber nicht an das Modell. Die Option hat dann keine Wirkung. Sie erhalten keinen Fehler, und die Anfrage wird so abgerechnet, als hätten Sie die Option nicht gesendet.

| Modelle | Ignorierte Optionen |
| - | - |
| `gpt-4o`, `gpt-4.1`, `mistral-large-3` | Keine |
| `gpt-5.4` | `stop`, `presence_penalty`, `frequency_penalty` |
| `o3-mini` | `top_p`, `presence_penalty`, `frequency_penalty` sowie jeder `temperature`-Wert außer `1` |
| `haiku-4.5`, `sonnet-4.5`, `opus-4.5`, `opus-4.6`, `sonnet-4.6` | `top_p`, `presence_penalty`, `frequency_penalty`, `seed` |
| `opus-4.7`, `opus-4.8`, `opus-5`, `sonnet-5`, `haiku-5.5`, `sonnet-5.5`, `opus-5.5` | `temperature`, `top_p`, `presence_penalty`, `frequency_penalty`, `seed` |
| `deepseek-v3.2`, `glm-4.7`, `glm-4.7-flash`, `glm-5`, `kimi-k2.5`, `minimax-m2.1`, `minimax-m2.5`, `nemotron-3-super`, `qwen3-235b-2507` | `stop`, `presence_penalty`, `frequency_penalty`, `seed` |

* **`temperature` über 1:** `haiku-4.5`, `sonnet-4.5`, `opus-4.5`, `opus-4.6` und `sonnet-4.6` akzeptieren `temperature` nur von 0 bis 1. Dasselbe gilt für `deepseek-v3.2`, `glm-4.7`, `glm-4.7-flash`, `glm-5`, `kimi-k2.5`, `minimax-m2.1`, `minimax-m2.5`, `nemotron-3-super` und `qwen3-235b-2507`. Einen höheren Wert lehnt der Modellanbieter mit einem `4xx`-Status und `API_UPSTREAM_REJECTED` ab. Diese Ablehnung wird nicht abgerechnet.
* **`temperature` bei Claude-Modellen ab Version 4.7:** Diese Modelle ignorieren `temperature`, wie die Tabelle zeigt. Ein Wert über 1 hat bei ihnen daher keine Wirkung.
* **Andere Ablehnungen durch den Anbieter:** Ein Modellanbieter kann auch einen Wert ablehnen, den sein Modell nicht unterstützt. Auch diese Ablehnung führt zu `API_UPSTREAM_REJECTED` und wird nicht abgerechnet.

### Nicht unterstützte Parameter

Diese Parameter und Eingaben führen zu `400` mit `API_REQUEST_UNBOUNDED`, sofern die Zeile keinen anderen Code nennt.

| Nicht unterstützt | Was Sie stattdessen tun |
| - | - |
| `response_format`, einschließlich JSON-Modus, Structured Outputs und der `parse()`-Hilfsfunktionen der SDKs | Beschreiben Sie das Format in Ihrem Prompt, oder definieren Sie ein Funktions-Tool und lesen Sie dessen Argumente aus. |
| `n` mit einem anderen Wert als 1 | Senden Sie für jede benötigte Antwort eine eigene Anfrage. |
| `logprobs`, `top_logprobs` | Entfernen Sie die Parameter. |
| `logit_bias` | Entfernen Sie den Parameter. |
| `top_k` | Entfernen Sie den Parameter. Verwenden Sie stattdessen `temperature` oder `top_p`. |
| `reasoning_effort` | Entfernen Sie den Parameter. |
| `functions`, `function_call` | Verwenden Sie `tools` und `tool_choice`. |
| `metadata`, `store` oder jedes andere Feld, das nicht unter [Anfragetext](#anfragetext) aufgeführt ist | Entfernen Sie die Felder. |
| Datei-, Audio- oder Dokument-Parts oder jeder andere Part ohne `image_url`-Feld, etwa `input_text` | Senden Sie Text als String oder in Text-Parts. |
| Text-Parts in `assistant`- oder `tool`-Nachrichten | Senden Sie deren `content` als String. |
| `cache_control` in einem Text-Part | Entfernen Sie das Feld. |
| `cache_control` in einem Bild-Part (`API_IMAGE_INVALID`) | Entfernen Sie das Feld. |
| Bilder in einer anderen Nachricht als einer Benutzernachricht, etwa in `system`-, `assistant`-, `tool`- oder `developer`-Nachrichten (`API_IMAGE_INPUT_UNSUPPORTED`) | Senden Sie Bilder in Benutzernachrichten. |
| Bilder bei einem Modell ohne Bildeingabe (`API_IMAGE_INPUT_UNSUPPORTED`) | Verwenden Sie eines der Modelle, die unter [Bildeingabe](#bildeingabe) aufgeführt sind. |
| Bildlinks, etwa `https://`-URLs (`API_IMAGE_URL_UNSUPPORTED`) | Senden Sie das Bild als Base64-Data-URL. |
| `detail: "high"` oder ein anderer `detail`-Wert als `"auto"` oder `"low"` (`API_IMAGE_INVALID`) | Lassen Sie `detail` weg, oder setzen Sie es auf `"auto"` oder `"low"`. |
| Die `developer`-Rolle oder `name` in System-, Benutzer- und Assistant-Nachrichten | Verwenden Sie `system` und entfernen Sie `name`. |
| Tools mit einem anderen `type` als `function` | Definieren Sie Funktions-Tools. |
| Ein leeres `tools`-Array oder `tool_choice` bzw. `parallel_tool_calls` ohne `tools` | Lassen Sie die Felder weg, wenn Sie keine Tools haben. |
| `stream_options` ohne `stream: true` | Senden Sie `stream_options` nur beim Streaming. |

> [!WARNING]
>
> Manche Frameworks, Agent-Bibliotheken und SDK-Wrapper fügen Ihren Anfragen Parameter wie `reasoning_effort`, `top_k`, `logprobs`, `response_format` oder ein leeres `tools`-Array hinzu, teilweise standardmäßig. DeepMask gibt für solche Anfragen `400` mit `API_REQUEST_UNBOUNDED` zurück. Konfigurieren Sie Ihr Framework oder Ihre Bibliothek so, dass diese Parameter nicht gesendet werden, oder rufen Sie die API wie auf dieser Seite gezeigt direkt mit dem OpenAI-SDK auf. Sampling-Optionen innerhalb ihrer Wertebereiche werden akzeptiert, Sie müssen sie also nicht entfernen. Halten Sie `temperature` bei manchen Modellen bei 1 oder darunter. Siehe [Sampling-Optionen](#sampling-optionen).

### Ausgabelänge

`max_tokens` legt die maximale Anzahl an Ausgabe-Tokens für eine Antwort fest. `max_completion_tokens` funktioniert genauso. Senden Sie nur einen der beiden Parameter. Alle Token-Limits auf einen Blick finden Sie unter [Token-Limits](https://documentation.deepmask.io/de/api/limits.md#token-limits).

* **Bei den meisten Modellen kein DeepMask-Standardwert:** Wenn Sie `max_tokens` weglassen, setzt DeepMask kein eigenes Limit. Es gilt die Standard-Ausgabelänge des Modells, und diese kann unter dem Maximum des Modells liegen. Setzen Sie `max_tokens`, wenn Sie lange Antworten erwarten.
* **GLM-4.7-Modelle:** `glm-4.7` und `glm-4.7-flash` stoppen bei 65.536 Ausgabe-Tokens, sofern Sie `max_tokens` nicht setzen.
* **Maximum je Modell:** Jedes Modell akzeptiert Werte bis zu seinem eigenen Maximum. Sie finden es unter **Max. Ausgabe-Tokens** in [Modelle](https://documentation.deepmask.io/de/api/models.md#verfügbare-modelle). Ein größerer Wert wird mit `400` und `API_REQUEST_UNBOUNDED` abgelehnt.
* **Reasoning-Tokens zählen mit:** Bei Reasoning-Modellen wie `o3-mini` und bei den Claude-Modellen mit dauerhaft aktivem Thinking werden verborgene Reasoning-Tokens auf `max_tokens` angerechnet. Sie werden als Ausgabe-Tokens abgerechnet. Bei diesen Claude-Modellen können Sie das Thinking nicht deaktivieren. Bei welchen Modellen Thinking immer aktiv ist, erfahren Sie unter [Reasoning- und Thinking-Tokens](https://documentation.deepmask.io/de/api/models.md#reasoning-und-thinking-tokens).
* **Abgeschnittene Antworten:** Wenn eine Antwort das Limit erreicht, hat `finish_reason` den Wert `length`. Bei einem niedrigen Limit kann das Reasoning das Budget aufbrauchen, bevor die sichtbare Antwort vollständig ist.
* **Lange Anfragen:** Eine Anfrage kann bis zu 15 Minuten laufen. Die OpenAI-SDKs brechen standardmäßig nach 10 Minuten mit einem Timeout ab und wiederholen die Anfrage dann. DeepMask rechnet beide Anfragen ab. Erhöhen Sie für lange Antworten den `timeout` des Clients. Siehe [Wiederholungen in den OpenAI-SDKs](https://documentation.deepmask.io/de/api/errors.md#wiederholungen-in-den-openai-sdks).
* **Am 15-Minuten-Limit:** DeepMask beendet die Anfrage. Ihr Ergebnis ist dann unklar. Sie wird daher nicht abgerechnet, es sei denn, für sie wird später noch Nutzung gemeldet. Siehe [Anfragedauer](https://documentation.deepmask.io/de/api/limits.md#anfragedauer).

### Anfragegröße

Alle Limits für Größe und Dauer auf einen Blick finden Sie unter [Größe und Dauer von Anfragen](https://documentation.deepmask.io/de/api/limits.md#größe-und-dauer-von-anfragen).

* **Anfragetext:** Ein Anfragetext darf bis zu 32 MiB groß sein. Bei einem größeren Anfragetext erhalten Sie `413` mit `API_REQUEST_INVALID`.
* **Unkomprimiert:** Senden Sie den Anfragetext ohne Komprimierung. Ein Anfragetext mit einem `Content-Encoding`-Header wie `gzip`, `deflate` oder `br` wird mit `400` und `API_REQUEST_INVALID` abgelehnt. Die OpenAI-SDKs senden unkomprimierte Anfragetexte.
* **Base64-Bilder:** Der Base64-Text Ihrer Bilder zählt zu den 32 MiB. 20 MB Bilder ergeben etwa 26,7 MB Base64. Für den Rest der Anfrage bleiben damit etwa 6,9 MB.
* **Nachrichten, Tools und Stoppsequenzen:** Nachrichten, Tool-Definitionen, `tool_choice` und `stop` dürfen zusammen bis zu 32 MiB als UTF-8-JSON umfassen. Base64-Bilder zählen hier ebenfalls mit. Tool-Schemas werden dabei mit aufgelösten `$ref`-Verweisen gezählt. Größere Anfragen werden mit `400` und `API_REQUEST_UNBOUNDED` abgelehnt.
* **Anfragetexte in Bearbeitung:** Die Anfragetexte, die ein Schlüssel gleichzeitig in Bearbeitung hat, dürfen zusammen bis zu 64 MiB groß sein. Eine Anfrage, die diese Grenze überschreiten würde, erhält `429` mit `API_CONCURRENCY_LIMIT`. Senden Sie bei großen Bildern weniger Anfragen parallel. Siehe [Anfragen in Bearbeitung pro Schlüssel](https://documentation.deepmask.io/de/api/limits.md#anfragen-in-bearbeitung-pro-schlüssel).
* **Kontextfenster:** In der Praxis ist das Kontextfenster des Modells die Grenze. Einen Prompt, der nicht hineinpasst, lehnt der Modellanbieter mit einem `4xx`-Status und `API_UPSTREAM_REJECTED` ab. Diese Ablehnung wird nicht abgerechnet. Das Kontextfenster jedes Modells finden Sie unter [Modelle](https://documentation.deepmask.io/de/api/models.md).

## Bildeingabe

An sieben Modelle können Sie Bilder in Benutzernachrichten senden: `gpt-4o`, `gpt-4.1` und die Claude-Modelle `haiku-4.5`, `sonnet-4.5`, `opus-4.5`, `opus-4.6` und `sonnet-4.6`. Das Modell liest die Bilder zusammen mit Ihrem Text und antwortet mit Text. Dieselbe Liste finden Sie unter [Bildeingabe](https://documentation.deepmask.io/de/api/models.md#bildeingabe) auf der Seite „Modelle“.

* **Nur Base64:** Sie senden jedes Bild innerhalb der Anfrage als Base64-Data-URL. DeepMask lehnt Bildlinks ab und lädt sie nie herunter.
* **Andere Modelle lehnen Bilder ab:** Ein gültiger Bild-Part, den Sie an ein anderes Modell senden, führt zu `400` mit `API_IMAGE_INPUT_UNSUPPORTED`.
* **Nicht in der Modellliste:** `GET /v1/models` zeigt nicht, welche Modelle Bilder akzeptieren.

### Bild senden

Dieses Beispiel sendet eine lokale PNG-Datei, `photo.png`, mit einer Frage an `gpt-4o`. Für ein anderes Format ändern Sie `image/png` in der Data-URL passend zur Datei. Das cURL-Beispiel schreibt die Anfrage zuerst in eine Datei, weil ein großes Bild nicht in ein einzelnes Kommandozeilenargument passt.

```bash cURL theme={null}
# Bild als Base64 in einer Zeile codieren. Das funktioniert unter macOS und Linux.
IMAGE_BASE64=$(base64 < photo.png | tr -d '\n')

# Anfragetext in eine Datei schreiben.
cat > request.json <<EOF
{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "What is in this picture?"},
        {"type": "image_url", "image_url": {"url": "data:image/png;base64,$IMAGE_BASE64"}}
      ]
    }
  ],
  "max_tokens": 300
}
EOF

curl https://api.deepmask.io/v1/chat/completions \
  -H "Authorization: Bearer $DEEPMASK_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json
```

```python Python theme={null}
import base64
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPMASK_API_KEY"],
    base_url="https://api.deepmask.io/v1",
)

with open("photo.png", "rb") as image_file:
    image_base64 = base64.b64encode(image_file.read()).decode("ascii")

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What is in this picture?"},
                {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{image_base64}"}},
            ],
        },
    ],
    max_tokens=300,
)

print(response.choices[0].message.content)
```

```javascript Node.js theme={null}
import { readFile } from "node:fs/promises";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.DEEPMASK_API_KEY,
  baseURL: "https://api.deepmask.io/v1",
});

const imageBase64 = (await readFile("photo.png")).toString("base64");

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "What is in this picture?" },
        { type: "image_url", image_url: { url: `data:image/png;base64,${imageBase64}` } },
      ],
    },
  ],
  max_tokens: 300,
});

console.log(response.choices[0].message.content);
```

Die Antwort hat dasselbe Format wie jede andere Chat Completion. Siehe [Antwort](#antwort).

### Bild-Parts

Ein Bild-Part steht im `content`-Array einer Benutzernachricht. Sie können Bild-Parts und Text-Parts in beliebiger Reihenfolge kombinieren.

```json theme={null}
{
  "role": "user",
  "content": [
    {"type": "text", "text": "What is in this picture?"},
    {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KGgo...", "detail": "auto"}}
  ]
}
```

* **Felder des Parts:** Ein Bild-Part hat genau zwei Felder: `type` mit dem Wert `"image_url"` und `image_url`. Andere Felder, etwa `cache_control`, werden abgelehnt.
* **Felder von `image_url`:** `image_url` ist ein Objekt mit `url` und einem optionalen `detail`. Andere Felder, etwa `format`, werden abgelehnt. Ein String anstelle des Objekts wird ebenfalls abgelehnt.
* **`detail`:** Lassen Sie das Feld weg, oder setzen Sie es auf `"auto"` oder `"low"`. Andere Werte, auch `"high"` und `null`, werden abgelehnt. Bei `gpt-4o` und `gpt-4.1` verbraucht `"low"` deutlich weniger Tokens. Die Claude-Modelle akzeptieren `detail`, ignorieren es aber.
* **Nur Benutzernachrichten:** Ein Bild-Part in einer `system`-, `assistant`- oder `tool`-Nachricht wird abgelehnt.
* **Bilder ohne Text:** Eine Benutzernachricht kann Bild-Parts ohne einen Text-Part enthalten.
* **Format von Chat Completions:** Verwenden Sie `image_url`- und `text`-Parts. Parts der Responses API werden abgelehnt. Ein `input_image`-Part mit einer Base64-Data-URL führt zum Beispiel zu `API_IMAGE_INVALID`, ein `input_text`-Part zu `API_REQUEST_UNBOUNDED`.

### Bilddaten

Die `url` muss eine Data-URL im Format `data:image/<type>;base64,<data>` sein. Vor dem Komma darf nichts anderes stehen.

* **Formate:** PNG, JPEG, GIF und WebP. Schreiben Sie den Typ in Kleinbuchstaben: `image/png`, `image/jpeg`, `image/gif` oder `image/webp`. Andere Formate wie SVG, HEIC, BMP oder PDF werden abgelehnt.
* **JPEG-Bezeichnung:** `image/jpg` wird ebenfalls akzeptiert. DeepMask sendet es als `image/jpeg` an das Modell.
* **Passender Typ:** Der angegebene Typ muss zu den Bytes des Bildes passen. Eine JPEG-Datei mit der Angabe `image/png` wird zum Beispiel abgelehnt.
* **Standard-Base64:** Verwenden Sie das Standardalphabet (`A–Z`, `a–z`, `0–9`, `+` und `/`) mit `=`-Padding. URL-sicheres Base64, das `-` und `_` verwendet, wird abgelehnt. Dasselbe gilt für Base64 ohne Padding.
* **Eine Zeile:** Zeilenumbrüche im Base64-Text werden abgelehnt. GNU `base64` unter Linux bricht Zeilen standardmäßig um. Verwenden Sie daher `base64 -w 0` oder entfernen Sie die Zeilenumbrüche.
* **Animierte Bilder:** Animierte WebP-Bilder werden abgelehnt. Animierte GIFs werden akzeptiert, aber jedes Einzelbild muss innerhalb des Pixellimits liegen. Ein Modellanbieter kann ein GIF ablehnen, das er nicht lesen kann. Senden Sie daher nach Möglichkeit Standbilder.
* **Keine Links:** `https://`-, `http://`- und andere URLs werden abgelehnt. DeepMask lädt sie nicht herunter.

### Bildlimits

Diese Limits gelten für jede Anfrage. Die Anzahl und die Gesamtgröße umfassen die Bilder in allen Nachrichten, auch in früheren Runden der Unterhaltung.

| Modelle | Bilder | Größe pro Bild | Größe aller Bilder | Pixel pro Seite |
| - | - | - | - | - |
| `haiku-4.5`, `sonnet-4.5`, `opus-4.5`, `opus-4.6`, `sonnet-4.6` | 20 | 3,75 MB | 20 MB | 8.000 |
| `gpt-4o`, `gpt-4.1` | 20 | 5 MB | 20 MB | 8.000 |

* **Decodierte Größe:** Die Größen beziehen sich auf das decodierte Bild, nicht auf den Base64-Text. 1 MB entspricht 1.000.000 Bytes.
* **Pixel:** Jede Seite eines Bildes muss 1 bis 8.000 Pixel lang sein.
* **Limit überschritten:** Die Anfrage gibt `400` mit `API_IMAGE_INVALID` zurück.
* **Große Fotos:** Handyfotos können größer als 3,75 MB sein, und manche Smartphones speichern sie als HEIC. Speichern Sie ein Foto vor dem Codieren als JPEG, dessen längste Seite etwa 2.000 Pixel misst. Der Modellanbieter verkleinert große Bilder ohnehin, sodass das Modell etwa dieselben Details sieht.
* **Lange Unterhaltungen:** Um innerhalb der Limits zu bleiben, entfernen Sie Bilder aus früheren Runden, die das Modell nicht mehr benötigt.
* **Anfragetext:** Der Base64-Text zählt auch zu den 32 MiB des Anfragetexts. Siehe [Anfragegröße](#anfragegröße).

### Bildfehler

Abgelehnte Bilder führen zu `400`, bevor die Anfrage das Modell erreicht. Diese Ablehnungen werden daher nicht abgerechnet.

| Code | Ursache | Was Sie tun |
| - | - | - |
| `API_IMAGE_INPUT_UNSUPPORTED` | Das Modell akzeptiert keine Bilder, oder ein Bild-Part steht in einer anderen Nachricht als einer Benutzernachricht. | Verwenden Sie ein Modell mit Bildeingabe und senden Sie Bilder in Benutzernachrichten. |
| `API_IMAGE_URL_UNSUPPORTED` | Das Bild ist ein Link, etwa eine `https://`-URL, statt einer Base64-Data-URL. | Codieren Sie das Bild als Base64 und senden Sie es als Data-URL. |
| `API_IMAGE_INVALID` | Der Bild-Part hat falsche Felder oder einen falschen `detail`-Wert, ein nicht unterstütztes Format, ungültiges Base64 oder einen Typ, der nicht zu den Bytes passt. Sie erhalten den Code auch, wenn die Anfrage ein Bildlimit überschreitet. | Korrigieren Sie den Bild-Part. Wiederholen Sie die Anfrage nicht unverändert. |

* **Bildprüfungen kommen zuerst:** DeepMask prüft die Struktur jedes Bild-Parts, bevor es prüft, ob das Modell Bilder akzeptiert. Bei einem Modell ohne Bildeingabe führt ein Link daher trotzdem zu `API_IMAGE_URL_UNSUPPORTED` und `detail: "high"` trotzdem zu `API_IMAGE_INVALID`.
* **Ursache finden:** `API_IMAGE_INVALID` nennt nicht, welche Regel verletzt wurde. Unter macOS und Linux zeigt `file photo.png` das tatsächliche Format der Datei und ihre Größe in Pixeln. Vergleichen Sie beides mit dem Typ in der Data-URL und mit den [Bildlimits](#bildlimits).
* **Andere Parts:** Eine Anfrage, die zusätzlich einen Datei-, Audio- oder Dokument-Part enthält, führt zu `API_REQUEST_UNBOUNDED`.
* **Ablehnungen durch den Anbieter:** Kann der Modellanbieter ein Bild nicht verarbeiten, das diese Prüfungen bestanden hat, schlägt die Anfrage mit `API_UPSTREAM_REJECTED` fehl. Je nach Modell ist der Status der eigene `4xx`-Status des Anbieters oder `502`. Diese Anfrage wird nicht abgerechnet. Prüfen Sie das Bild, zum Beispiel indem Sie es in PNG umwandeln, statt die Anfrage unverändert zu wiederholen. Siehe [Anbieterfehler](https://documentation.deepmask.io/de/api/errors.md#anbieterfehler-4xx-502-oder-503).

### Wie Bilder abgerechnet werden

Bilder werden als Eingabe-Tokens abgerechnet. Bild-Tokens sind Teil von `prompt_tokens` und werden zum Preis für **Eingabe** des Modells abgerechnet. Einen separaten Preis für Bilder gibt es nicht.

* **Keine separate Angabe:** `usage` weist weder Bild-Tokens noch die Anzahl der Bilder aus.
* **Tokens pro Bild:** Die Anzahl hängt von der Bildgröße und vom Modell ab. In den Messungen von DeepMask verbrauchte ein großes Bild bei den Claude-Modellen bis zu etwa 1.500 Tokens, bei `gpt-4.1` etwa 1.450 und bei `gpt-4o` etwa 1.700. Ein Bild mit 512 × 512 Pixeln verbrauchte etwa 250 bis 370 Tokens.
* **`detail: "low"`:** Bei `gpt-4o` und `gpt-4.1` verbrauchte ein Bild mit `"low"` etwa 85 bis 105 Tokens.
* **Große Bilder werden verkleinert:** Der Modellanbieter verkleinert große Bilder, bevor das Modell sie liest. Ein Bild mit 8.000 × 8.000 Pixeln kostete nicht mehr Tokens als die oben genannten großen Bilder.
* **Viele Bilder:** Bei etwa 1.700 Tokens pro Bild fügen 20 große Bilder etwa 34.000 Eingabe-Tokens hinzu.
* **Wiederholte Bilder:** Bei `gpt-4o` und `gpt-4.1` kann ein Bild, das in späteren Anfragen erneut vorkommt, zum Preis für zwischengespeicherte Eingabe abgerechnet werden. Siehe [Zwischengespeicherte Eingabe](https://documentation.deepmask.io/de/api/models.md#zwischengespeicherte-eingabe).
* **Genaue Werte:** Die Token-Regeln der Anbieter können sich ändern. Die genaue Anzahl lesen Sie in jeder Antwort aus `usage.prompt_tokens`.

## Antwort

Eine erfolgreiche Anfrage gibt ein Chat-Completion-Objekt im OpenAI-Format zurück.

```json theme={null}
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1762790400,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "An API key is a secret token that identifies your app when it calls an API."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 27,
    "completion_tokens": 18,
    "total_tokens": 45
  }
}
```

* `model` ist die API-Modell-ID, die Sie gesendet haben, etwa `gpt-4o`.
* `choices[0].message` enthält die Antwort. Wenn das Modell Tools aufruft, kann `content` `null` sein, und `tool_calls` listet die Aufrufe auf.
* `usage` gibt die Eingabe-Tokens (`prompt_tokens`) und die Ausgabe-Tokens (`completion_tokens`) der Anfrage an.

Antworten können weitere Felder enthalten. Ignorieren Sie alle Felder, die Ihre App nicht verwendet.

### Abschlussgründe

Die häufigsten Werte für `finish_reason` sind:

| Wert | Bedeutung |
| - | - |
| `stop` | Das Modell hat seine Antwort beendet. |
| `length` | Die Antwort hat `max_tokens` oder die maximale Ausgabelänge des Modells erreicht. |
| `tool_calls` | Das Modell möchte, dass Sie ein oder mehrere Tools ausführen. Siehe [Tool-Aufrufe](#tool-aufrufe). |
| `content_filter` | Ein Inhaltsfilter hat die Antwort gestoppt. Mehrere Claude-Modelle können eine Anfrage auf diese Weise über die Sicherheitsklassifikatoren des Anbieters ablehnen. Welche Modelle das sind, erfahren Sie unter [So funktionieren die Preise](https://documentation.deepmask.io/de/api/models.md#so-funktionieren-die-preise). Die Antwort wird Ihnen berechnet. |

## Streaming

Setzen Sie `stream` auf `true`, um die Antwort als Server-Sent Events zu empfangen, während das Modell sie erzeugt. Fügen Sie `stream_options: {"include_usage": true}` hinzu, um zusätzlich die Anzahl der Tokens zu erhalten.

```bash cURL theme={null}
curl -N https://api.deepmask.io/v1/chat/completions \
  -H "Authorization: Bearer $DEEPMASK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Write a haiku about the sea."}],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'
```

```python Python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPMASK_API_KEY"],
    base_url="https://api.deepmask.io/v1",
)

stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Write a haiku about the sea."}],
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if chunk.usage:
        print(f"\nTokens: {chunk.usage.prompt_tokens} in, {chunk.usage.completion_tokens} out")
```

```javascript Node.js theme={null}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.DEEPMASK_API_KEY,
  baseURL: "https://api.deepmask.io/v1",
});

const stream = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Write a haiku about the sea." }],
  stream: true,
  stream_options: { include_usage: true },
});

for await (const chunk of stream) {
  const text = chunk.choices[0]?.delta?.content;
  if (text) process.stdout.write(text);
  if (chunk.usage) {
    console.log(`\nTokens: ${chunk.usage.prompt_tokens} in, ${chunk.usage.completion_tokens} out`);
  }
}
```

Die Antwort hat den Content-Type `text/event-stream`. Jedes Event ist eine `data:`-Zeile mit einem Chat-Completion-Chunk, und der Stream endet mit `data: [DONE]`. Ein gekürzter Stream sieht so aus:

```text theme={null}
data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","model":"gpt-4o","choices":[{"index":0,"delta":{"role":"assistant","content":""}}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","model":"gpt-4o","choices":[{"index":0,"delta":{"content":"Waves fold into foam"}}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","model":"gpt-4o","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","model":"gpt-4o","choices":[],"usage":{"prompt_tokens":14,"completion_tokens":17,"total_tokens":31}}

data: [DONE]
```

* **Events kommen an, sobald sie bereit sind:** DeepMask leitet jedes Event weiter, sobald es vollständig ist.
* **Leere Chunks entfallen:** Jeder Chunk, den Sie erhalten, enthält mindestens einen Eintrag in `choices`. Einzige Ausnahme ist der Chunk mit den Nutzungsdaten.
* **Nutzungsdaten nur auf Wunsch:** Der letzte Chunk mit einem `usage`-Objekt wird nur gesendet, wenn Sie `include_usage` auf `true` setzen. Sein `choices`-Array kann leer sein. Prüfen Sie es daher, bevor Sie `choices[0]` lesen.
* **Fehler vor Beginn des Streams:** Wird eine Streaming-Anfrage vor dem ersten Chunk abgelehnt, erhalten Sie einen normalen JSON-Fehler mit einem HTTP-Fehlerstatus.
* **Fehler während des Streams:** Tritt ein Fehler auf, nachdem der Stream begonnen hat, erhalten Sie statt eines Chunks ein Event mit einem `error`-Objekt, zum Beispiel `data: {"error":{"message":"DeepMask API request could not be completed.","type":"api_error","code":"API_UPSTREAM_REJECTED"}}`. Prüfen Sie jedes Event auf ein `error`-Feld.
* **Vorzeitig endende Streams:** Erreicht eine Anfrage die maximale Anfragedauer von 15 Minuten oder bricht die Verbindung auf Seiten von DeepMask ab, wird der Stream ohne Fehler-Event und ohne `data: [DONE]` geschlossen. Wenn Sie HTTP direkt verwenden, behandeln Sie einen Stream, der ohne `data: [DONE]` endet, als unvollständig. Die OpenAI-SDKs blenden `[DONE]` aus. Behandeln Sie dort einen Stream als unvollständig, wenn kein Chunk einen `finish_reason` enthält. Siehe [Fehler in gestreamten Antworten](https://documentation.deepmask.io/de/api/errors.md#fehler-in-gestreamten-antworten).
* **Unklares Ergebnis:** Ein Stream, der mit einem Fehler-Event endet oder auf Seiten von DeepMask oder des Anbieters vorzeitig abbricht, hat ein unklares Ergebnis. Er wird nicht abgerechnet, es sei denn, für ihn wird später noch Nutzung gemeldet. Mehr als 20 unklare Ergebnisse innerhalb von 24 Stunden pausieren die Anfragen Ihrer Organisation. Siehe [Unklare Ergebnisse](https://documentation.deepmask.io/de/api/limits.md#unklare-ergebnisse).

> [!NOTE]
>
> Wenn Ihr Client die Verbindung während eines Streams trennt, läuft die Anfrage trotzdem bis zum Ende weiter und wird abgerechnet. Setzen Sie `max_tokens`, um die Kosten einer abgebrochenen Antwort zu begrenzen.

## Tool-Aufrufe

Mit Tool-Aufrufen kann das Modell Ihre App bitten, eine Funktion auszuführen, etwa um Daten nachzuschlagen. Das Modell führt die Funktion nie selbst aus. Ihr Code führt sie aus und sendet das Ergebnis zurück.

**1. Tools senden**

Fügen Sie Ihrer Anfrage `tools` hinzu. Jedes Tool ist eine Funktion mit einem `name`, einer `description` und einem JSON-Schema in `parameters`.

**2. Auf Tool-Aufrufe prüfen**

Wenn das Modell ein Tool verwenden möchte, hat `finish_reason` den Wert `tool_calls`, und `message.tool_calls` listet die Aufrufe auf. Jeder Aufruf hat eine `id`, den `name` der Funktion und ihre `arguments` als JSON-String.

**3. Funktionen ausführen**

Parsen Sie die Argumente und führen Sie die passende Funktion in Ihrem Code aus.

**4. Ergebnisse senden**

Hängen Sie die Assistant-Nachricht und pro Aufruf eine `tool`-Nachricht an. Verwenden Sie dabei die `id` des Aufrufs als `tool_call_id`. Senden Sie die Anfrage erneut mit denselben `tools`. Wiederholen Sie das, bis `finish_reason` den Wert `stop` hat.

Dieses Beispiel zeigt einen vollständigen Durchlauf mit einer Funktion `get_weather`.

```bash cURL theme={null}
# 1. Frage und Tool-Definition senden.
curl https://api.deepmask.io/v1/chat/completions \
  -H "Authorization: Bearer $DEEPMASK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "What is the weather in Berlin?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get the current weather for a city.",
        "parameters": {
          "type": "object",
          "properties": {"city": {"type": "string"}},
          "required": ["city"]
        }
      }
    }]
  }'

# 2. Die Antwort hat finish_reason "tool_calls". Funktion ausführen.
#    Assistant-Nachricht aus der ersten Antwort übernehmen, dann pro Aufruf
#    eine tool-Nachricht anhängen. Die id jedes Aufrufs als tool_call_id
#    verwenden. Dieselben tools mitsenden.
curl https://api.deepmask.io/v1/chat/completions \
  -H "Authorization: Bearer $DEEPMASK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "What is the weather in Berlin?"},
      {
        "role": "assistant",
        "content": null,
        "tool_calls": [{
          "id": "call_abc123",
          "type": "function",
          "function": {"name": "get_weather", "arguments": "{\"city\":\"Berlin\"}"}
        }]
      },
      {"role": "tool", "tool_call_id": "call_abc123", "content": "{\"city\":\"Berlin\",\"temperature_c\":18}"}
    ],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get the current weather for a city.",
        "parameters": {
          "type": "object",
          "properties": {"city": {"type": "string"}},
          "required": ["city"]
        }
      }
    }]
  }'
```

```python Python theme={null}
import json
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPMASK_API_KEY"],
    base_url="https://api.deepmask.io/v1",
)

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get the current weather for a city.",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    },
}]

def get_weather(city):
    return {"city": city, "temperature_c": 18}  # Durch Ihre eigene Abfrage ersetzen.

messages = [{"role": "user", "content": "What is the weather in Berlin?"}]

response = client.chat.completions.create(model="gpt-4o", messages=messages, tools=tools)
message = response.choices[0].message

if message.tool_calls:
    messages.append(message)  # SDK-Nachricht unverändert zurücksenden.
    for call in message.tool_calls:
        args = json.loads(call.function.arguments)
        result = get_weather(**args)
        messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(result)})

    final = client.chat.completions.create(model="gpt-4o", messages=messages, tools=tools)
    print(final.choices[0].message.content)
else:
    print(message.content)
```

```javascript Node.js theme={null}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.DEEPMASK_API_KEY,
  baseURL: "https://api.deepmask.io/v1",
});

const tools = [{
  type: "function",
  function: {
    name: "get_weather",
    description: "Get the current weather for a city.",
    parameters: {
      type: "object",
      properties: { city: { type: "string" } },
      required: ["city"],
    },
  },
}];

function getWeather({ city }) {
  return { city, temperature_c: 18 }; // Durch Ihre eigene Abfrage ersetzen.
}

const messages = [{ role: "user", content: "What is the weather in Berlin?" }];

const response = await client.chat.completions.create({ model: "gpt-4o", messages, tools });
const message = response.choices[0].message;

if (message.tool_calls?.length) {
  messages.push(message); // SDK-Nachricht unverändert zurücksenden.
  for (const call of message.tool_calls) {
    const result = getWeather(JSON.parse(call.function.arguments));
    messages.push({ role: "tool", tool_call_id: call.id, content: JSON.stringify(result) });
  }

  const final = await client.chat.completions.create({ model: "gpt-4o", messages, tools });
  console.log(final.choices[0].message.content);
} else {
  console.log(message.content);
}
```

Die erste Anfrage liefert eine Antwort wie diese (hier gekürzt). Übernehmen Sie deren Assistant-`message` in die zweite Anfrage und verwenden Sie die `id` jedes Aufrufs als `tool_call_id`.

```json theme={null}
{
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": { "name": "get_weather", "arguments": "{\"city\":\"Berlin\"}" }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}
```

> [!TIP]
>
> Senden Sie in einer Unterhaltung mit Tool-Aufrufen bei jeder Anfrage dasselbe `tools`-Array. Manche Modelle lehnen eine Anfrage ab, deren Verlauf Tool-Aufrufe enthält, wenn `tools` fehlt.

### Tool-Auswahl

`tool_choice` steuert, ob und wie das Modell Ihre Tools verwendet. Der Parameter erfordert `tools`.

| Wert | Wirkung |
| - | - |
| `"auto"` | Das Modell entscheidet, ob es ein Tool aufruft. Das ist der Standard. |
| `"none"` | Das Modell antwortet, ohne ein Tool aufzurufen. |
| `"required"` | Das Modell muss mindestens ein Tool aufrufen. |
| `{"type": "function", "function": {"name": "get_weather"}}` | Das Modell muss die benannte Funktion aufrufen. |

### Modellspezifische Einschränkungen für Tools

Jedes Modell unterstützt `tools` mit `tool_choice: "auto"`. Manche Modelle unterstützen nicht alle anderen Tool-Optionen. Eine Anfrage mit einer nicht unterstützten Option wird mit `400` und `API_REQUEST_UNBOUNDED` abgelehnt, bevor sie das Modell erreicht. Sie wird daher nicht abgerechnet.

| Modelle | `"none"` | `"required"` | Benannte Funktion | `parallel_tool_calls` |
| - | - | - | - | - |
| `gpt-4o`, `gpt-4.1`, `gpt-5.4`, `o3-mini`, `mistral-large-3` | Ja | Ja | Ja | Ja |
| `haiku-4.5`, `sonnet-4.5`, `opus-4.5`, `opus-4.6`, `sonnet-4.6`, `opus-4.7`, `opus-4.8`, `opus-5`, `haiku-5.5` | Nein | Ja | Ja | Ja |
| `sonnet-5`, `sonnet-5.5`, `opus-5.5` | Nein | Nein | Nein | Ja |
| `deepseek-v3.2`, `glm-4.7`, `glm-4.7-flash`, `glm-5`, `kimi-k2.5`, `minimax-m2.1`, `minimax-m2.5`, `nemotron-3-super`, `qwen3-235b-2507` | Nein | Ja | Nein | Nein |

* **`parallel_tool_calls`:** Bei Modellen mit **Nein** wird die Anfrage abgelehnt, wenn das Feld vorhanden ist, unabhängig von seinem Wert. Lassen Sie es weg.
* **Erzwungene Tool-Auswahl:** `sonnet-5`, `sonnet-5.5` und `opus-5.5` akzeptieren weder `"required"` noch eine benannte Funktion. Verwenden Sie `"auto"` und beschreiben Sie in Ihrem Prompt, wann das Modell ein Tool verwenden soll.
* **`mistral-large-3`:** Geben Sie jeder Funktion eine `description`. Ohne sie lehnt der Anbieter die Anfrage mit `422` und `API_UPSTREAM_REJECTED` ab. Diese Ablehnung wird nicht abgerechnet.

Wenn ein Modell eine Ihrer Tool-Einstellungen nicht anwenden kann, lehnt DeepMask die Anfrage ab, statt sie ohne diese Einstellung auszuführen.

### Regeln für Tool-Definitionen

> [accordion] Funktionsdefinitionen
>
> * Jeder Eintrag in `tools` hat genau zwei Felder: `type` mit dem Wert `"function"` und `function`.
> * `function` kann `name`, `description`, `parameters` und `strict` enthalten. Andere Felder werden abgelehnt.
> * `name` hat 1–64 Zeichen: Buchstaben, Ziffern, Unterstriche und Bindestriche.
> * `description` ist ein String.
> * `parameters` ist ein JSON-Schema-Objekt. Es darf bis zu 32 Ebenen tief verschachtelt sein, und jede Zahl muss endlich sein.
> * `strict` ist ein boolescher Wert.

> [accordion] Schemas mit \$ref
>
> * Nur lokale Verweise funktionieren: `#`, `#/$defs/name`, `#/definitions/name` oder ein anderer JSON-Pointer innerhalb desselben Schemas.
> * Remote-Verweise und Pointer mit einem maskierten Schrägstrich (`%2F`) werden abgelehnt.
> * Ein Schema mit `$ref` darf weder `$id` unterhalb seiner Wurzel (oder ein `$id` auf der Wurzelebene mit einem `#`-Fragment) noch `$anchor`, `$dynamicRef`, `$dynamicAnchor`, `$recursiveRef` oder `$recursiveAnchor` enthalten. Es darf auch kein `$schema` für Draft-03 oder Draft-04 deklarieren.
> * Eine Eigenschaft, die wörtlich `$ref` oder `$id` heißt, wird abgelehnt.
> * Nach dem Auflösen seiner Verweise darf das Schema eines Tools höchstens etwa 32-mal so groß sein wie Ihr `tools`-Array in der gesendeten Form und höchstens 64 Ebenen tief. Nachrichten, die aufgelösten Tools, `tool_choice` und `stop` müssen zusammen weiterhin in 32 MiB passen.
> * Rekursive Schemas, bei denen ein Verweis auf ein Schema zurückzeigt, das ihn enthält, funktionieren nur bei `gpt-4o`, `gpt-4.1`, `gpt-5.4`, `o3-mini` und `mistral-large-3`.

## Modelle auflisten

`GET /v1/models` gibt die Modelle zurück, die Ihr API-Schlüssel verwenden kann. Der Endpunkt verwendet dieselbe Authentifizierung wie Chat-Anfragen.

```bash cURL theme={null}
curl https://api.deepmask.io/v1/models \
  -H "Authorization: Bearer $DEEPMASK_API_KEY"
```

```python Python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPMASK_API_KEY"],
    base_url="https://api.deepmask.io/v1",
)

for model in client.models.list():
    print(model.id)
```

```javascript Node.js theme={null}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.DEEPMASK_API_KEY,
  baseURL: "https://api.deepmask.io/v1",
});

for await (const model of client.models.list()) {
  console.log(model.id);
}
```

```json theme={null}
{
  "object": "list",
  "data": [
    { "id": "gpt-4.1", "object": "model", "created": 0, "owned_by": "deepmask" },
    { "id": "gpt-4o", "object": "model", "created": 0, "owned_by": "deepmask" }
  ]
}
```

* Die Liste enthält nur die Modelle, die dem Schlüssel zugewiesen sind, sortiert nach ID.
* Ein Modell, das DeepMask aus dem Katalog entfernt, verschwindet aus der Liste, auch wenn es dem Schlüssel zugewiesen war.
* Modelle, die DeepMask später hinzufügt, werden bestehenden Schlüsseln nicht hinzugefügt.
* `created` ist immer `0`, und `owned_by` ist immer `deepmask`.
* Das Abrufen eines einzelnen Modells mit `GET /v1/models/{id}` wird nicht unterstützt und gibt `404` zurück.

Das Auflisten von Modellen wird nicht abgerechnet. Unter [Modelle](https://documentation.deepmask.io/de/api/models.md) vergleichen Sie Kontextfenster und Preise.

## Was abgerechnet wird

Sie zahlen für die Eingabe- und Ausgabe-Tokens jeder Anfrage. Dazu gehören Bilder, Tool-Definitionen, Tool-Aufrufe, Tool-Ergebnisse und verborgene Reasoning-Tokens. Wie Bilder gezählt werden, erfahren Sie unter [Wie Bilder abgerechnet werden](#wie-bilder-abgerechnet-werden). Preise, zwischengespeicherte Eingaben und Preise für lange Prompts finden Sie unter [So funktionieren die Preise](https://documentation.deepmask.io/de/api/models.md#so-funktionieren-die-preise).

Eine Anfrage hat ein unklares Ergebnis, wenn DeepMask nicht feststellen kann, ob sie abgeschlossen wurde. Beispiele sind ein Serverfehler oder ein Timeout beim Modellanbieter, ein Stream, der mittendrin abbricht, und eine Anfrage, die das 15-Minuten-Limit erreicht. DeepMask berechnet diese Anfragen nicht. Ein unklares Ergebnis allein pausiert die Anfragen Ihrer Organisation nicht. Wird für eine solche Anfrage später noch Nutzung gemeldet, rechnet DeepMask diese Nutzung wie jede andere Nutzung ab. Mehr als 20 unklare Ergebnisse innerhalb von 24 Stunden pausieren die Anfragen Ihrer Organisation, bis DeepMask die Ergebnisse geklärt hat. Siehe [Unklare Ergebnisse](https://documentation.deepmask.io/de/api/limits.md#unklare-ergebnisse).

Welche abgelehnten und unterbrochenen Anfragen abgerechnet werden, erfahren Sie unter [Werden fehlgeschlagene Anfragen abgerechnet?](https://documentation.deepmask.io/de/api/errors.md#werden-fehlgeschlagene-anfragen-abgerechnet).

## Häufige Anfragefehler

Fehler dieser Endpunkte haben alle dieselbe JSON-Struktur. Die `message` ändert sich nie. Behandeln Sie Fehler deshalb anhand des HTTP-Status und des Werts von `error.code`.

```json theme={null}
{
  "error": {
    "message": "DeepMask API request could not be completed.",
    "type": "api_error",
    "code": "API_REQUEST_UNBOUNDED"
  }
}
```

| Status | Code | Ursache |
| - | - | - |
| `400` | `API_REQUEST_INVALID` | Der Anfragetext ist kein gültiges JSON oder kein JSON-Objekt, `Content-Type` ist nicht `application/json`, der Anfragetext ist komprimiert, `model` fehlt oder ist kein String, `user` enthält NUL, oder ein String enthält ungültige Unicode-Zeichen. |
| `413` | `API_REQUEST_INVALID` | Der Anfragetext ist größer als 32 MiB. |
| `400` | `API_REQUEST_UNBOUNDED` | Die Anfrage verwendet ein Feld, einen Wert, eine Nachrichtenstruktur, einen Content-Part oder eine Tool-Option, die nicht unterstützt wird. |
| `400` | `API_IMAGE_INPUT_UNSUPPORTED`, `API_IMAGE_URL_UNSUPPORTED`, `API_IMAGE_INVALID` | DeepMask kann ein Bild in der Anfrage nicht annehmen, etwa weil das Modell keine Bildeingabe hat, das Bild ein Link ist oder ein Limit überschreitet. Die einzelnen Codes finden Sie unter [Bildfehler](#bildfehler). |
| `403` | `API_MODEL_NOT_ALLOWED` | Der Schlüssel hat keinen Zugriff auf das Modell, oder das Modell ist nicht mehr im Katalog. |
| `404` | `API_ENDPOINT_NOT_FOUND` | Der Pfad oder die Methode wird nicht unterstützt. |
| `4xx`, `502` oder `503` | `API_UPSTREAM_REJECTED` | Der Modellanbieter hat die Anfrage abgelehnt (`4xx`), etwa weil der Prompt zu lang ist oder das Modell einen Sampling-Wert nicht akzeptiert, oder einen Serverfehler gemeldet (`502` oder `503`). Auch ein abgelehntes Bild kann zu `502` führen. Keiner dieser Fälle wird abgerechnet, es sei denn, für einen Serverfehler wird später noch Nutzung gemeldet. |

Fehler zu Authentifizierung, Abrechnung, Ratenlimits und Ausgabenlimits finden Sie unter [Fehler und Wiederholungen](https://documentation.deepmask.io/de/api/errors.md). Raten-, Token- und Budgetlimits finden Sie unter [Limits und faire Nutzung](https://documentation.deepmask.io/de/api/limits.md).

## Verwandte Seiten

> [card] [Schnellstart](https://documentation.deepmask.io/de/api/quickstart.md)
>
> Erstellen Sie einen Schlüssel und senden Sie Ihre erste Anfrage.

> [card] [Modelle](https://documentation.deepmask.io/de/api/models.md)
>
> Sehen Sie sich Modell-IDs, Kontextfenster und Preise an.

> [card] [API-Schlüssel](https://documentation.deepmask.io/de/api/keys.md)
>
> Erstellen Sie Schlüssel, wählen Sie ihre Modelle aus und widerrufen Sie sie.

> [card] [Limits und faire Nutzung](https://documentation.deepmask.io/de/api/limits.md)
>
> Sehen Sie sich die Raten-, Token- und Budgetlimits an, die für Ihre Anfragen gelten.

> [card] [Fehler und Wiederholungen](https://documentation.deepmask.io/de/api/errors.md)
>
> Behandeln Sie jeden Fehlercode und erfahren Sie, welche Fehler Sie wiederholen sollten.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.