Batch REST API
Submit a recording to the batch REST API, poll the job to a terminal status, and retry without creating duplicate jobs.
Batch is the direct HTTP route for long, complete recordings
(choose a workflow): upload once, get a jobId, and poll until
the job finishes. Send x-api-key from your backend; REST calls don't need an Origin
header (Authentication). Size and duration limits are in
Limits.
Submit a job
Upload one audio file in the file field of a multipart/form-data body. This request
transcribes Arabic–English code-switched speech with speaker diarization:
curl -sS -X POST "$API_URL/v1/transcribe/codeswitch?diarization=1" \
-H "x-api-key: $API_KEY" \
-F "[email protected]"A 200 means the job is queued, not finished (trimmed):
{ "jobId": "e5e90424-de35-4976-8951-04edae59fae8", "status": "queued" }Store jobId with your own work item before you do anything else; it's the only handle to the job.
| Selector | Where | Values | Default |
|---|---|---|---|
lang | Path | en, ar, codeswitch, auto | Required |
asr | Query | An ASR model key | The language's configured model |
diarization | Query | 0, 1, d1, d2, d3 | Off; 1 selects the default level |
itn | Query | 0, 1 | Off |
redact | Query | 0, 1 | Off |
true and false work wherever 1 and 0 do. For model keys and the differences between
diarization levels, see Models. An unknown asr key returns 400 ASR_MODEL_NOT_FOUND.
Poll for the result
Set JOB_ID to the returned jobId and read the job with the V2 route:
curl -sS -X GET "$API_URL/v1/transcribe/$JOB_ID?save_result=true" \
-H "x-api-key: $API_KEY"Response (trimmed):
{
"message": "success",
"data": {
"id": "e5e90424-de35-4976-8951-04edae59fae8",
"language": "codeswitch",
"audio_duration": 72.6085,
"status": "done",
"final_result": "Yeah, I mean, look, to start with, as you know, building infrastructure…",
"final_word_segments": [{ "start_time": 0.08, "end_time": 0.36, "word": "Yeah," }],
"diarization_segments": [{ "start_time": 0, "end_time": 14.56, "speaker": "SPEAKER_1" }]
}
}Keep polling while data.status is queued or processing. Stop on done, failed, or
cleared (job statuses). Poll every 2 s, with a timeout on each
request and an overall deadline.
Every job status returns HTTP 200. Retry a 5xx read (safe with save_result=true) and stop on
404 TRANSCRIPTION_JOB_NOT_FOUND. Other codes:
Error codes.
| Route | Use | Transcript | Word timings | Speakers |
|---|---|---|---|---|
GET /v1/transcribe/{job_id} (V2) | New direct integrations | data.final_result | data.final_word_segments (no speaker) | data.diarization_segments |
GET /v1/transcribe/{job_id}/{lang} (V1) | Legacy; used by the SDKs | results.transcript | results.offsets (word, startTime, endTime, speaker) | diarization_segments |
The two shapes use the same statuses but different field names and casing, so model each one
with its own type. The V1 {lang} segment is required but ignored. Read result fields only when
the status is done; final_result and final_word_segments already include ITN and redaction
when you enable them. A failed response doesn't include a reason. A failed job is final;
submitting the file again creates a new job.
Read the result again
Both result routes accept save_result, which defaults to false. With the default, a read that
returns done or failed can clear the stored result, and later reads return cleared. Save the
result in your own storage once you read done.
Pass save_result=true on every poll if you may need to read the result more than once, for
example after a network error or from a second worker.
Force-aligned diarization
If you need a speaker on every word, poll the V1 route; it applies the rule below server-side and
puts a speaker on each word in results.offsets. On V2, assign each word to the segment
containing its start_time; otherwise use the nearest-boundary rule below.
The V1 query parameter diarization_force_align sets the label for a word whose startTime is
outside every speaker segment:
diarization_force_align | Speaker for that word |
|---|---|
true (default) | The speaker of the nearest segment boundary, measured from the word's midpoint; ties go to the earlier segment |
false | UNKNOWN_SPEAKER |
If the result has no speaker segments, speaker is null either way. The parameter changes only
word labels; diarization_segments stays the same. The SDKs read the V1 route with the default,
so SDK word offsets already carry speakers. Treat labels such as SPEAKER_1 as opaque strings
that distinguish speakers within one result. They don't identify anyone.
Retries and duplicates
Submission has no idempotency key, and there's no endpoint to list or look up jobs. If you never
saw the jobId, you can't recover it, so after an ambiguous upload you choose between accepting a
possible duplicate job and not resubmitting.
| Submission outcome | Job created? | What to do |
|---|---|---|
400, 401, 402, 403, 413, 422 | No | Fix the request or account, then submit. |
429, 503 | No | Back off and resubmit (retrying safely). |
500, gateway 502 or 504, timeout, dropped connection | Maybe | Don't resubmit automatically. |
Record every jobId you receive, and record any submission whose outcome you didn't see. Result
reads are safe to retry when every poll uses save_result=true.
Capacity responses
When your batch audio capacity is used up, submission returns 429 RATE_LIMIT_EXCEEDED with the
remaining capacity in audio seconds (trimmed):
{ "code": "RATE_LIMIT_EXCEEDED", "retryable": true, "data": { "capacity": 120.5 } }data.capacity isn't a wait time. A value of 0 can mean no balance was available. Use it to
decide whether a recording fits, and queue larger work for later. A gateway rate limit can return
429 without this body; treat a missing data.capacity as plain backoff. 402 CREDITS_EXHAUSTED is
different: the account is out of credit, and retrying won't help. For backoff rules, see
Retrying safely.
Next steps
Live audio over the API
Choose Socket.IO or HTTP streaming to send live audio to HUMAIN Voice for realtime transcription or live diarization.
HTTP streaming API
Call the HUMAIN Voice HTTP streaming routes directly to transcribe a clip, stream live audio for transcription or speaker diarization, and capture text-to-speech frames.