# 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.

No suitable example model is currently verified in the public catalog. Replace YOUR_MODEL_ID with an available model for this endpoint before sending a request.

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

## Authorizations

[
  [
    {
      "name": "Authorization",
      "description": "API key as bearer token in the `Authorization` header: `Authorization: Bearer sk-tl-v1-…`. Existing `sk-eu-` keys remain valid. Missing, unknown or expired keys get 401 `authentication`.",
      "type": "http bearer",
      "location": "",
      "scopes": []
    }
  ]
]

Values starting with YOUR_ are placeholders. Replace them with appropriate values before sending.

## 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

{}

## Body: 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 (required): 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 (required): 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 (required): 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"
```

## Response 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"
```

## Response 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.

## Response 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.

## Response 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.

## Response 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.

## Response 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.

## Response 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.

## Response 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

Every response with an HTTP status of 400 or higher has this shape, OpenRouter's error
format. Everything the gateway adds is inside `error.metadata`, so OpenRouter clients see
nothing unfamiliar. See "Errors" in the introduction for all error types.

{}

```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 (required): s238

### s238: object

What went wrong.

{}

```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 (required): s633

### s633: integer

The HTTP status of the response, as a number.

int32

{"minimum":"0"}

```json
400
```

- message (required): s634

### s634: string

What went wrong, in English. With several problems: the first one and how many more
follow; all of them are in `metadata.issues`. The text may change; match on
`metadata.type` instead.

{}

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

- metadata (optional): s635

### s635: object

Details for programs: error type, request ID, every problem, a suggested fix and, for
provider errors, which provider failed. Always present on gateway errors.

{}

```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

Providers that serve the model (when `provider.only` excluded all of them).

{}

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

### s7: string

{}

- docs_url (required): s640

### s640: string

Link to the section of this error type in the documentation.

{}

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

- failed_routing_step (optional): s641

### s641: string

The routing step that left no route (routing errors only).

{}

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

- issues (optional): s642

### s642: array

Every problem found in the request, so all can be fixed at once (at most 20); for
routing errors one entry per excluded route, for `no_provider_available` one per failed
attempt.

{}

### s123: object

One problem in the request, one reason a route was excluded, or one failed attempt.

{}

```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 (required): s636

### s636: string

Kind of problem, stable for programs.

"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 (required): s637

### s637: string

The problem in English, naming the field and, if short, the value sent.

{}

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

- path (required): s638

### s638: string

Where the problem is: JSONPath of the field in the request body, for example
`$.messages[2].content[0].image_url.url`, or `query.<name>` for a query parameter.

{}

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

- provider_error (optional): s643

### s643: oneOf

Safe provider diagnostics, identical for HTTP errors and terminal stream events.

{}

oneOf: s1158

### s1158: object

Provider diagnostics without provider-authored text. HTTP and terminal SSE errors use
this same structure; arbitrary upstream messages and metadata are discarded.

{}

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

- category (required): s1299

### s1299: string

Gateway classification from HTTP status and recognized dialect identifiers.

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

{}

```json
"rate_limited"
```

- code (optional): s1300

### s1300: string

Exact identifier from the configured dialect's fixed list; arbitrary values vanish.

{}

```json
"rate_limit_exceeded"
```

- provider_name (required): s1301

### s1301: string

Configured provider name, never a name supplied by the upstream body.

{}

```json
"deepinfra"
```

- retry_after (optional): s1302

### s1302: integer

Bounded seconds from the upstream Retry-After header, when present and numeric.

int64

{"minimum":"0"}

```json
2
```

- retryable (required): s1303

### s1303: boolean

Whether the classified failure can be transient. Unknown failures are not promised retryable.

{}

- status (optional): s1304

### s1304: integer

Actual HTTP status received from the upstream, including 200 for native errors.
Absent when no HTTP status is available.

int32

{"minimum":"0"}

```json
429
```

oneOf: s588

### s588: null

{}

- provider_name (optional): s644

### s644: string

The provider that failed, as in the response field `provider` (provider errors only).

{}

```json
"deepinfra"
```

- raw (optional): s645

### s645: string

Reserved OpenRouter compatibility field. The gateway never fills it: provider
free text is deliberately withheld. Use provider_error instead.

{}

```json
""
```

- remedy_hint (optional): s646

### s646: string

A concrete fix, for example the closest model ID to a mistyped one.

{}

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

- request_id (required): s647

### s647: string

ID of the request, the same as the `x-request-id` response header. Quote it when
contacting support.

{}

```json
"req_01k7tm9qz3f5c8x2v6b4n0m7hd"
```

- requested_providers (optional): s648

### s648: array

Providers named in `provider.only` (when it excluded all routes).

{}

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

- retry_after (optional): s649

### s649: integer

Seconds to wait before retrying; also sent as the `Retry-After` header (429 and 503).

int64

{"minimum":"0"}

```json
2
```

- retryable (required): s650

### s650: boolean

Whether sending the identical request again can succeed (for example after a timeout
or rate limit), as opposed to errors that need a changed request.

{}

- routing_funnel (optional): s651

### s651: array

How routing narrowed down the providers: each step with the number of routes left
(routing errors only, same format as OpenRouter).

{}

### s200: object

One routing step, as in OpenRouter's `routing_funnel`.

{}

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

- endpoint_count (required): s979

### s979: integer

Number of routes (providers of the model) left after the step.

{"minimum":"0"}

```json
2
```

- reason (optional): s980

### s980: string

The request field the step filtered on.

{}

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

- step (required): s981

### s981: string

Name of the step, as at OpenRouter.

{}

```json
"Initial Endpoints"
```

- type (required): s652

### s652: string

Stable error type to match on in code; see "Errors" in the introduction. Messages may
change, the type does not.

"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

Organization of the API key, if the key was recognized.

{}

```json
"org_01k7tm2c4e6g8j0k2m4p6r8t0v"
```

## Response 401: application/json

Missing, invalid or expired API key

## Response 402: application/json

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

## Response 403: application/json

Effective access policy forbids this model

## Response 404: application/json

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

## Response 408: application/json

Request upload or first audio bytes timed out

## Response 409: application/json

Conflicting, active or unavailable encrypted idempotency replay

## Response 413: application/json

Request body or retained structure exceeds the configured memory limit

## Response 429: application/json

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

## Response 500: application/json

Unexpected gateway error or durable recording unavailable

## Response 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.

## Response 502: application/json

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

## Response 503: application/json

No provider available, memory busy or shutdown in progress
