Reference

API Reference

Authentication

All API requests require your API key to be sent in the Authorization header as a Bearer token.

code

Authorization: Bearer qc_live_your_api_key_here

Endpoints

POST `/v1/audio/transcriptions` (Sync)

Uploads an audio file and waits for the transcription to complete. Best for files under 4 MB.

Parameter	Type	Description
`file`	File (multipart)	The audio file bytes. (Required if no file_id)
`file_id`	String	A pre-uploaded file ID. (Required if no file)
`model`	String	Must be `auto`. (Required)
`language`	String	Optional ISO 639-1 language code hint (e.g., `ur`). See supported languages.

POST `/v1/transcriptions` (Async)

Submits a transcription job to the queue. Returns immediately with a tr_... ID.

Parameter	Type	Description
`file_id`	String (JSON)	A pre-uploaded file ID. (Required)
`model`	String (JSON)	Must be `auto`. (Required)
`language`	String (JSON)	Optional ISO 639-1 language code hint. See supported languages.
`Idempotency-Key`	Header	Optional unique key to safely retry network failures.

GET `/v1/transcriptions/{id}` (Poll)

Retrieves the status and result of an async transcription job.

POST `/v1/files` (Upload)

Requests a pre-signed URL to upload large files (up to 25 MB).

Parameter	Type	Description
`filename`	String (JSON)	Name of the file (e.g., `audio.mp3`). (Required)
`content_type`	String (JSON)	MIME type (e.g., `audio/mpeg`). (Required)
`size_bytes`	Integer (JSON)	Exact file size in bytes. (Required)

The Transcription Object

Whether you use the sync or async endpoint, a completed transcription looks like this:

Transcription Object

{
"id": "tr_12345678-...",
"status": "done",
"text": "The full transcript string.",
"language": {
    "code": "en",
    "source": "detected" // or "hint"
},
"segments": [
    { "start": 0.0, "end": 2.5, "text": "Segment text." }
],
"routing": {
    "model": "openai/whisper-large-v3",
    "provider": "openrouter",
    "reason": "table: en → openai/whisper-large-v3"
},
"usage": {
    "audio_seconds": 120,
    "credits": 2
},
"error": null
}

Errors

All errors return a standard JSON envelope with a specific error code and a retryable flag.

Error Envelope

{
"error": {
    "code": "insufficient_credits",
    "message": "Your account does not have enough transcription credits.",
    "retryable": false,
    "request_id": "req_abc123"
}
}

Code	HTTP	Description
`invalid_request`	400	Missing or malformed parameters.
`unauthorized`	401	Missing or invalid API key.
`insufficient_credits`	402	Account balance is too low.
`file_not_found`	404	The requested `file_id` or `tr_id` does not exist.
`file_too_large`	413	File exceeds the endpoint's limit.
`unsupported_media_type`	415	File format is not supported.
`rate_limit_exceeded`	429	Too many requests per minute.
`concurrency_limit`	429	Too many active transcriptions running at once.
`provider_error`	502	The AI provider failed to process the audio.
`timeout`	504	Transcription took too long and timed out.
`internal_error`	500/503	An unexpected platform error occurred.

API Reference

Authentication

Endpoints

POST /v1/audio/transcriptions (Sync)

POST /v1/transcriptions (Async)

GET /v1/transcriptions/{id} (Poll)