Zum Hauptinhalt springen
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. Für Ihren ersten Aufruf folgen Sie dem Schnellstart.
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.
Die Basis-URL lautet https://api.deepmask.io/v1. Administratoren der Organisation können sie auch unter Basis-URL in Benutzereinstellungen > API kopieren.

Endpunkte

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.
  • 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. Die Beispiele auf dieser Seite lesen den Schlüssel aus der Umgebungsvariable DEEPMASK_API_KEY.
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.
Die Antwort folgt dem OpenAI-Format. Die einzelnen Felder finden Sie unter Antwort.

Anfragetext

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

Nachrichten

Jede Nachricht hat die Felder role und content. In System- und Benutzernachrichten kann content ein String oder ein Array aus Content-Parts 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 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.
  • 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.
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.
  • 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.
  • 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.
  • Anfragegröße: stop zählt zum Limit von 32 MiB für Nachrichten und Tools. Siehe 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.
  • 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.
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.

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

Anfragegröße

Alle Limits für Größe und Dauer auf einen Blick finden Sie unter 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.
  • 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.

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 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.
Die Antwort hat dasselbe Format wie jede andere Chat Completion. Siehe Antwort.

Bild-Parts

Ein Bild-Part steht im content-Array einer Benutzernachricht. Sie können Bild-Parts und Text-Parts in beliebiger Reihenfolge kombinieren.
  • 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.
  • 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.

Bildfehler

Abgelehnte Bilder führen zu 400, bevor die Anfrage das Modell erreicht. Diese Ablehnungen werden daher nicht abgerechnet.
  • 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.
  • 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.

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.
  • 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.
  • 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:

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.
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:
  • 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.
  • 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.
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.
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.
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.

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

  • 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.
  • 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.
  • 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 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. Preise, zwischengespeicherte Eingaben und Preise für lange Prompts finden Sie unter 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. Welche abgelehnten und unterbrochenen Anfragen abgerechnet werden, erfahren Sie unter 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.
Fehler zu Authentifizierung, Abrechnung, Ratenlimits und Ausgabenlimits finden Sie unter Fehler und Wiederholungen. Raten-, Token- und Budgetlimits finden Sie unter Limits und faire Nutzung.

Verwandte Seiten

Schnellstart

Erstellen Sie einen Schlüssel und senden Sie Ihre erste Anfrage.

Modelle

Sehen Sie sich Modell-IDs, Kontextfenster und Preise an.

API-Schlüssel

Erstellen Sie Schlüssel, wählen Sie ihre Modelle aus und widerrufen Sie sie.

Limits und faire Nutzung

Sehen Sie sich die Raten-, Token- und Budgetlimits an, die für Ihre Anfragen gelten.

Fehler und Wiederholungen

Behandeln Sie jeden Fehlercode und erfahren Sie, welche Fehler Sie wiederholen sollten.