Audio — Noirdoc Docs

Beide Endpunkte nehmen nur POST an. Andere Methoden beantwortet das Gateway mit 405 method_not_allowed. Streaming unterstützen sie nicht.

Transkription

POST /v1/audio/transcriptions

Familie: stt
Maskierung: nein
Streaming: nein
Format: multipart/form-data
Abrechnung: Audiodauer

Der Body ist ein Multipart-Formular wie bei der OpenAI Audio API. model ist Pflicht und muss ein Modell der Familie stt aus GET /v1/models sein. Die Felder model, stream und response_format dürfen je nur einmal vorkommen.

Audio zählt als Dateiinhalt. Der Endpunkt funktioniert nur, wenn Admins Ihrer Organisation unter Models → Datenschutz die Option Dateiinhalte zulassen eingeschaltet haben. Sonst antwortet das Gateway mit 403 file_content_not_allowed.

Der Body darf höchstens 26 MB groß sein. Größere Anfragen lehnt das Gateway mit 413 request_too_large ab, bevor es sie weiterleitet.

Shell

curl https://api.noirdoc.de/v1/audio/transcriptions \
  -H "Authorization: Bearer $NOIRDOC_API_KEY" \
  -F model=whisper \
  -F file=@diktat.mp3

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("diktat.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("diktat.mp3"),
});
console.log(transcript.text);

Was Noirdoc ändert

Bereich	Verhalten
Modell	Das Gateway löst die Modell-ID über den Katalog auf und wählt damit den Anbieter. Die Audiodatei leitet es unverändert weiter.
`response_format`	Bei `json`, `text` oder ohne Angabe fordert das Gateway beim Anbieter `verbose_json` an, um die Audiodauer abzurechnen. Sie erhalten das Format, das Sie angefragt haben: bei `json` ein Objekt nur mit `text`, bei `text` reinen Text. Meldet der Anbieter keine Dauer, erhalten Sie seine `verbose_json`-Antwort unverändert. `verbose_json`, `srt`, `vtt` und andere Formate leitet das Gateway unverändert durch.
`stream`	Setzen Sie `stream` auf `true`, `1`, `yes` oder `on`, antwortet das Gateway mit 400 `streaming_not_supported_for_endpoint`.
Abrechnung	Das Gateway rechnet nach der Audiodauer ab, die der Anbieter in `verbose_json` meldet.
Anbieter	Der Header `X-Noirdoc-Provider` in der Antwort nennt den Anbieter.

Sprachausgabe

POST /v1/audio/speech

Familie: tts
Maskierung: nein
Streaming: nein
Format: JSON, Antwort als Audio
Abrechnung: Zeichen in input

Der Body ist JSON wie bei der OpenAI Audio API. model ist Pflicht und muss ein Modell der Familie tts aus GET /v1/models sein.

input muss ein nicht leerer Text mit höchstens 4.096 Zeichen sein. voice muss ein nicht leerer String sein. Welche Stimmen ein Modell anbietet, legt der Anbieter fest. Verstöße beantwortet das Gateway mit 400 invalid_tts_request.

Die Antwort enthält die Audiodaten so, wie der Anbieter sie liefert, mit dessen Content-Type.

Shell

curl https://api.noirdoc.de/v1/audio/speech \
  -H "Authorization: Bearer $NOIRDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts",
    "voice": "<stimme>",
    "input": "Ihr Termin ist am Dienstag um 10 Uhr."
  }' \
  --output termin.mp3

Python

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.noirdoc.de/v1",
    api_key=os.environ["NOIRDOC_API_KEY"],
)

response = client.audio.speech.create(
    model="tts",
    voice="<stimme>",
    input="Ihr Termin ist am Dienstag um 10 Uhr.",
)
response.write_to_file("termin.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 response = await client.audio.speech.create({
  model: "tts",
  voice: "<stimme>",
  input: "Ihr Termin ist am Dienstag um 10 Uhr.",
});
const audio = Buffer.from(await response.arrayBuffer());
fs.writeFileSync("termin.mp3", audio);

Was Noirdoc ändert

Bereich	Verhalten
Modell	Das Gateway löst die Modell-ID über den Katalog auf und wählt damit den Anbieter.
Streaming	Keines. Ist `stream` wahr oder `stream_format` gesetzt, antwortet das Gateway mit 400 `streaming_not_supported_for_endpoint`.
Abrechnung	Das Gateway zählt die Zeichen in `input` und rechnet sie ab.
Anbieter	Der Header `X-Noirdoc-Provider` in der Antwort nennt den Anbieter.

Unterrouten

Keine. Andere Pfade unter /v1/audio/ beantwortet das Gateway mit 404 unsupported_endpoint.

Fehler auf diesen Endpunkten

Status	Code	Bedeutung
400	`model_required`	Die Anfrage nennt kein Modell (`model` im Body, bei `/v1/audio/transcriptions` im Formularfeld).
400	`wrong_endpoint_for_model`	Das Modell gehört zu einer anderen Endpunkt-Familie oder einem anderen API-Format als der aufgerufene Endpunkt.
400	`streaming_not_supported_for_endpoint`	Die Anfrage verlangt Streaming, der Endpunkt unterstützt es aber nicht.
400	`invalid_request_body`	Der Body ist kein JSON-Objekt oder nicht in UTF-8 kodiert.
400	`invalid_tts_request`	`input` oder `voice` fehlt oder ist leer, oder `input` ist zu lang.
400	`invalid_multipart_body`	Der Body ist kein gültiges `multipart/form-data`, oder `model`, `stream` bzw. `response_format` kommt mehrfach vor.
402	`insufficient_credit`	Das Guthaben der Organisation ist aufgebraucht oder kleiner als die geschätzten Höchstkosten der Anfrage.
402	`key_budget_exhausted`	Das Budget dieses Schlüssels ist für den laufenden Zeitraum aufgebraucht oder reicht für die geschätzten Kosten der Anfrage nicht aus.
403	`model_not_allowed_for_key`	Das Modell gehört nicht zu den erlaubten Modellen dieses Schlüssels.
403	`provider_not_allowed_for_tenant`	Die Organisation gilt als Berufsgeheimnisträger (§ 203 StGB); das schließt jeden Anbieter aus, der dieses Modell anbietet.
403	`provider_not_allowed_for_key`	Die Einschränkungen des Schlüssels (Anbieter, Datenresidenz, CLOUD Act, § 203) schließen jeden Anbieter dieses Modells aus.
403	`masking_not_supported_for_endpoint`	Der Endpunkt kann nicht maskieren, aber die Maskierungsrichtlinie ist `enforced` oder die Anfrage sendet `X-Noirdoc-Mask: on`.
403	`file_content_not_allowed`	Die Anfrage enthält Dateien, Bilder oder Audio, und die Organisation lässt keine Dateiinhalte zu.
404	`model_not_available`	Die Modell-ID ist für die Organisation nicht verfügbar.
405	`method_not_allowed`	Der Endpunkt nimmt nur `POST` an.
413	`request_too_large`	Der Body überschreitet das Größenlimit des Endpunkts.
502	`provider_unreachable`	Das Gateway konnte keine Verbindung zum Anbieter herstellen, oder die Verbindung ist abgebrochen.
504	`provider_timeout`	Der Anbieter hat nicht innerhalb der Wartezeit des Gateways geantwortet.

OpenAI-Referenz

Alle übrigen Felder von Anfrage und Antwort beschreibt die API-Referenz von OpenAI: Audio (geprüft am 30.09.2026).