TokenLab

Audio & Realtime

Create Transcription

Transcribes audio into the input language

POST
/v1/audio/transcriptions

Use GET /v1/models?recommended_for=stt to get current transcription models.

Request Body

Transcription can return the transcript immediately or accept an asynchronous task with HTTP 200, id, and status. For an accepted task, poll GET /v1/tasks/{id} with the returned id. For longer synchronous audio, allow a client timeout of at least 120s.

filefilerequired

Audio file to transcribe. Supported formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm. Maximum file size: 25 MB.

modelstringrequired

Transcription model ID, for example whisper-large-v3 or qwen3-asr-flash. Find current choices with GET /v1/models?recommended_for=stt. There is no default model.

languagestring

Language of the audio in ISO-639-1 format (e.g., en, zh, ja).

promptstring

Optional text to guide the model's style or continue a previous segment, for models that list this parameter, such as qwen3-asr-flash.

response_formatstringdefault: json

Output format. Models differ: all accept json, and some also list text or verbose_json. Check the selected model's details before sending another value. text returns raw text instead of a JSON object.

temperaturenumber

Sampling temperature from 0 to 1, only for models that list this parameter.

timestamp_granularitiesarray

word and/or segment, only for models that list this parameter. Some models need response_format=verbose_json for timestamps. In multipart requests, repeat timestamp_granularities[] for multiple values.

Response

The fields below describe JSON transcript or translation responses. text, srt, and vtt return raw text or subtitles rather than a JSON object. Additional fields depend on the model and output format.

textstring

The transcribed text.

For verbose_json:

taskstring

Task name when returned, such as transcribe.

languagestring

Detected language.

durationnumber

Audio duration in seconds.

segmentsarray

Transcription segments with timestamps.

wordsarray

Word-level timestamps (if requested).

An accepted asynchronous transcription task returns the following fields instead of the transcript. Poll GET /v1/tasks/{id}; a completed task returns text and, when available, duration, segments, and words.

idstring

Task ID.

task_idstring

Async task identifier alias when provided.

statusstring

Task status: pending, processing, completed, or failed.

poll_urlstring

Status URL for this task. Poll GET /v1/tasks/{id} with id.

Request

curl -X POST "https://api.tokenlab.sh/v1/audio/transcriptions" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F file="@audio.mp3" \
  -F model="whisper-large-v3" \
  -F language="en"

Response

{
  "text": "Hello, this is a test of the transcription API."
}

Authorization

BearerAuth
AuthorizationBearer <token>

API Key authentication. Create or manage API keys in Dashboard > API > API Keys.

In: header

Headers

X-TokenLab-Delivery-Policy?string

Per-request Delivery policy. Overrides the API key and Workspace defaults. Auto tries TokenLab Verified first and may switch once to Official only before output, request acceptance, or persistent resource creation.

Value in

  • "auto"
  • "verified"
  • "official"

Request Body

multipart/form-data

Response

application/json

application/json

application/json

application/json

application/json

application/json