Skip to main content
POST
Transcriptions — Submit Job
Step 2. Starts speech-to-text over an uploaded recording, with an optional translation into target_language. Returns 202 Accepted as soon as the job has been submitted for processing; completion is observed by polling GET /v2/transcriptions/{job_id} (the Location header points there, Retry-After suggests the cadence).

Language behavior

  • Omit target_language for transcription only. Every spoken language is preserved and translated_text is null.
  • target_language is a 2–3 letter ISO 639 code (en, zh, ko, …), case-insensitive. Other formats, such as en-US, are rejected with 400. Every segment is sent for translation regardless of the language the speech-to-text step labelled it with; the translator is instructed to return text already in the target language unchanged and to translate the other-language parts of a segment that mixes languages, so mixed-language calls are supported. The language label on a segment is the speech-to-text provider’s per-chunk detection and can differ from the words inside it. A line the translator did not answer is reported with translated_text: null and TRANSLATION_FAILED, never as original text presented as a translation.
  • Translation quality is best effort. Detected translation failures are reported with TRANSLATION_FAILED, and the original transcript is retained.

Idempotency

Send an Idempotency-Key header with a value unique to the submission. A retry with the same key, upload_id and target_language returns the existing job and does not start a second workflow. Reusing a key with a different upload_id or target_language starts a new job. Each call still counts against your organization’s transcription limit, retries included. If the submission returns 503 (TRANSCRIPTION_SUBMIT_UNAVAILABLE), the job may or may not have started. Wait Retry-After seconds and submit again with the same Idempotency-Key; without a key, a retry can process the same recording twice.
Submitting an upload_id whose file was never PUT, or that belongs to another organization, returns 404, as does a new submission for an upload whose audio was deleted (90 days after upload); an empty file or one larger than 2 GB returns 400. A new submission returns status queued; a retry with the same Idempotency-Key returns the job’s current status. Neither confirms successful processing.

Authorizations

X-API-KEY
string
header
required

Headers

Idempotency-Key
string

Unique per submission; a retry with the same key returns the existing job.

Body

application/json
upload_id
string<uuid>
required
target_language
string

Language to translate into, as a 2–3 letter ISO 639 code such as en, zh or ko (case-insensitive). Other formats, such as en-US, are rejected with 400. Omit for transcription only.

Pattern: ^[A-Za-z]{2,3}$
Example:

"en"

Response

Accepted. Location: /v2/transcriptions/{job_id}; Retry-After: 60.

error
object | null
required
payload
object
required