Guides

Asynchronous Jobs

The synchronous endpoint (/v1/audio/transcriptions) keeps the HTTP connection open until the transcription finishes. If you are processing many files, or don't want to risk network timeouts, you should use the asynchronous workflow.

Step 1 — Submit a job

The async endpoint only accepts pre-uploaded files. You must first upload your file using the Two-step Upload API to get a file_id.

Send a JSON request to POST /v1/transcriptions with your file_id.

curl -X POST https://api.quantclarity.com/v1/transcriptions \
-H "Authorization: Bearer qc_live_REPLACE_WITH_KEY" \
-H "Content-Type: application/json" \
-d '{
    "file_id": "file_12345678-1234-1234-1234-123456789abc",
    "model": "auto",
    "language": "ur"
}'

The API will immediately return a 202 Accepted with a transcription ID and its status.

{
"id": "tr_98765432-abcd-4ef0-9a1b-9876543210ab",
"status": "queued"
}

Step 2 — Poll for completion

Use the returned ID to check the status of your transcription. Send a request to GET /v1/transcriptions/{id}.

curl https://api.quantclarity.com/v1/transcriptions/tr_98765432-abcd-4ef0-9a1b-9876543210ab \
-H "Authorization: Bearer qc_live_REPLACE_WITH_KEY"

While the job is in the queue or being transcribed, the response will look like this:

{
"id": "tr_98765432-abcd-4ef0-9a1b-9876543210ab",
"status": "processing",
"text": null,
"language": null,
"segments": [],
"routing": {
    "model": "openai/whisper-large-v3",
    "provider": "openrouter",
    "reason": "table: ur → openai/whisper-large-v3"
},
"usage": null,
"error": null
}

We recommend polling every 3 to 5 seconds. Once the status changes to done, the text, segments, and usage fields will be populated with the final results.

Idempotency (Preventing double-charges)

Network issues happen. If you send a job but the connection drops before you get the response, you might be tempted to retry the exact same request. To prevent being charged twice, use an Idempotency Key.

Pass a unique string (like a UUID) in the Idempotency-Key header:

curl -X POST https://api.quantclarity.com/v1/transcriptions \
-H "Authorization: Bearer qc_live_REPLACE_WITH_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: my-unique-retry-key-123" \
-d '{"file_id": "...", "model": "auto"}'