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/generations inspect neither audio files nor text prompts (use POST /v1/shield/inspect to check text beforehand). Under the enforced policy or with X-Noirdoc-Mask: on (and on /v1/images/generations also with X-Noirdoc-Shield: on), the gateway fails closed with 403 masking_not_supported_for_endpoint. With default_on or default_off and 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

Python
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)
TypeScript
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
curl https://api.noirdoc.de/v1/audio/transcriptions \
  -H "Authorization: Bearer $NOIRDOC_API_KEY" \
  -F model="whisper" \
  -F file="@dictation.mp3"
JSON
// 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

Python
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")
TypeScript
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
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.mp3
HTTP
HTTP/1.1 200 OK
content-type: audio/mpeg
x-noirdoc-provider: azure

<MP3 audio bytes>
AreaNoirdoc 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 creditPOST 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

Python
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)
TypeScript
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
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
  }'
JSON
// 200 OK · X-Noirdoc-Provider: ionos
{
  "created": 1763180400,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAABAAAAAQACAIAAADwf7zU...",
    },
  ],
}
Field / areaNoirdoc rule
prompt & ShieldNon-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 & sizen 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 megapixelsAt 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 creditBilled 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 & subroutesPOST 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.

Send an inline UTF-8 text file with Shield
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

Python
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)
TypeScript
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
curl https://api.noirdoc.de/v1/files \
  -H "Authorization: Bearer $NOIRDOC_API_KEY" \
  -H "X-Provider: anthropic" \
  -F file="@contract.pdf"
JSON
// 200 OK · X-Noirdoc-Masked: false
{
  "id": "file-7f3a91c2",
  "object": "file",
  "bytes": 184320,
  "created_at": 1763180400,
  "filename": "contract.pdf",
  "purpose": "user_data",
}
AreaNoirdoc behaviour
Fail-closed under enforcedBecause /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 providersOn 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 & headersSupported 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 until 2026-11-30 continue to evaluate file_analysis_mode (passthrough, detect_only, pseudonymize, block returning 403 file_pii_blocked) on embedded documents up to 25 MB by default (returning 422 file_unprocessable in pseudonymize/block when oversized or unreadable, and reversing placeholders on GET /v1/files/{id}/content downloads). 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.