Audio, Images & Files.
Transcribes audio, generates speech and images, inspects inline text files with Shield and passes /v1/files and /v1/skills through.
Audio.
Not inspected by Noirdoc Shield:
/v1/audio/*and/v1/images/generationsinspect neither audio files nor text prompts (usePOST /v1/shield/inspectto check text beforehand). Under theenforcedpolicy or withX-Noirdoc-Mask: on(and on/v1/images/generationsalso withX-Noirdoc-Shield: on), the gateway fails closed with 403masking_not_supported_for_endpoint. Withdefault_onordefault_offand no inspection header, requests pass through uninspected.
POST /v1/audio/transcriptions accepts multipart/form-data in the format of the OpenAI Audio API (endpoint_family: "stt" in GET /v1/models).
POST https://api.noirdoc.de/v1/audio/transcriptions
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.noirdoc.de/v1",
api_key=os.environ["NOIRDOC_API_KEY"],
)
with open("dictation.mp3", "rb") as audio:
transcript = client.audio.transcriptions.create(
model="whisper",
file=audio,
)
print(transcript.text)import fs from "node:fs";
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.noirdoc.de/v1",
apiKey: process.env.NOIRDOC_API_KEY,
});
const transcript = await client.audio.transcriptions.create({
model: "whisper",
file: fs.createReadStream("dictation.mp3"),
});
console.log(transcript.text);curl https://api.noirdoc.de/v1/audio/transcriptions \
-H "Authorization: Bearer $NOIRDOC_API_KEY" \
-F model="whisper" \
-F file="@dictation.mp3"// 200 OK · X-Noirdoc-Provider: azure
{
"text": "The deadline for comments closes next Friday.",
}POST /v1/audio/speech accepts JSON in the format of the OpenAI Audio API (endpoint_family: "tts") and returns raw audio bytes with the provider’s Content-Type.
POST https://api.noirdoc.de/v1/audio/speech
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.noirdoc.de/v1",
api_key=os.environ["NOIRDOC_API_KEY"],
)
speech = client.audio.speech.create(
model="tts",
voice="alloy",
response_format="mp3",
input="The meeting takes place on Tuesday at 10:00.",
)
speech.write_to_file("meeting.mp3")import fs from "node:fs";
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.noirdoc.de/v1",
apiKey: process.env.NOIRDOC_API_KEY,
});
const speech = await client.audio.speech.create({
model: "tts",
voice: "alloy",
response_format: "mp3",
input: "The meeting takes place on Tuesday at 10:00.",
});
fs.writeFileSync("meeting.mp3", Buffer.from(await speech.arrayBuffer()));curl https://api.noirdoc.de/v1/audio/speech \
-H "Authorization: Bearer $NOIRDOC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "tts",
"voice": "alloy",
"response_format": "mp3",
"input": "The meeting takes place on Tuesday at 10:00."
}' \
--output meeting.mp3HTTP/1.1 200 OK
content-type: audio/mpeg
x-noirdoc-provider: azure
<MP3 audio bytes>| Area | Noirdoc behaviour |
|---|---|
Transcription (stt) | Multipart body at most 26 MB (26 × 1024 × 1024 bytes including form fields, otherwise 413 request_too_large). model, stream and response_format may each appear at most once (otherwise 400 invalid_multipart_body). Requires Allow file attachments and images in requests under Models → Shield (otherwise 403 file_content_not_allowed). |
response_format & billing (stt) | Billed by audio duration. When response_format is json, text or omitted, the gateway requests verbose_json upstream to read duration and converts back to your requested format (returning verbose_json unchanged if duration is absent). verbose_json, srt and vtt pass through unchanged. |
Text-to-speech (tts) | Requires input (1 to 4,096 characters) and a non-empty voice string (otherwise 400 invalid_tts_request). Billed by character count in input. |
| Streaming, methods & starter credit | POST only (405 method_not_allowed otherwise); other paths under /v1/audio/ return 404 unsupported_endpoint. stream (true, 1, yes, on) or stream_format returns 400 streaming_not_supported_for_endpoint. Non-starter managed models on starter credit return 403 starter_model_not_allowed. X-Noirdoc-Provider names the provider. |
| Status | Code | Meaning |
|---|---|---|
| 400 | model_required | The request names no model (model in the body, or in the form field for /v1/audio/transcriptions). |
| 400 | wrong_endpoint_for_model | The model belongs to a different endpoint family or API format than the endpoint called. |
| 400 | streaming_not_supported_for_endpoint | The request asks for streaming, but the endpoint does not support it. |
| 400 | invalid_request_body | The body is not a JSON object or not encoded in UTF-8. |
| 400 | invalid_tts_request | input or voice is missing or empty, or input is too long. |
| 400 | invalid_multipart_body | The body is not valid multipart/form-data, or model, stream or response_format appears more than once. |
| 403 | starter_model_not_allowed | The organisation is still using only its starter credit, and the model or its managed provider is not included in starter credit. |
| 403 | masking_not_supported_for_endpoint | The endpoint supports neither Noirdoc Shield nor legacy masking, yet the policy is enforced or the request sends X-Noirdoc-Mask: on (and on /v1/images/generations also X-Noirdoc-Shield: on). During the legacy masking transition until 30.11.2026, this also affects /v1/embeddings and /v1/rerank on pre-existing organisations that have not switched to Shield yet. |
| 403 | file_content_not_allowed | The request contains files, images or audio, and the organisation does not allow file content. |
| 405 | method_not_allowed | The endpoint accepts only POST. |
| 413 | request_too_large | The body exceeds the endpoint's size limit. |
Images.
Generates images from a text prompt in the format of the OpenAI Images API (endpoint_family: "image_gen" in GET /v1/models) and returns base64-encoded image data in data[].b64_json.
POST https://api.noirdoc.de/v1/images/generations
import base64
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.noirdoc.de/v1",
api_key=os.environ["NOIRDOC_API_KEY"],
)
img = client.images.generate(
model="black-forest-labs/FLUX.1-schnell",
prompt="A North Sea lighthouse at sunrise",
size="1024x1024",
n=1,
)
raw = base64.b64decode(img.data[0].b64_json or "")
with open("lighthouse.png", "wb") as f:
f.write(raw)import fs from "node:fs";
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.noirdoc.de/v1",
apiKey: process.env.NOIRDOC_API_KEY,
});
const img = await client.images.generate({
model: "black-forest-labs/FLUX.1-schnell",
prompt: "A North Sea lighthouse at sunrise",
size: "1024x1024",
n: 1,
});
const png = Buffer.from(img.data?.[0]?.b64_json ?? "", "base64");
fs.writeFileSync("lighthouse.png", png);curl https://api.noirdoc.de/v1/images/generations \
-H "Authorization: Bearer $NOIRDOC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "black-forest-labs/FLUX.1-schnell",
"prompt": "A North Sea lighthouse at sunrise",
"size": "1024x1024",
"n": 1
}'// 200 OK · X-Noirdoc-Provider: ionos
{
"created": 1763180400,
"data": [
{
"b64_json": "iVBORw0KGgoAAAANSUhEUgAABAAAAAQACAIAAADwf7zU...",
},
],
}| Field / area | Noirdoc rule |
|---|---|
prompt & Shield | Non-empty string (otherwise 400 invalid_image_request). Not inspected by Shield: enforced, X-Noirdoc-Shield: on or X-Noirdoc-Mask: on fails closed with 403 masking_not_supported_for_endpoint. |
n & size | n integer from 1 to 10 (default 1). size as WIDTHxHEIGHT with each side 1 to 2048 pixels (defaults to 1024x1024; "auto" is rejected with 400 invalid_image_request). Tighter model limits at the provider return provider_rejected_request. |
| Total megapixels | At most 16 megapixels per request (n × rounded-up 1024 × 1024 units per image: 1024x1024 = 1 unit → up to 10 images; 1536x1024 = 2 units; 2048x2048 = 4 units → up to 4 images; otherwise 400 invalid_image_request). |
| Billing & starter credit | Billed per image (data count) or per megapixel (from response size, else request size, else 1024x1024; see Models & pricing). Non-starter managed models on starter credit return 403 starter_model_not_allowed. |
| Streaming & subroutes | POST only (405 method_not_allowed otherwise); "stream": true returns 400 streaming_not_supported_for_endpoint; /v1/images/edits and other paths under /v1/images/ return 404 unsupported_endpoint. |
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request_path | The path contains a dot segment (. or ..), a %, a backslash or a control character. |
| 400 | model_required | The request names no model (model in the body, or in the form field for /v1/audio/transcriptions). |
| 400 | wrong_endpoint_for_model | The model belongs to a different endpoint family or API format than the endpoint called. |
| 400 | streaming_not_supported_for_endpoint | The request asks for streaming, but the endpoint does not support it. |
| 400 | invalid_request_body | The body is not a JSON object or not encoded in UTF-8. |
| 400 | provider_rejected_request | The provider itself rejected the request, for example because of an invalid parameter or a context that is too long. The response carries the provider's status code (400, 404, 409, 413, 422 or another 4xx status code except 401, 402, 403 and 429), and message contains the provider's message, shortened and sanitised, at most 500 characters. On routes with your own provider key (BYOK) the gateway also reports the provider's status codes 401, 402, 403 and 429 this way, because the key, credit and quota belong to the customer; with 429 it adds Retry-After. |
| 400 | invalid_image_request | prompt, n or size is outside the gateway's limits; message names the parameter. |
| 400 | invalid_request_tags | The X-Noirdoc-Tags header or the tag name in the path under /v1/tags is empty, contains more than 5 tags or does not match the format ^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,63}$. |
| 401 | invalid_api_key | The key is missing, invalid or deactivated, or the organisation is not active. |
| 402 | insufficient_credit | The organisation's credit is used up or lower than the estimated maximum cost of the request (including Noirdoc Shield, also on BYOK routes when Shield is active). |
| 402 | key_budget_exhausted | This key's budget is used up for the current period or does not cover the estimated cost of the request. |
| 402 | tag_budget_exhausted | The budget of a tag named in X-Noirdoc-Tags is used up for the current period or does not cover the estimated cost of the request; message names the tag. |
| 403 | model_not_allowed_for_key | The model is not one of this key's allowed models. |
| 403 | provider_not_allowed_for_tenant | The organisation counts as bound by professional secrecy (§ 203 StGB); this excludes every provider that offers this model. |
| 403 | provider_not_allowed_for_key | The key's restrictions (providers, data residency, CLOUD Act, § 203) exclude every provider of this model. |
| 403 | starter_model_not_allowed | The organisation is still using only its starter credit, and the model or its managed provider is not included in starter credit. |
| 403 | masking_not_supported_for_endpoint | The endpoint supports neither Noirdoc Shield nor legacy masking, yet the policy is enforced or the request sends X-Noirdoc-Mask: on (and on /v1/images/generations also X-Noirdoc-Shield: on). During the legacy masking transition until 30.11.2026, this also affects /v1/embeddings and /v1/rerank on pre-existing organisations that have not switched to Shield yet. |
| 403 | model_not_billable | The model has no complete price on record, so it cannot be used with credit. |
| 403 | request_tags_disabled | The request sends X-Noirdoc-Tags or calls /v1/tags, but request tags (Preview) are not enabled for this organisation. |
| 403 | tag_not_found | The named tag does not exist. On requests with X-Noirdoc-Tags, automatic tag creation is turned off (status code 403); on /v1/tags/{name}, the gateway answers with status code 404. |
| 403 | tag_disabled | A tag named in X-Noirdoc-Tags is deactivated. |
| 403 | tag_limit_exceeded | The organisation has reached the maximum of 1,000 request tags. |
| 403 | model_not_allowed_for_tag | The model is not one of the allowed models of a tag named in X-Noirdoc-Tags. |
| 403 | provider_not_allowed_for_tag | The restrictions of a tag named in X-Noirdoc-Tags (providers, data residency, CLOUD Act, § 203) exclude every provider of this model. |
| 404 | model_not_available | The model ID is not available to the organisation. |
| 405 | method_not_allowed | The endpoint accepts only POST. |
| 413 | request_too_large | The body exceeds the endpoint's size limit. |
| 429 | starter_rate_limit_exceeded | The organisation is still using only its starter credit and has reached the limit of 5 requests per minute or 25 requests per day (UTC) for managed providers. The response contains Retry-After with the wait in seconds. |
| 429 | resource_exhausted | The provider reported capacity problems or exhausted credit (status code 429 or 402), even after failover across up to three providers. The response contains Retry-After with the wait in seconds. |
| 500 | internal_error | An unexpected error occurred in the gateway. |
| 502 | provider_not_configured | The organisation has no suitable provider set up for this request. |
| 502 | provider_misconfigured | The configuration of the selected provider is invalid, for example a base URL that is not allowed. |
| 502 | provider_unreachable | The gateway could not connect to the provider, or the connection dropped. |
| 502 | provider_error | The provider answered with an error (status code 5xx except 503 and 529, or 401 and 403 on routes with a provider managed by Noirdoc) that the request did not cause. The gateway replaces the provider's message with a fixed text. On routes with your own provider key it reports 401 and 403 as provider_rejected_request. |
| 503 | capacity_exhausted | All providers of the model were at their capacity limit or paused after a 429, even after a wait of up to 10 seconds. The response contains Retry-After with the seconds until a provider is expected to be free again, at most 60, or 5 seconds if that is not known. |
| 503 | provider_overloaded | The provider reported overload (status code 503 or 529), even after failover across up to three providers. The status code is 503 on OpenAI endpoints and 529 on /v1/messages and /v1/skills. The response contains Retry-After with the provider's value between 1 and 60 seconds, otherwise 5 seconds. |
| 503 | service_overloaded | The gateway is temporarily at capacity. The response contains Retry-After with 5 seconds. |
| 503 | forwarding_pool_exhausted | All of the gateway's connections to the providers are in use. This is a limit of the gateway, not of a provider. The response contains Retry-After with 5 seconds. |
| 503 | provider_auth_unavailable | The gateway's credentials for the provider are currently unavailable. The response contains Retry-After with 5 seconds. |
| 504 | provider_timeout | The provider did not answer within the gateway's timeout. The response contains Retry-After with 10 seconds. |
Files & Skills.
Under Models → Shield (Advanced settings), the toggle Allow file attachments and images in requests (allow_file_content, default: on) gates all file paths. When switched off, messages with file, image, audio or file_id parts as well as all requests to /v1/files, /v1/skills and /v1/audio/transcriptions return 403 file_content_not_allowed.
Inline attachments (with Shield inspection for UTF-8 text)
When you embed files inline as base64 data: URLs on /v1/chat/completions, /v1/responses or /v1/messages, Noirdoc Shield decodes and inspects inline UTF-8 text files (text/*, JSON, XML, CSV, Markdown, YAML under 4 MiB decoded; at most 4 MiB of inspected text in total or 413 shield_input_too_large) before forwarding. Binary documents (PDF, DOCX, XLSX, PPTX), images, audio and file_id references cannot be inspected as text: under enforced the gateway rejects with 422 shield_uninspectable_content (extract text client-side first); without enforced, Shield inspects all text fields and marks the response X-Noirdoc-Shield: partial; redacted=<n> and X-Noirdoc-Masked: false.
curl https://api.noirdoc.de/v1/chat/completions \
-H "Authorization: Bearer $NOIRDOC_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Noirdoc-Shield: on" \
-d '{
"model": "qwen3.8-27b",
"messages": [{
"role": "user",
"content": [
{"type": "text", "text": "Summarise the meeting notes."},
{
"type": "file",
"file": {
"filename": "notes.txt",
"file_data": "data:text/plain;base64,Sm9uYXMgQmVja2Vy..."
}
}
]
}]
}'Passthrough via /v1/files and /v1/skills
/v1/files and /v1/skills forward uploads, retrievals and deletions unchanged and without Shield inspection to the provider (body up to 600 MB, no gateway surcharge).
POST https://api.noirdoc.de/v1/files
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.noirdoc.de/v1",
api_key=os.environ["NOIRDOC_API_KEY"],
)
with open("contract.pdf", "rb") as f:
uploaded = client.files.create(file=f, purpose="user_data")
print(uploaded.id)import fs from "node:fs";
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.noirdoc.de/v1",
apiKey: process.env.NOIRDOC_API_KEY,
});
const uploaded = await client.files.create({
file: fs.createReadStream("contract.pdf"),
purpose: "user_data",
});
console.log(uploaded.id);curl https://api.noirdoc.de/v1/files \
-H "Authorization: Bearer $NOIRDOC_API_KEY" \
-H "X-Provider: anthropic" \
-F file="@contract.pdf"// 200 OK · X-Noirdoc-Masked: false
{
"id": "file-7f3a91c2",
"object": "file",
"bytes": 184320,
"created_at": 1763180400,
"filename": "contract.pdf",
"purpose": "user_data",
}| Area | Noirdoc behaviour |
|---|---|
Fail-closed under enforced | Because /v1/files and /v1/skills are not inspected by Shield, under enforced or with X-Noirdoc-Mask: on the gateway rejects all write methods (anything other than GET, HEAD, OPTIONS, DELETE) with 403 masking_not_supported_for_endpoint. Listing, retrieving, GET /v1/files/{id}/content and deleting remain permitted. |
Provider selection (X-Provider) | Both routes carry no model and route to your organisation’s oldest active provider of the chosen format (BYOK first; Claude via Google Vertex is not used; 502 provider_not_configured if none exists; provider allowlists and starter-credit rules such as starter_model_not_allowed still apply). On /v1/files, Authorization: Bearer or api-key selects OpenAI format and x-api-key selects Anthropic format; X-Provider: anthropic or X-Provider: openai (lowercase) overrides that choice. /v1/skills always targets Anthropic (X-Provider has no effect). For Anthropic, the gateway appends files-api-2025-04-14 or skills-2025-10-02 to anthropic-beta. |
| Managed providers | On shared platform accounts, the gateway isolates objects per organisation: list calls return only your organisation’s files plus Anthropic’s pre-built skills (pages may therefore contain fewer items than limit), foreign {id} lookups return 404 object_not_found, unsupported methods return 403 endpoint_not_available_on_platform, and an unavailable ownership store returns 503 ownership_check_unavailable. Not applied on BYOK routes. |
| Subroutes & headers | Supported routes are POST|GET /v1/files, GET|DELETE /v1/files/{id}, GET /v1/files/{id}/content as well as /v1/skills, /v1/skills/{id}, /v1/skills/{id}/versions and /v1/skills/{id}/versions/{version} (other subpaths return 404 unsupported_endpoint). Successful passthrough responses carry X-Noirdoc-Masked: false without X-Noirdoc-Provider or X-Noirdoc-Shield (upstream errors include X-Noirdoc-Provider). |
Legacy file analysis (sunset
2026-11-30): Existing organisations still running legacy masking during the transition until2026-11-30continue to evaluatefile_analysis_mode(passthrough,detect_only,pseudonymize,blockreturning 403file_pii_blocked) on embedded documents up to 25 MB by default (returning 422file_unprocessableinpseudonymize/blockwhen oversized or unreadable, and reversing placeholders onGET /v1/files/{id}/contentdownloads). Switching to Noirdoc Shield under Models → Shield replaces those modes with stateless UTF-8 text inspection.
| Status | Code | Meaning |
|---|---|---|
| 403 | endpoint_not_available_on_platform | The call would read data from the shared account of a provider managed by Noirdoc and is blocked there. |
| 403 | starter_model_not_allowed | The organisation is still using only its starter credit, and the model or its managed provider is not included in starter credit. |
| 403 | shield_violation | Noirdoc Shield blocked the request before forwarding to the provider because an active protection filter configured with block matched; message names the triggered rule (secrets, pii, ner, injection or custom). |
| 403 | masking_not_supported_for_endpoint | The endpoint supports neither Noirdoc Shield nor legacy masking, yet the policy is enforced or the request sends X-Noirdoc-Mask: on (and on /v1/images/generations also X-Noirdoc-Shield: on). During the legacy masking transition until 30.11.2026, this also affects /v1/embeddings and /v1/rerank on pre-existing organisations that have not switched to Shield yet. |
| 403 | file_content_not_allowed | The request contains files, images or audio, and the organisation does not allow file content. |
| 403 | file_pii_blocked | A file contains personal data, and the organisation's legacy file analysis (transition until 30.11.2026) is set to block or to detect_only under enforced. |
| 404 | unsupported_endpoint | The gateway does not know this path. |
| 404 | object_not_found | The object (file, skill or stored response) does not exist or does not belong to your organisation. |
| 413 | request_too_large | The body exceeds the endpoint's size limit. |
| 413 | shield_input_too_large | The text to inspect in this request exceeds the Shield service limit of 4 MiB of encoded text in a single call. |
| 422 | shield_uninspectable_content | The Shield policy is enforced, and the request carries content that Shield cannot inspect as text (binary_document such as PDF or Office, media_not_inspectable such as images, audio or video, file_reference by ID or URL, file_too_large at 4 MiB or above, file_not_decodable or unrecognised_content). The gateway did not forward the request. |
| 422 | file_unprocessable | A file could not be processed in legacy file analysis (transition until 30.11.2026): it is too large, unreadable or in a format without analysis. The gateway did not forward the request. |
| 500 | file_analysis_error | Reserved for file analysis errors. The gateway does not currently send this code. |
| 502 | provider_not_configured | The organisation has no suitable provider set up for this request. |
| 503 | ownership_check_unavailable | The gateway could not check just now whether the object belongs to your organisation and rejected the request. The response contains Retry-After with 5 seconds. |