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/completionsund/v1/images/generationsgeben404mitAPI_ENDPOINT_NOT_FOUNDzurück. SDK-Methoden, die auf diese Pfade angewiesen sind, funktionieren nicht. Dazu gehören die Responses API (client.responses) undclient.models.retrieve(). - Embeddings: Der Katalog enthält keine Embedding-Modelle. Daher schlägt
client.embeddings.create()mit einem Zugriffsfehler fehl, meist403mitAPI_MODEL_NOT_ALLOWED.
/v1/chat/completions/, gibt ebenfalls 404 zurück.
Authentifizierung
Senden Sie Ihren API-Schlüssel bei jeder Anfrage als Bearer-Token im HeaderAuthorization. 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äfixBearerwird zwischen Groß- und Kleinschreibung unterschieden. - Bei einem fehlenden, fehlerhaft formatierten, unbekannten oder widerrufenen Schlüssel erhalten Sie
401mitAPI_CREDENTIAL_INVALID.
DEEPMASK_API_KEY.
Chat Completion erstellen
Diese Anfrage sendet eine Systemnachricht und eine Benutzernachricht angpt-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.
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 Felderrole 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:
typemit dem Wert"text"undtextmit 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_controlin jedem Part. Siehe Nicht unterstützte Parameter. - Keine
developer-Rolle: Verwenden Sie stattdessensystem. namenur bei Tool-Nachrichten: Entfernen Sienameaus System-, Benutzer- und Assistant-Nachrichten.- Tool-Aufrufe: Eine Assistant-Nachricht kann 1–128 Tool-Aufrufe enthalten. Jeder Aufruf hat eine
idmit 1–100 Zeichen,type: "function"und einfunction-Objekt mitnameundarguments, 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.
Sampling-Optionen
Viele SDKs, Frameworks und Coding-Agents senden bei jeder Anfrage Sampling-Optionen mit. DeepMask akzeptierttemperature, 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 zu400mitAPI_REQUEST_UNBOUNDED. Manche Modelle akzeptieren fürtemperatureeinen 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 wie1.5oder"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 Sieseeddaher für exakte Ergebnisse im Bereich von ±9.007.199.254.740.991. nullbedeutet nicht gesetzt: DeepMask behandelt eine Option mit dem Wertnullso, als hätten Sie sie weggelassen.nnur als 1:n: 1wird akzeptiert, weil es der Standardwert ist. Jeder andere Wert, etwa2oder0, führt zu400mitAPI_REQUEST_UNBOUNDED. Wenn Sie mehrere Antworten benötigen, senden Sie für jede eine eigene Anfrage.stopals 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 ohnestop.gpt-4o,gpt-4.1,o3-miniundmistral-large-3erhalten solche Sequenzen unverändert. Die anderen Modelle ignorierenstop. Siehe Optionen, die manche Modelle ignorieren. - Anfragegröße:
stopzä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.6undsonnet-4.6akzeptierentemperaturenur von 0 bis 1. Dasselbe gilt fürdeepseek-v3.2,glm-4.7,glm-4.7-flash,glm-5,kimi-k2.5,minimax-m2.1,minimax-m2.5,nemotron-3-superundqwen3-235b-2507. Einen höheren Wert lehnt der Modellanbieter mit einem4xx-Status undAPI_UPSTREAM_REJECTEDab. Diese Ablehnung wird nicht abgerechnet.temperaturebei Claude-Modellen ab Version 4.7: Diese Modelle ignorierentemperature, 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_REJECTEDund wird nicht abgerechnet.
Nicht unterstützte Parameter
Diese Parameter und Eingaben führen zu400 mit API_REQUEST_UNBOUNDED, sofern die Zeile keinen anderen Code nennt.
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_tokensweglassen, setzt DeepMask kein eigenes Limit. Es gilt die Standard-Ausgabelänge des Modells, und diese kann unter dem Maximum des Modells liegen. Setzen Siemax_tokens, wenn Sie lange Antworten erwarten. - GLM-4.7-Modelle:
glm-4.7undglm-4.7-flashstoppen bei 65.536 Ausgabe-Tokens, sofern Siemax_tokensnicht 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
400undAPI_REQUEST_UNBOUNDEDabgelehnt. - Reasoning-Tokens zählen mit: Bei Reasoning-Modellen wie
o3-miniund bei den Claude-Modellen mit dauerhaft aktivem Thinking werden verborgene Reasoning-Tokens aufmax_tokensangerechnet. 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_reasonden Wertlength. 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
timeoutdes 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
413mitAPI_REQUEST_INVALID. - Unkomprimiert: Senden Sie den Anfragetext ohne Komprimierung. Ein Anfragetext mit einem
Content-Encoding-Header wiegzip,deflateoderbrwird mit400undAPI_REQUEST_INVALIDabgelehnt. 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_choiceundstopdü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 mit400undAPI_REQUEST_UNBOUNDEDabgelehnt. - 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
429mitAPI_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 undAPI_UPSTREAM_REJECTEDab. 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
400mitAPI_IMAGE_INPUT_UNSUPPORTED. - Nicht in der Modellliste:
GET /v1/modelszeigt 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.
Bild-Parts
Ein Bild-Part steht imcontent-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:
typemit dem Wert"image_url"undimage_url. Andere Felder, etwacache_control, werden abgelehnt. - Felder von
image_url:image_urlist ein Objekt miturlund einem optionalendetail. Andere Felder, etwaformat, 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"undnull, werden abgelehnt. Beigpt-4oundgpt-4.1verbraucht"low"deutlich weniger Tokens. Die Claude-Modelle akzeptierendetail, ignorieren es aber.- Nur Benutzernachrichten: Ein Bild-Part in einer
system-,assistant- odertool-Nachricht wird abgelehnt. - Bilder ohne Text: Eine Benutzernachricht kann Bild-Parts ohne einen Text-Part enthalten.
- Format von Chat Completions: Verwenden Sie
image_url- undtext-Parts. Parts der Responses API werden abgelehnt. Eininput_image-Part mit einer Base64-Data-URL führt zum Beispiel zuAPI_IMAGE_INVALID, eininput_text-Part zuAPI_REQUEST_UNBOUNDED.
Bilddaten
Dieurl 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/gifoderimage/webp. Andere Formate wie SVG, HEIC, BMP oder PDF werden abgelehnt. - JPEG-Bezeichnung:
image/jpgwird ebenfalls akzeptiert. DeepMask sendet es alsimage/jpegan das Modell. - Passender Typ: Der angegebene Typ muss zu den Bytes des Bildes passen. Eine JPEG-Datei mit der Angabe
image/pngwird 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
base64unter Linux bricht Zeilen standardmäßig um. Verwenden Sie daherbase64 -w 0oder 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
400mitAPI_IMAGE_INVALIDzurü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 zu400, 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_UNSUPPORTEDunddetail: "high"trotzdem zuAPI_IMAGE_INVALID. - Ursache finden:
API_IMAGE_INVALIDnennt nicht, welche Regel verletzt wurde. Unter macOS und Linux zeigtfile photo.pngdas 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_REJECTEDfehl. Je nach Modell ist der Status der eigene4xx-Status des Anbieters oder502. 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 vonprompt_tokens und werden zum Preis für Eingabe des Modells abgerechnet. Einen separaten Preis für Bilder gibt es nicht.
- Keine separate Angabe:
usageweist 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.1etwa 1.450 und beigpt-4oetwa 1.700. Ein Bild mit 512 × 512 Pixeln verbrauchte etwa 250 bis 370 Tokens. detail: "low": Beigpt-4oundgpt-4.1verbrauchte 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-4oundgpt-4.1kann 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.modelist die API-Modell-ID, die Sie gesendet haben, etwagpt-4o.choices[0].messageenthält die Antwort. Wenn das Modell Tools aufruft, kanncontentnullsein, undtool_callslistet die Aufrufe auf.usagegibt die Eingabe-Tokens (prompt_tokens) und die Ausgabe-Tokens (completion_tokens) der Anfrage an.
Abschlussgründe
Die häufigsten Werte fürfinish_reason sind:
Streaming
Setzen Siestream 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.
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 Sieinclude_usageauftruesetzen. Seinchoices-Array kann leer sein. Prüfen Sie es daher, bevor Siechoices[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 Beispieldata: {"error":{"message":"DeepMask API request could not be completed.","type":"api_error","code":"API_UPSTREAM_REJECTED"}}. Prüfen Sie jedes Event auf einerror-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 ohnedata: [DONE]endet, als unvollständig. Die OpenAI-SDKs blenden[DONE]aus. Behandeln Sie dort einen Stream als unvollständig, wenn kein Chunk einenfinish_reasonenthä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.get_weather.
message in die zweite Anfrage und verwenden Sie die id jedes Aufrufs als tool_call_id.
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ützttools 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.5undopus-5.5akzeptieren 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 einedescription. Ohne sie lehnt der Anbieter die Anfrage mit422undAPI_UPSTREAM_REJECTEDab. Diese Ablehnung wird nicht abgerechnet.
Regeln für Tool-Definitionen
Funktionsdefinitionen
Funktionsdefinitionen
- Jeder Eintrag in
toolshat genau zwei Felder:typemit dem Wert"function"undfunction. functionkannname,description,parametersundstrictenthalten. Andere Felder werden abgelehnt.namehat 1–64 Zeichen: Buchstaben, Ziffern, Unterstriche und Bindestriche.descriptionist ein String.parametersist ein JSON-Schema-Objekt. Es darf bis zu 32 Ebenen tief verschachtelt sein, und jede Zahl muss endlich sein.strictist ein boolescher Wert.
Schemas mit $ref
Schemas mit $ref
- Nur lokale Verweise funktionieren:
#,#/$defs/name,#/definitions/nameoder ein anderer JSON-Pointer innerhalb desselben Schemas. - Remote-Verweise und Pointer mit einem maskierten Schrägstrich (
%2F) werden abgelehnt. - Ein Schema mit
$refdarf weder$idunterhalb seiner Wurzel (oder ein$idauf der Wurzelebene mit einem#-Fragment) noch$anchor,$dynamicRef,$dynamicAnchor,$recursiveRefoder$recursiveAnchorenthalten. Es darf auch kein$schemafür Draft-03 oder Draft-04 deklarieren. - Eine Eigenschaft, die wörtlich
$refoder$idheiß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_choiceundstopmü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-miniundmistral-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.
createdist immer0, undowned_byist immerdeepmask.- Das Abrufen eines einzelnen Modells mit
GET /v1/models/{id}wird nicht unterstützt und gibt404zurück.
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. Diemessage ä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.