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 --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
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
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
// 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
{
"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.
{}
{
"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.
{}
"Speak calmly."
- model (required): s233
s233: string
Public speech model ID or alias.
{}
"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\""}
"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"}
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"}
"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
{}
"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
{
"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.
{}
{
"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.
{}
{
"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"}
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.
{}
"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.
{}
{
"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).
{}
[
"deepinfra",
"open-inference"
]
s7: string
{}
- docs_url (required): s640
s640: string
Link to the section of this error type in the documentation.
{}
"/docs#description/model-not-found"
- failed_routing_step (optional): s641
s641: string
The routing step that left no route (routing errors only).
{}
"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.
{}
{
"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"
{}
"out_of_range"
- message (required): s637
s637: string
The problem in English, naming the field and, if short, the value sent.
{}
"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.
{}
"$.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.
{}
{
"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"
{}
"rate_limited"
- code (optional): s1300
s1300: string
Exact identifier from the configured dialect's fixed list; arbitrary values vanish.
{}
"rate_limit_exceeded"
- provider_name (required): s1301
s1301: string
Configured provider name, never a name supplied by the upstream body.
{}
"deepinfra"
- retry_after (optional): s1302
s1302: integer
Bounded seconds from the upstream Retry-After header, when present and numeric.
int64
{"minimum":"0"}
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"}
429
oneOf: s588
s588: null
{}
- provider_name (optional): s644
s644: string
The provider that failed, as in the response field provider (provider errors only).
{}
"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.
{}
""
- remedy_hint (optional): s646
s646: string
A concrete fix, for example the closest model ID to a mistyped one.
{}
"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.
{}
"req_01k7tm9qz3f5c8x2v6b4n0m7hd"
- requested_providers (optional): s648
s648: array
Providers named in provider.only (when it excluded all routes).
{}
[
"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"}
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.
{}
{
"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"}
2
- reason (optional): s980
s980: string
The request field the step filtered on.
{}
"provider.only"
- step (required): s981
s981: string
Name of the step, as at OpenRouter.
{}
"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"
{}
"invalid_parameter"
- user_id (optional): s239
s239: string | null
Organization of the API key, if the key was recognized.
{}
"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