Skip to main content
POST
Transcribe a recording

Authorizations

Authorization
string
header
required

An API key from the dashboard, sk_live_…, sent as Authorization: Bearer sk_live_….

Body

application/json
audio_url
string<uri>
required

HTTPS URL of the recording, fetched by the provider. Signed URLs are fine; it must stay reachable until the provider has read it. No embedded credentials or fragments.

provider
enum<string>

Which speech-to-text provider runs the job. auto (default) picks the first configured provider. The choice is persisted on the job before execution.

Available options:
assemblyai,
deepgram,
elevenlabs,
auto
language
string

BCP-47-style language tag such as en or en-US. Omit to let the provider detect the language.

Pattern: ^[a-zA-Z]{2,3}(?:-[a-zA-Z0-9]{2,8})*$
diarize
boolean

Label speakers in words as speaker_0, speaker_1, … in order of first appearance. Default false.

keyterms
string[]

Recognition hints: names, jargon, product terms. Supported on AssemblyAI, Deepgram Nova-3, and ElevenLabs Scribe v2; other models ignore them with a warning.

Minimum array length: 1
timestamps
enum<string>

word (default) returns per-word timings in result.words; none omits them.

Available options:
word,
none
strict
boolean

When true, any option the selected provider or model cannot honour rejects the request instead of producing a warning. Default false.

provider_options
object

Provider-native options, validated by the adapter. Model selection lives here. Transport settings such as URLs, callbacks, and authentication cannot be overridden.

Response

Transcription accepted

id
string
required

The job id, job_…. Poll GET /v1/jobs/{id} with it.

Pattern: ^job_[0-9a-f-]{36}$
tool
enum<string>
required
Available options:
transcription
status
enum<string>
required

queued and running are in progress; completed carries result; failed carries error.

Available options:
queued,
running,
completed,
failed
provider
enum<string>
required

The provider selected for this job, resolved from auto.

Available options:
assemblyai,
deepgram,
elevenlabs
model
string
required

The provider model the job will run on.

warnings
object[]
required

Options the selected provider or model cannot honour. Empty when the request was accepted exactly.

created_at
string<date-time>
required