POST /v1/transcriptions accepts a recording by URL and returns a job immediately; GET /v1/jobs/{id} carries its state, then the transcript. One request shape, one transcript shape, three providers. Reference: create a transcription, get a job.
1
Submit the recording
2
Poll the job
status moves from queued to running to completed or failed. attempt_status shows where the provider attempt is, which is useful when a job sits in running longer than expected.3
Read the transcript
What “durable” means
Helve writes the attempt to its database before it talks to the provider, so a crash on either side never loses a job. Rate limits are retried. A submission whose outcome is uncertain is reconciled rather than sent twice, so you are never charged for a duplicate. A job that cannot finish fails cleanly at its deadline with a reason inerror, instead of hanging. Jobs and their transcripts are kept for seven days.
Options across providers
An option the selected model cannot honour produces a warning on the created job, or rejects the request when
strict is true.
Transcript shape
text is the provider’s complete transcript with punctuation, never reconstructed from words. duration_seconds is the recording length the provider reported, and the amount you are billed on. Speakers are normalized to speaker_0, speaker_1, … in order of first appearance, and are local to one transcript. confidence is the provider’s own 0 to 1 figure and is not comparable across providers.