Transcribe audio
Turns speech into text. Send the audio as JSON with base64 in input_audio (OpenRouter's form) or as a multipart/form-data upload with a file part (OpenAI's form, as OpenAI's SDKs send it). Same response as OpenRouter: text and usage with the cost in EUR, plus language, duration and segments with response_format: verbose_json.
The gateway picks a European provider of the model (respecting provider preferences) and, if it fails, tries the next one. Whether the provider receives the audio as an upload or as base64 JSON is part of its configuration, not of the request. The body is validated completely before any provider is called; every problem is listed in error.metadata.issues. Audio by URL (input_audio.url, source_url), speaker labels (diarize) and keyterms are not supported by this gateway's providers and fail with 400.
Administrative PII requirements are checked for each actual route, including fallbacks and retries. This endpoint cannot redact its input: a matching requirement returns invalid_parameter with a not_available issue at $.model before provider I/O.
POST https://api.tokenlane.de/v1/audio/transcriptions
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": [] } ] ]
curl
curl --request POST \
--url 'https://api.tokenlane.de/v1/audio/transcriptions' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"input_audio": {
"data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=",
"format": "wav"
},
"language": "de",
"model": "mistralai/voxtral-mini-transcribe-3-0"
}'
node
const response = await fetch("https://api.tokenlane.de/v1/audio/transcriptions", {
method: "POST",
headers: {
"Authorization": "Bearer " + process.env.TOKENLANE_API_KEY,
"Content-Type": "application/json",
},
body: `{
"input_audio": {
"data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=",
"format": "wav"
},
"language": "de",
"model": "mistralai/voxtral-mini-transcribe-3-0"
}`,
});
console.log(await response.text());
python
import os
import urllib.request
body = (r'''{
"input_audio": {
"data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=",
"format": "wav"
},
"language": "de",
"model": "mistralai/voxtral-mini-transcribe-3-0"
}''').encode("utf-8")
request = urllib.request.Request(
"https://api.tokenlane.de/v1/audio/transcriptions",
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/transcriptions", {
method: "POST",
headers: {
"Authorization": "Bearer " + process.env.TOKENLANE_API_KEY,
"Content-Type": "application/json",
},
body: `{
"input_audio": {
"data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=",
"format": "wav"
},
"language": "de",
"model": "mistralai/voxtral-mini-transcribe-3-0"
}`,
});
console.log(await response.text());
header: x-session-id (optional)
Groups the generation into a session, immediately available from GET /v1/sessions/{id}. Use 1 to 256 ASCII letters, digits, '-', '_', '.' or ':'; an ID cannot consist only of dots. A non-null session_id in JSON or multipart takes precedence. Never sent to the provider.
s0: string | null
{}
header: Idempotency-Key (optional)
Explicit opt-in to encrypted response replay across gateway nodes. One 1..=255 printable ASCII value per logical operation, scoped to this API key ID. Reuse the same method, path and normalized body. Completed responses are retained for at most 10 minutes; replay is free and creates no generation. Conflicting content or unavailable replay returns 409. A successful replay carries Idempotent-Replayed: true and preserves the original request and generation IDs. See /docs/guides/idempotency.
Body: application/json
{
"input_audio": {
"data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=",
"format": "wav"
},
"language": "de",
"model": "mistralai/voxtral-mini-transcribe-3-0"
}
s4: object
Audio to transcribe as JSON, in OpenRouter's format: the audio is base64 in input_audio.
The body is validated before any provider is called; every problem is listed in error.metadata.issues. The audio may have at most 50 MiB decoded, within the 50 MiB body (as base64 about 37 MiB of audio fit; upload larger files as multipart/form-data). Unknown parameters are ignored and named in x-ignored-params.
{}
{
"input_audio": {
"data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=",
"format": "wav"
},
"language": "de",
"model": "openai/whisper-large-v3"
}
- diarize (optional): s240
s240: boolean
Speaker labels. Not supported by the providers of this gateway: true fails with 400 invalid_parameter.
{}
false
- input_audio (required): s241
s241: anyOf
The audio as {"data": <base64>, "format": <format>}. Formats: aac, flac, m4a, mp3, mp4, mpeg, mpga, oga, ogg, opus, wav, webm. {"url": …} (the provider downloads the audio) is not supported by the providers of this gateway and fails with 400 invalid_parameter.
{}
anyOf: s201
s201: object
Audio as base64.
{"additionalProperties":"false"}
{
"data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=",
"format": "wav"
}
- data (required): s982
s982: string
The audio file, base64-encoded (standard or URL-safe alphabet, no data URL prefix).
{}
- format (required): s983
s983: string
Format of the audio: aac, flac, m4a, mp3, mp4, mpeg, mpga, oga, ogg, opus, wav or webm (any case).
{"pattern":"\"^[a-zA-Z0-9][a-zA-Z0-9+._-]{0,15}$\""}
"wav"
anyOf: s202
s202: object
Audio the provider downloads. Not supported by the providers of this gateway.
{"additionalProperties":"false"}
{
"format": "mp3",
"url": "https://example.com/meeting.mp3"
}
- format (optional): s984
s984: string
Format of the audio at the URL.
{"pattern":"\"^[a-zA-Z0-9][a-zA-Z0-9+._-]{0,15}$\""}
"mp3"
- url (required): s985
s985: string
URL of the audio file; fails with 400 invalid_parameter.
uri
{"maxLength":"8000"}
- keyterms (optional): s242
s242: array
Terms to bias recognition toward. Not supported by the providers of this gateway: a non-empty list fails with 400 invalid_parameter; put such terms into prompt.
{}
s7: string
{}
- language (optional): s243
s243: string
Language of the audio as an ISO-639-1 code, for example de; detected if missing.
{}
"de"
- metadata (optional): s244
s244: any
Local metadata: at most 16 string pairs, keys 1..64 and values 0..512 characters.
{}
- model (required): s245
s245: string
Transcription model, with the same ID as on OpenRouter, or an alias of the gateway. Models without audio transcription fail with 404 no_endpoint; an unknown ID with 400 model_not_found and a suggestion in remedy_hint.
{}
"openai/whisper-large-v3"
- prompt (optional): s246
s246: string
Text that guides the transcription, for example spellings of names or the previous part of a longer recording. Passed to the provider as sent.
{}
"Prozesshub, dpa"
- provider (optional): s247
s247: object
Routing preferences, as for chat completions: only, ignore, order, allow_fallbacks, sort and max_price. Never sent to the provider.
{}
- response_format (optional): s248
s248: string
json (default) returns text and usage; verbose_json adds language, duration and timestamped segments.
"json", "verbose_json"
{}
"json"
- session_id (optional): s249
s249: string | null
Groups related requests in generation records and GET /v1/sessions/{id}. Use 1 to 256 ASCII letters, digits, -, _, . or :; not only dots. A non-null body value takes precedence over x-session-id. Never sent to the provider.
{"minLength":"1","maxLength":"256"}
"session-1234"
- temperature (optional): s250
s250: number
Sampling temperature from 0 to 1.
double
{}
0
- timestamp_granularities (optional): s251
s251: array
Timestamp detail with verbose_json: segment, and word for a words array.
{}
s215: string
A timestamp detail level of verbose_json.
"word", "segment"
{}
"segment"
- trace (optional): s252
s252: object
Trace metadata for observability; never sent to the provider.
{}
- user (optional): s253
s253: string
An identifier of the end user; retained locally and only a tenant-scoped hash may reach a route explicitly supporting user.
{"maxLength":"256"}
"user-1234"
Body: multipart/form-data
{
"file": "meeting.mp3",
"language": "de",
"model": "openai/whisper-large-v3"
}
s5: object
Audio to transcribe as a file upload, as OpenAI's SDKs send it.
{}
{
"file": "meeting.mp3",
"language": "de",
"model": "openai/whisper-large-v3"
}
- diarize (optional): s254
s254: boolean
Speaker labels; true fails with 400 (not supported by the providers of this gateway).
{}
- file (optional): s255
s255: string
The audio file, at most 50 MiB; required (source_url is not supported). Its format comes from the file name's extension or the part's content type: aac, flac, m4a, mp3, mp4, mpeg, mpga, oga, ogg, opus, wav or webm.
binary
{}
- keyterms[] (optional): s256
s256: array
Terms to bias recognition toward, one part per term; not supported by the providers of this gateway (400).
{}
- language (optional): s257
s257: string
Language of the audio as an ISO-639-1 code; detected if missing.
{}
- metadata (optional): s258
s258: string | null
Local metadata as a JSON object with at most 16 string pairs, keys 1..64 and values 0..512 characters; never sent to the provider.
{}
"{\"workflow\":\"support\"}"
- model (required): s259
s259: string
Transcription model, as in the JSON form.
{}
"openai/whisper-large-v3"
- prompt (optional): s260
s260: string
Text that guides the transcription.
{}
- provider (optional): s261
s261: string
Routing preferences as a JSON-encoded object.
{}
- response_format (optional): s262
s262: string
json (default) or verbose_json.
"json", "verbose_json"
{}
"json"
- session_id (optional): s263
s263: string
Groups related requests in generation records and GET /v1/sessions/{id}. Use 1 to 256 ASCII letters, digits, -, _, . or :; not only dots. This form field takes precedence over x-session-id. Never sent to the provider.
{"minLength":"1","maxLength":"256"}
- source_url (optional): s264
s264: string
URL of the audio for the provider to download; not supported by the providers of this gateway (400). Upload the file instead.
uri
{}
- temperature (optional): s265
s265: number
Sampling temperature from 0 to 1.
{}
- timestamp_granularities[] (optional): s266
s266: array
Timestamp detail with verbose_json, one part per value.
{}
A timestamp detail level of verbose_json.
- trace (optional): s267
s267: string
Trace metadata as a JSON-encoded object; never sent to the provider.
{}
- user (optional): s268
s268: string
An identifier of the end user; retained locally and only a tenant-scoped hash may reach a route explicitly supporting user.
{"maxLength":"256"}
Response 200: application/json
The transcript, with what the provider counted and the cost in EUR in usage.
{
"text": "Guten Tag, hier ist die Zusammenfassung der Sitzung.",
"usage": {
"cost": 0.001,
"currency": "EUR",
"is_byok": false,
"seconds": 9.2
}
}
s6: object
The transcript, in OpenRouter's format, with the cost in EUR.
{}
{
"text": "Guten Tag, hier ist die Zusammenfassung der Sitzung.",
"usage": {
"cost": 0.001,
"currency": "EUR",
"is_byok": false,
"seconds": 9.2
}
}
- text (required): s269
s269: string
The transcribed text.
{}
"Guten Tag, hier ist die Zusammenfassung der Sitzung."
- usage (optional): s270
s270: object
What the provider counted and the cost in EUR, if it reported anything the model's prices apply to; otherwise cost is missing rather than zero.
{}
{
"cost": 0.001,
"currency": "EUR",
"is_byok": false,
"seconds": 9.2
}
- cost (optional): s1003
s1003: number
Cost of the request in EUR: tokens at the model's token prices, audio at its price per second (started seconds count fully).
double
{}
0.001
- input_tokens (optional): s1004
s1004: integer
Input tokens, if the provider counts tokens.
int64
{"minimum":"0"}
83
- output_tokens (optional): s1005
s1005: integer
Output tokens, if the provider counts tokens.
int64
{"minimum":"0"}
30
- seconds (optional): s1006
s1006: number
Duration of the audio in seconds, if the provider reports it.
double
{}
9.2
- total_tokens (optional): s1007
s1007: integer
Input plus output tokens.
int64
{"minimum":"0"}
113
- * (optional): s1008
s1008: any
Public fields: currency (always EUR), is_byok and exact cost_details. Unknown provider usage fields are removed.
{}
- * (optional): s271
s271: any
Public OpenRouter transcription fields, for example language, duration, segments and words with verbose_json. An optional id extension is omitted if it is not a nonempty string of at most 128 bytes or contains the credential used for that provider, including encoded forms.
{}
Response 400: application/json
Recognized upstream 400/422 request rejections return non-retryable client errors with safe public field paths. Invalid request: broken JSON or a malformed form (invalid_request), invalid fields such as missing or non-base64 audio, an audio format outside the supported list or unsupported options, with every problem in issues (invalid_parameter), or an unknown model ID with a suggestion in remedy_hint (model_not_found)
{
"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"
]
- 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 (authentication)
Response 402: application/json
The API key spending limit, the workspace budget (workspace_budget_exceeded) or the organization prepaid balance cannot cover the estimated request reservation, including fees, media and concurrent reservations (insufficient_credits for key and organization). No paid upstream call starts without a reservation.
Response 403: application/json
The organization, workspace or key policy does not allow the model (permission_denied); remedy_hint names the models it may use
Response 404: application/json
The model exists, but none of its providers fits the request: it does not transcribe audio, or provider filters or max_price exclude every provider. issues names the reason per provider (no_endpoint)
Response 408: application/json
The provider did not connect or did not finish its response within the time limit, or the request body stopped arriving (timeout)
Response 409: application/json
idempotency_conflict: this key has different request content; use a new key. idempotency_in_progress: the original is running; respect Retry-After. idempotency_unavailable: no safe replay is possible; do not silently recompute. See remedy_hint.
Response 413: application/json
The request body or the decoded audio is larger than 50 MiB (payload_too_large)
Response 429: application/json
Customer quota or upstream rate limit exhausted (rate_limited)
Response 500: application/json
Unexpected gateway error (internal)
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
The only provider tried failed (provider_error, with provider_name and structured provider_error diagnostics; provider text is withheld) or sent a response without text, larger than 32 MiB or too complex to parse (provider_invalid_response)
Response 503: application/json
Every provider failed, the gateway is busy with other large request bodies, or this gateway instance is shutting down (no_provider_available)