Entwickeln / Referenz
Maskierte Felder
Welche Felder einer Anfrage das Gateway pro Endpunkt maskiert, welche es in der Antwort zurückübersetzt und welche es bewusst unverändert lässt.
Diese Seite gilt für Anfragen, bei denen die Maskierung aktiv ist. Ob sie aktiv ist, entscheiden die Maskierungsrichtlinie Ihrer Organisation und der Header X-Noirdoc-Mask, siehe Authentifizierung & Header. Wie die Maskierung arbeitet, erklärt Maskierung.
Endpunkte
| Endpunkt | Maskierung |
|---|---|
/v1/chat/completions | ja |
/v1/responses | ja |
/v1/messages | ja |
/v1/embeddings | nein |
/v1/audio/transcriptions, /v1/audio/speech | nein |
/v1/images/generations | nein |
/v1/files, /v1/skills | nein, das Gateway reicht diese Anfragen unverändert durch |
Die Endpunkte ohne Maskierung lehnen eine Anfrage mit dem Fehlercode masking_not_supported_for_endpoint ab, wenn sie X-Noirdoc-Mask: on sendet oder die Richtlinie enforced ist. Bei /v1/files und /v1/skills gilt das für Aufrufe mit Inhalt, etwa das Hochladen; Auflisten, Abrufen, Herunterladen und Löschen bleiben erlaubt. Bei default_off und default_on ohne diesen Header leitet das Gateway den Text dort unmaskiert weiter.
Chat Completions
/v1/chat/completions
| Feld | Maskiert |
|---|---|
messages[].content als String, jede Rolle (system, developer, user, assistant, tool) | ja |
messages[].content[], Teile vom Typ text | ja |
messages[].tool_calls[].function.arguments, jeder String-Wert im JSON | ja |
image_url-, file- und input_audio-Teile | über die Dateianalyse |
tools[] (Name, Beschreibung, parameters) | nein |
response_format | nein |
Tool-Argumente sind JSON-Strings. Das Gateway zerlegt sie, maskiert jeden String-Wert einzeln und setzt das JSON wieder zusammen. Schlüssel und Struktur bleiben erhalten, die Argumente bleiben gültiges JSON. Ist ein Argument kein gültiges JSON, maskiert das Gateway es als einen Text.
Responses
/v1/responses
| Feld | Maskiert |
|---|---|
instructions als String | ja |
instructions als Liste von Einträgen | ja, wie input[] |
input als String | ja |
input[], Nachrichten mit String-Inhalt oder Teilen vom Typ input_text bzw. output_text | ja |
input[], Einträge vom Typ function_call: arguments, jeder String-Wert im JSON | ja |
input[], Einträge vom Typ function_call_output: output als String oder Textteile | ja |
input_image- und input_file-Teile | über die Dateianalyse |
tools[] (Name, Beschreibung, parameters) | nein |
text.format | nein |
Mit previous_response_id setzen Sie eine Unterhaltung fort, die beim Anbieter gespeichert ist. Das Gateway sieht diesen Verlauf nicht erneut. Es lädt aber die Zuordnung der vorherigen Antwort, damit dieselben Personen dieselben Platzhalter behalten.
Messages
/v1/messages
| Feld | Maskiert |
|---|---|
system als String | ja |
system[], Blöcke vom Typ text | ja |
messages[].content als String | ja |
messages[].content[], Blöcke vom Typ text | ja |
tool_use.input, alle String-Werte, auch verschachtelt | ja |
tool_result.content als String oder text-Blöcke | ja |
Blöcke der Code-Ausführung (server_tool_use, bash_code_execution_tool_result, text_editor_code_execution_tool_result) | ja, siehe unten |
document-Blöcke mit Textquelle (source.type text oder content), dazu title und context | ja |
citations[] in text-Blöcken: cited_text und document_title | ja |
image-Blöcke und document-Blöcke mit Base64-Quelle | über die Dateianalyse |
thinking-Blöcke aus früheren Antworten | nein |
tools[] (Name, Beschreibung, input_schema) | nein |
Frühere Antworten des Modells im Verlauf maskiert das Gateway wie Text der Nutzer. Maßgeblich ist das Feld, nicht die Rolle.
Beim Code-Ausführungs-Tool von Anthropic maskiert das Gateway in server_tool_use-Blöcken die Felder input.command, input.file_text, input.old_str und input.new_str. input.command des Text-Editors ist ein fester Befehlsname und bleibt unverändert. In den Ergebnisblöcken maskiert das Gateway stdout, stderr, content als Text und die Zeilen in lines. Dateien, die das Tool erzeugt, stehen nur als file_id im Ergebnis; sie behandelt Dateien & Skills.
Rückübersetzung in der Antwort
In der Antwort ersetzt das Gateway die Platzhalter wieder durch die Originalwerte. Das gilt auch beim Streaming.
| Endpunkt | Zurückübersetzt |
|---|---|
/v1/chat/completions | choices[].message.content, Argumente in tool_calls; beim Streaming Text- und Argument-Deltas |
/v1/responses | output_text-Teile, arguments von function_call-Einträgen; beim Streaming response.output_text.delta und response.function_call_arguments.delta |
/v1/messages | text-, thinking- und tool_use-Blöcke, Ergebnisse der Code-Ausführung und citations[] in text-Blöcken; beim Streaming text_delta, thinking_delta, input_json_delta und Ergebnisse der Code-Ausführung, nicht aber citations_delta |
Ihre Anwendung erhält Tool-Aufrufe mit echten Werten und kann sie direkt ausführen.
Enthält die Zuordnung einer Anfrage Platzhalter, aus dieser Anfrage oder aus früheren derselben Unterhaltung, stellt das Gateway eine kurze Systemanweisung voran. Sie weist das Modell an, Platzhalter wie <<PERSON_1>> als echte Werte zu behandeln. Bei /v1/chat/completions ist das eine zusätzliche system-Nachricht am Anfang von messages, bei /v1/responses ein Absatz vor instructions (wenn instructions fehlt oder ein String ist), bei /v1/messages ein Absatz bzw. Textblock vor system.
Bewusst nicht maskiert
Tool-Definitionen in tools[] (Name, Beschreibung, Schema der Parameter) gehen unverändert an den Anbieter. Das gilt ebenso für Antwort-Schemas (response_format, text.format) und technische Parameter wie model, metadata, tool_choice und die Sampling-Einstellungen. Diese Felder schreiben Entwickler, nicht die Nutzer Ihrer Anwendung. Würde das Gateway Namen oder Beschreibungen von Tools umschreiben, könnte das Modell die Tools nicht mehr zuverlässig aufrufen.
Bei /v1/messages gilt das auch für thinking-Blöcke, die Sie aus früheren Antworten in den Verlauf zurückgeben. In der Antwort hat das Gateway darin die Originalwerte wiederhergestellt. Schicken Sie die Blöcke unverändert zurück, erreichen diese Werte den Anbieter im Klartext. Das Gateway schreibt diese Blöcke in der Anfrage nicht um.
Dateien und Bilder
Dateien und Bilder, die als Base64 in der Anfrage stehen (etwa als data:-URL), prüft die Dateianalyse. Sie läuft nur, wenn die Maskierung für die Anfrage aktiv ist. Was sie tut, legt der Dateianalyse-Modus unter Models → Datenschutz fest:
| Modus | Verhalten |
|---|---|
passthrough (Standard) | keine Analyse, die Datei geht unverändert weiter |
detect_only | erkennen, die Datei geht unverändert weiter |
pseudonymize | erkennen und in der Datei maskieren |
block | Anfrage mit Statuscode 403 (file_pii_blocked) ablehnen, wenn eine Datei personenbezogene Daten enthält |
In den Modi pseudonymize und block lehnt das Gateway jede Datei, die es nicht prüfen kann, mit Statuscode 422 (file_unprocessable) ab: zu groß, nicht lesbar oder in einem Format ohne Analyse. Text in Bildern und gescannten PDFs erkennt es nur, wenn OCR für Scans und Bilder eingeschaltet ist. Ohne OCR leitet es solche Dateien ungeprüft weiter.
Dateien, die Sie nur per URL oder file_id referenzieren, lädt das Gateway nicht herunter. Es analysiert und maskiert sie nicht. Lässt die Organisation keine Dateiinhalte zu (Dateiinhalte zulassen aus), lehnt das Gateway jede Anfrage mit Datei-, Bild- oder Audioteilen mit file_content_not_allowed ab. Mehr dazu unter Dateien.
Zuordnung zwischen Anfragen
Damit Folgeanfragen derselben Unterhaltung dieselben Platzhalter erhalten, speichert das Gateway die Zuordnung verschlüsselt. Standard sind 30 Tage. Admins stellen den Wert unter Models → Datenschutz (Mapping-TTL) ein. Bei /v1/responses findet das Gateway die Zuordnung über previous_response_id, bei /v1/chat/completions und /v1/messages über den bisherigen Verlauf.