# Synthesizes speech from text

Returns raw audio, never SSE or a JSON success envelope. Default format is pcm; every
route declares its formats, voices and input-character limit. Voice is model-dependent;
current explicit-voice routes reject omission as not_available, without guessing a voice.
Turn-list syntax is recognized but rejected as not_available before provider I/O on
current text-only routes; it is never concatenated or split into paid calls. Unicode scalar values of
`input` determine the exact character charge, separately from token counters. Text
accepted by a provider is payable even if the client later disconnects or audio fails.
Generation lookup returns the EUR charge and `api_type: tts`. The final audio byte is
withheld until its durable generation is confirmed. Client disconnects either cancel the
upstream immediately or drain it without retaining audio, according to the provider profile.
Output is limited to 32 MiB, without collecting the whole audio.
Midstream errors terminate the byte stream and record a catalog failure; they cannot be
inserted as JSON into audio. Errors before commitment use the normal JSON error catalog.

Im öffentlichen Katalog ist derzeit kein geeignetes Beispielmodell bestätigt. YOUR_MODEL_ID vor dem Senden durch ein verfügbares Modell für diesen Endpunkt ersetzen.

`POST https://api.tokenlane.de/v1/audio/speech`

## Authentifizierung

[
  [
    {
      "name": "Authorization",
      "description": "API-Key als Bearer-Token im Header `Authorization`: `Authorization: Bearer sk-tl-v1-…`. Bestehende `sk-eu-`-Keys bleiben gültig. Fehlende, unbekannte oder abgelaufene Keys erhalten 401 `authentication`.",
      "type": "http bearer",
      "location": "",
      "scopes": []
    }
  ]
]

Werte mit YOUR_ sind Platzhalter. Vor dem Senden durch passende eigene Werte ersetzen.

## curl

```curl
curl --request POST \
  --url 'https://api.tokenlane.de/v1/audio/speech' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "input": "Hello from Europe.",
  "model": "YOUR_MODEL_ID",
  "response_format": "mp3",
  "voice": "en_paul_neutral"
}'
```

## node

```node
const response = await fetch("https://api.tokenlane.de/v1/audio/speech", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.TOKENLANE_API_KEY,
    "Content-Type": "application/json",
  },
  body: `{
  "input": "Hello from Europe.",
  "model": "YOUR_MODEL_ID",
  "response_format": "mp3",
  "voice": "en_paul_neutral"
}`,
});
console.log(await response.text());
```

## python

```python
import os
import urllib.request

body = (r'''{
  "input": "Hello from Europe.",
  "model": "YOUR_MODEL_ID",
  "response_format": "mp3",
  "voice": "en_paul_neutral"
}''').encode("utf-8")

request = urllib.request.Request(
    "https://api.tokenlane.de/v1/audio/speech",
    method="POST",
    headers={
        "Authorization": "Bearer " + os.environ["TOKENLANE_API_KEY"],
        "Content-Type": "application/json",
    },
    data=body,
)

with urllib.request.urlopen(request) as response:
    print(response.read().decode("utf-8"))
```

## vercel

```vercel
// This operation uses HTTP directly.
const response = await fetch("https://api.tokenlane.de/v1/audio/speech", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.TOKENLANE_API_KEY,
    "Content-Type": "application/json",
  },
  body: `{
  "input": "Hello from Europe.",
  "model": "YOUR_MODEL_ID",
  "response_format": "mp3",
  "voice": "en_paul_neutral"
}`,
});
console.log(await response.text());
```

## Header: Idempotency-Key (optional)

One printable ASCII key per logical operation; retries replay the same encrypted audio without another generation or charge

### s0: string | null

{}

## Anfrageinhalt: application/json

```json
{
  "input": "Hello from Europe.",
  "model": "YOUR_MODEL_ID",
  "response_format": "mp3",
  "voice": "en_paul_neutral"
}
```

### s1: object

Speech synthesis using the selected route's explicit voice and format contract.

{}

```json
{
  "input": "Hello from Europe.",
  "model": "mistralai/voxtral-mini-tts-2603",
  "response_format": "mp3",
  "voice": "en_paul_neutral"
}
```

- input (Pflichtfeld): s231

### s231: anyOf

Speech input syntax; recognizing turn lists does not offer multi-speaker execution.

{}

anyOf: s1055

### s1055: string

Supported nonempty text, bounded to the existing character limit.

{"minLength":"1","maxLength":"65536"}

anyOf: s1056

### s1056: array

Vendor turn syntax, unavailable on the configured text-only speech routes.

{"minItems":"1"}

### s209: object

One syntactically recognized speaker turn; no configured route executes turn lists.

{}

- instructions (optional): s991

### s991: string

Optional per-turn delivery instructions, not executed on current routes.

{"maxLength":"4096"}

- text (Pflichtfeld): s992

### s992: string

Nonempty text, sharing the existing total 65536-character input limit.

{"minLength":"1","maxLength":"65536"}

- voice (optional): s993

### s993: string

Per-turn voice or inheritance from the top-level voice, never a guessed default.

{"minLength":"1","maxLength":"128"}

- instructions (optional): s232

### s232: string

Optional delivery instructions, only on routes explicitly supporting them.

{}

```json
"Speak calmly."
```

- model (Pflichtfeld): s233

### s233: string

Public speech model ID or alias.

{}

```json
"mistralai/voxtral-mini-tts-2603"
```

- provider (optional): s234

### s234: object

Provider selection, fallback and data-policy restrictions.

{}

- response_format (optional): s235

### s235: string

Output format, default pcm (24 kHz, signed 16-bit little-endian mono, without a header).
Each route declares its supported subset of mp3/pcm/wav/opus/aac/flac.

{"default":"\"pcm\""}

```json
"mp3"
```

- speed (optional): s236

### s236: number

Playback speed from 0.25 through 4, only on routes explicitly supporting it.

double

{"minimum":"0.25","maximum":"4"}

```json
1
```

- voice (optional): s237

### s237: string

Provider-specific voice, required by the currently configured explicit-voice routes.
Omission fails with not_available for those models; no default voice is invented.

{"minLength":"1","maxLength":"128"}

```json
"en_paul_neutral"
```

## Antwort 200: audio/*

Raw audio in the requested format; X-Generation-Id identifies the durable generation and exact EUR charge

### s2: string

Opaque media bytes. The response Content-Type is the validated original MIME type;
the body is binary rather than a JSON string or array.

binary

{}

```json
"binary media bytes"
```

## Antwort 200: audio/mpeg

Raw audio in the requested format; X-Generation-Id identifies the durable generation and exact EUR charge

Opaque media bytes. The response Content-Type is the validated original MIME type;
the body is binary rather than a JSON string or array.

## Antwort 200: audio/pcm

Raw audio in the requested format; X-Generation-Id identifies the durable generation and exact EUR charge

Opaque media bytes. The response Content-Type is the validated original MIME type;
the body is binary rather than a JSON string or array.

## Antwort 200: audio/wav

Raw audio in the requested format; X-Generation-Id identifies the durable generation and exact EUR charge

Opaque media bytes. The response Content-Type is the validated original MIME type;
the body is binary rather than a JSON string or array.

## Antwort 200: audio/ogg

Raw audio in the requested format; X-Generation-Id identifies the durable generation and exact EUR charge

Opaque media bytes. The response Content-Type is the validated original MIME type;
the body is binary rather than a JSON string or array.

## Antwort 200: audio/aac

Raw audio in the requested format; X-Generation-Id identifies the durable generation and exact EUR charge

Opaque media bytes. The response Content-Type is the validated original MIME type;
the body is binary rather than a JSON string or array.

## Antwort 200: audio/flac

Raw audio in the requested format; X-Generation-Id identifies the durable generation and exact EUR charge

Opaque media bytes. The response Content-Type is the validated original MIME type;
the body is binary rather than a JSON string or array.

## Antwort 400: application/json

Malformed JSON or invalid fields; collected issues identify missing text, unknown voice, unsupported format or invalid speed

```json
{
  "error": {
    "code": 400,
    "message": "deepseek/deepseek-v4.1-flsh is not a valid model ID",
    "metadata": {
      "docs_url": "/docs#description/model-not-found",
      "issues": [
        {
          "code": "unknown_model",
          "message": "deepseek/deepseek-v4.1-flsh is not a valid model ID",
          "path": "$.model"
        }
      ],
      "remedy_hint": "Did you mean deepseek/deepseek-v4.1-flash?",
      "request_id": "req_01k7tm9qz3f5c8x2v6b4n0m7hd",
      "retryable": false,
      "type": "model_not_found"
    }
  },
  "user_id": "org_01k7tm2c4e6g8j0k2m4p6r8t0v"
}
```

### s3: object

Jede Antwort mit HTTP-Status ab 400 hat diese Struktur im Fehlerformat von OpenRouter. Alle Gateway-Erweiterungen stehen unter `error.metadata`, damit OpenRouter-Clients keine unbekannte äußere Struktur erhalten. Der Abschnitt „Fehler“ in der Einführung nennt alle Fehlertypen.

{}

```json
{
  "error": {
    "code": 400,
    "message": "deepseek/deepseek-v4.1-flsh is not a valid model ID",
    "metadata": {
      "docs_url": "/docs#description/model-not-found",
      "issues": [
        {
          "code": "unknown_model",
          "message": "deepseek/deepseek-v4.1-flsh is not a valid model ID",
          "path": "$.model"
        }
      ],
      "remedy_hint": "Did you mean deepseek/deepseek-v4.1-flash?",
      "request_id": "req_01k7tm9qz3f5c8x2v6b4n0m7hd",
      "retryable": false,
      "type": "model_not_found"
    }
  },
  "user_id": "org_01k7tm2c4e6g8j0k2m4p6r8t0v"
}
```

- error (Pflichtfeld): s238

### s238: object

Fehlerbeschreibung.

{}

```json
{
  "code": 400,
  "message": "temperature must be at most 2, got 5 (and 1 more)",
  "metadata": {
    "docs_url": "/docs#description/invalid-parameter",
    "issues": [
      {
        "code": "out_of_range",
        "message": "temperature must be at most 2, got 5",
        "path": "$.temperature"
      },
      {
        "code": "invalid_value",
        "message": "messages[1].role must be one of system, developer, user, assistant, tool, got \"bot\"",
        "path": "$.messages[1].role"
      }
    ],
    "request_id": "req_01k7tm9qz3f5c8x2v6b4n0m7hd",
    "retryable": false,
    "type": "invalid_parameter"
  }
}
```

- code (Pflichtfeld): s633

### s633: integer

HTTP-Status der Antwort als Zahl.

int32

{"minimum":"0"}

```json
400
```

- message (Pflichtfeld): s634

### s634: string

Fehlerbeschreibung auf Englisch. Bei mehreren Problemen werden das erste und die Anzahl weiterer genannt. Alle stehen unter `metadata.issues`. Der Text kann sich ändern. Im Code stattdessen `metadata.type` auswerten.

{}

```json
"temperature must be at most 2, got 5"
```

- metadata (optional): s635

### s635: object

Maschinenlesbare Details: Fehlertyp, Anfrage-ID, alle Probleme, ein Lösungsvorschlag und bei Provider-Fehlern der betroffene Provider. Bei Gateway-Fehlern immer vorhanden.

{}

```json
{
  "docs_url": "/docs#description/rate-limited",
  "provider_error": {
    "category": "rate_limited",
    "provider_name": "deepinfra",
    "retry_after": 2,
    "retryable": true,
    "status": 429
  },
  "provider_name": "deepinfra",
  "remedy_hint": "Retry after the Retry-After interval, or allow fallbacks to other providers (provider.allow_fallbacks).",
  "request_id": "req_01k7tm9qz3f5c8x2v6b4n0m7hd",
  "retry_after": 2,
  "retryable": true,
  "type": "rate_limited"
}
```

- available_providers (optional): s639

### s639: array

Provider, die das Modell anbieten, wenn `provider.only` alle ausgeschlossen hat.

{}

```json
[
  "deepinfra",
  "open-inference"
]
```

### s7: string

{}

- docs_url (Pflichtfeld): s640

### s640: string

Link zum Abschnitt dieses Fehlertyps in der Dokumentation.

{}

```json
"/docs#description/model-not-found"
```

- failed_routing_step (optional): s641

### s641: string

Routing-Schritt, nach dem keine Route übrig blieb. Nur bei Routing-Fehlern.

{}

```json
"Filter by Max Price"
```

- issues (optional): s642

### s642: array

Alle erkannten Probleme der Anfrage, damit sie gemeinsam behoben werden können. Höchstens 20 Einträge. Bei Routing-Fehlern ein Eintrag je ausgeschlossener Route, bei `no_provider_available` einer je fehlgeschlagenem Versuch.

{}

### s123: object

Ein Anfrageproblem, ein Ausschlussgrund einer Route oder ein fehlgeschlagener Versuch.

{}

```json
{
  "code": "invalid_url",
  "message": "messages[2].content[0].image_url.url must be an http(s) URL or a base64 data URL",
  "path": "$.messages[2].content[0].image_url.url"
}
```

- code (Pflichtfeld): s636

### s636: string

Art des Problems. Für Programme stabil.

"required", "invalid_type", "invalid_value", "out_of_range", "empty", "invalid_url", "invalid_base64", "unsupported_media_type", "media_type_mismatch", "media_too_large", "too_many_media", "unsupported_media_transport", "media_fetch_failed", "unknown_tool", "unknown_model", "not_available", "not_allowed", "route_excluded", "bridge_failed", "provider_failed"

{}

```json
"out_of_range"
```

- message (Pflichtfeld): s637

### s637: string

Problembeschreibung auf Englisch mit dem Feld und, sofern kurz, dem gesendeten Wert.

{}

```json
"temperature must be at most 2, got 5"
```

- path (Pflichtfeld): s638

### s638: string

Position des Problems: JSONPath des Felds im Anfrageinhalt, beispielsweise `$.messages[2].content[0].image_url.url`, oder `query.<name>` bei einem Abfrageparameter.

{}

```json
"$.temperature"
```

- provider_error (optional): s643

### s643: oneOf

Sichere Provider-Diagnosen, einheitlich für HTTP-Fehler und finale Stream-Ereignisse.

{}

oneOf: s1158

### s1158: object

Provider-Diagnosen ohne vom Provider verfassten Text. HTTP-Fehler und finale SSE-Fehler verwenden dieselbe Struktur. Beliebige Upstream-Meldungen und Metadaten werden verworfen.

{}

```json
{
  "category": "rate_limited",
  "provider_name": "deepinfra",
  "retry_after": 2,
  "retryable": true,
  "status": 429
}
```

- category (Pflichtfeld): s1299

### s1299: string

Gateway-Klassifizierung anhand von HTTP-Status und erkannten Dialektkennungen.

"rate_limited", "overloaded", "invalid_request", "context_length", "content_filtered", "authentication", "billing", "timeout", "unavailable", "unknown"

{}

```json
"rate_limited"
```

- code (optional): s1300

### s1300: string

Exakte Kennung aus der festen Liste des konfigurierten Dialekts. Beliebige andere Werte werden entfernt.

{}

```json
"rate_limit_exceeded"
```

- provider_name (Pflichtfeld): s1301

### s1301: string

Konfigurierter Provider-Name. Nie ein Name aus dem Upstream-Antwortinhalt.

{}

```json
"deepinfra"
```

- retry_after (optional): s1302

### s1302: integer

Begrenzte Wartezeit in Sekunden aus dem Upstream-Header Retry-After, sofern vorhanden und numerisch.

int64

{"minimum":"0"}

```json
2
```

- retryable (Pflichtfeld): s1303

### s1303: boolean

Ob der klassifizierte Fehler vorübergehend sein kann. Bei unbekannten Fehlern wird ein sinnvoller erneuter Versuch nicht zugesichert.

{}

- status (optional): s1304

### s1304: integer

Tatsächlich vom Upstream empfangener HTTP-Status, einschließlich 200 bei nativen Fehlern. Fehlt, wenn kein HTTP-Status verfügbar ist.

int32

{"minimum":"0"}

```json
429
```

oneOf: s588

### s588: null

{}

- provider_name (optional): s644

### s644: string

Fehlgeschlagener Provider wie im Antwortfeld `provider`. Nur bei Provider-Fehlern.

{}

```json
"deepinfra"
```

- raw (optional): s645

### s645: string

Reserviertes Feld für OpenRouter-Kompatibilität. Das Gateway befüllt es nie. Freier Provider-Text wird bewusst nicht ausgegeben. Stattdessen provider_error verwenden.

{}

```json
""
```

- remedy_hint (optional): s646

### s646: string

Ein konkreter Lösungsvorschlag, beispielsweise die ähnlichste Modell-ID bei einem Tippfehler.

{}

```json
"Did you mean deepseek/deepseek-v4.1-flash?"
```

- request_id (Pflichtfeld): s647

### s647: string

Anfrage-ID. Identisch mit dem Antwortheader `x-request-id`. Diese ID bei Supportanfragen angeben.

{}

```json
"req_01k7tm9qz3f5c8x2v6b4n0m7hd"
```

- requested_providers (optional): s648

### s648: array

Unter `provider.only` genannte Provider, wenn dadurch alle Routen ausgeschlossen wurden.

{}

```json
[
  "scaleway"
]
```

- retry_after (optional): s649

### s649: integer

Wartezeit vor einem erneuten Versuch in Sekunden. Wird bei 429 und 503 auch als Header `Retry-After` gesendet.

int64

{"minimum":"0"}

```json
2
```

- retryable (Pflichtfeld): s650

### s650: boolean

Ob dieselbe unveränderte Anfrage bei einem erneuten Versuch erfolgreich sein kann, beispielsweise nach einer Zeitüberschreitung oder einem Anfragelimit. Im Gegensatz zu Fehlern, die eine geänderte Anfrage erfordern.

{}

- routing_funnel (optional): s651

### s651: array

Eingrenzung der Provider durch das Routing. Jeder Schritt nennt die Anzahl verbleibender Routen. Nur bei Routing-Fehlern, im selben Format wie bei OpenRouter.

{}

### s200: object

Ein Routing-Schritt wie unter `routing_funnel` von OpenRouter.

{}

```json
{
  "endpoint_count": 0,
  "reason": "provider.max_price",
  "step": "Filter by Max Price"
}
```

- endpoint_count (Pflichtfeld): s979

### s979: integer

Anzahl der nach diesem Schritt verbleibenden Routen beziehungsweise Modell-Provider.

{"minimum":"0"}

```json
2
```

- reason (optional): s980

### s980: string

Anfragefeld, nach dem der Schritt gefiltert hat.

{}

```json
"provider.only"
```

- step (Pflichtfeld): s981

### s981: string

Name des Schritts wie bei OpenRouter.

{}

```json
"Initial Endpoints"
```

- type (Pflichtfeld): s652

### s652: string

Stabiler Fehlertyp für die Auswertung im Code. Siehe „Fehler“ in der Einführung. Meldungen können sich ändern, der Typ bleibt stabil.

"invalid_request", "invalid_parameter", "unsupported_parameter", "context_length_exceeded", "authentication", "insufficient_credits", "workspace_budget_exceeded", "permission_denied", "moderation", "model_not_found", "no_endpoint", "not_found", "method_not_allowed", "timeout", "payload_too_large", "media_fetch_failed", "rate_limited", "provider_error", "idempotency_conflict", "idempotency_in_progress", "idempotency_unavailable", "provider_invalid_response", "no_provider_available", "byok_invalid_credential", "byok_rate_limited", "byok_unavailable", "feature_unavailable", "internal"

{}

```json
"invalid_parameter"
```

- user_id (optional): s239

### s239: string | null

Organisation des API-Keys, sofern der Key erkannt wurde.

{}

```json
"org_01k7tm2c4e6g8j0k2m4p6r8t0v"
```

## Antwort 401: application/json

API-Key fehlt, ist ungültig oder abgelaufen.

## Antwort 402: application/json

Organization, workspace or key cannot reserve the exact character/request charge

## Antwort 403: application/json

Effective access policy forbids this model

## Antwort 404: application/json

No speech route fits the requested voice, format, length or provider restrictions

## Antwort 408: application/json

Request upload or first audio bytes timed out

## Antwort 409: application/json

Conflicting, active or unavailable encrypted idempotency replay

## Antwort 413: application/json

Request body or retained structure exceeds the configured memory limit

## Antwort 429: application/json

Customer or upstream quota exhausted; Retry-After gives seconds to wait

## Antwort 500: application/json

Unexpected gateway error or durable recording unavailable

## Antwort 501: application/json

feature_unavailable: A required feature is permanently unconfigured on this gateway, for example encrypted idempotency replay without its encryption key, PII redaction without a detector, or BYOK import without import keys. Ask the operator to configure it or remove the optional feature from the request. Retrying the identical request cannot enable the feature: retryable is false and no Retry-After header is sent. Temporary cache, database, detector or provider outages, pending imports and missing or revoked individual customer credentials retain their existing error types.

## Antwort 502: application/json

Safe provider failure, wrong audio MIME type or empty provider response

## Antwort 503: application/json

No provider available, memory busy or shutdown in progress
