> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helve.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Transcription

> Durable speech-to-text jobs across AssemblyAI, Deepgram, and ElevenLabs.

Transcription is asynchronous. `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](/api-reference/create-transcription), [get a job](/api-reference/get-job).

<Steps>
  <Step title="Submit the recording">
    ```bash theme={null}
    curl -s https://helve.dev/v1/transcriptions \
      -H "Authorization: Bearer $HELVE_API_KEY" \
      -H "content-type: application/json" \
      -d '{
        "audio_url": "https://example.com/recordings/standup.mp3",
        "provider": "auto",
        "diarize": true,
        "keyterms": ["Helve", "Stirrup"]
      }'
    ```

    ```json theme={null}
    { "id": "job_7d0c…", "tool": "transcription", "status": "queued", "provider": "assemblyai", "model": "universal-2", "warnings": [], "created_at": "2026-09-16T10:12:03.221Z" }
    ```

    The URL must be HTTPS and reachable by the provider until it has fetched the file. Signed URLs work.
  </Step>

  <Step title="Poll the job">
    ```bash theme={null}
    curl -s https://helve.dev/v1/jobs/job_7d0c… -H "Authorization: Bearer $HELVE_API_KEY"
    ```

    Poll every few seconds. `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.
  </Step>

  <Step title="Read the transcript">
    ```json theme={null}
    {
      "id": "job_7d0c…",
      "status": "completed",
      "provider": "assemblyai",
      "model": "universal-2",
      "attempt_status": "completed",
      "finished_at": "2026-09-16T10:13:41.008Z",
      "result": {
        "text": "Morning everyone. Let's start with the eval results…",
        "language": "en",
        "duration_seconds": 612.4,
        "words": [{ "text": "Morning", "start": 0.32, "end": 0.71, "speaker_id": "speaker_0", "confidence": 0.98 }],
        "provider": "assemblyai",
        "model": "universal-2",
        "usage": { "cost_usd": 0.0289, "credits": 0 }
      },
      "error": null
    }
    ```
  </Step>
</Steps>

## 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 in `error`, instead of hanging. Jobs and their transcripts are kept for seven days.

## Options across providers

| Option          | AssemblyAI                          | Deepgram                          | ElevenLabs                             |
| --------------- | ----------------------------------- | --------------------------------- | -------------------------------------- |
| `language`      | Native, or detection when omitted   | Native, or detection              | Native, or detection                   |
| `diarize`       | Native, +\$0.02 per hour            | Native, included                  | Native                                 |
| `keyterms`      | Native                              | Nova-3 only, +\$0.08 per hour     | Scribe v2 only                         |
| `timestamps`    | Native word timings                 | Native word timings               | Native word timings                    |
| Model selection | `provider_options.assemblyai.model` | `provider_options.deepgram.model` | `provider_options.elevenlabs.model_id` |

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.