# Transcribe audio

- **Method:** `POST`
- **Path:** `/api/v1/transcription/start`
- **Operation ID:** `start_transcription_api_v1_transcription_start_post`
- **Tags:** Transcription

Start a speech-to-text transcription.

In **async** mode (default), returns immediately with `{started: true}`.
Poll `/api/v1/transcription/progress` for status and results.

In **sync** mode (`sync=true`), blocks until transcription completes and
returns the result directly. When `output_format=srt` and
`return_timestamps=true`, returns an SRT subtitle file instead of JSON.

## Effective servers

- `http://127.0.0.1:8100`

  Voice Creator Pro on this computer

## Query parameters

- **`sync`**: `boolean`, default: `false`

  Wait for transcription to complete and return the result directly
- **`output_format`**: `string`, possible values: `"json", "srt"`, default: `"json"`

  Response format when sync=true. 'srt' returns SubRip subtitles (requires return\_timestamps=true)

## Request body

**Required:** `true`

**Content type:** `application/json`

schema: `TranscribeRequest`

- **`audio_base64` (required)**: `string`

  Base64-encoded audio (WAV)
- **`asr_family`**: `string | null`

  ASR model family (e.g. 'Qwen3-ASR', 'Parakeet v3', 'Orukeet'). Used for routing; mostly informational on Modal-direct path.
- **`asr_quality`**: `string | null`

  ASR variant id within the family (e.g. 'standard', 'higher\_quality', 'parakeet\_v3', 'orukeet'). Subprocess loads this variant on demand if it differs from the currently-loaded one.
- **`diarization_engine`**

  Speaker detection engine. The saved preference is used if null.

  **Any of:**
  - `string`, possible values: `"pyannote", "nemotron"`
  - `null`
- **`language`**: `string | null`

  Force language (auto-detect if null)
- **`num_speakers`**

  Pin the exact diarization speaker count. Auto-detect (with trivial-cluster merging) if null.

  **Any of:**
  - `integer`, minimum: `1`, maximum: `10`
  - `null`
- **`reference_text`**: `string | null`

  Original text for punctuation restoration (e.g. from history)
- **`return_timestamps`**: `boolean`, default: `false`

  Return word-level timestamps via forced aligner

**Example:**

```json
{
  "audio_base64": "UklGRi4AAABXQVZFZm10IBAAAA...",
  "language": "en",
  "return_timestamps": true,
  "reference_text": "Hello world, this is a test.",
  "asr_family": "Qwen3-ASR",
  "asr_quality": "higher_quality",
  "num_speakers": 2,
  "diarization_engine": "nemotron"
}
```

## Responses

### 200 Transcription started (async) or completed (sync).

**Content type:** `application/json`

**Any of:**

- `object`, schema: `TranscriptionStartedResponse`
  - **`started` (required)**: `boolean`

    Whether the transcription was started
  - **`reason`**: `string | null`

    Reason if transcription could not start
- `object`, schema: `TranscriptionSyncResult`
  - **`success` (required)**: `boolean`

    Whether transcription completed successfully
  - **`cancelled`**: `boolean | null`

    True if the transcription was cancelled
  - **`error`**: `string | null`

    Error message if transcription failed
  - **`language`**: `string | null`

    Detected language of the audio
  - **`text`**: `string | null`

    Transcribed text
  - **`timestamps`**: `array | null`

    Word-level timestamps if requested

    **Items:**

    schema: `TimestampItem`
    - **`end_time` (required)**: `number`

      End time in seconds
    - **`start_time` (required)**: `number`

      Start time in seconds
    - **`text` (required)**: `string`

      Word or token text
    - **`speaker`**: `string | null`

      Speaker label when speaker detection ran

**One of:**

- *Schema `TranscriptionStartedResponse` is shown above.*
- *Schema `TranscriptionSyncResult` is shown above.*

**Example:**

```json
{
  "started": true,
  "reason": ""
}
```

**Content type:** `text/srt`

`string`

**Example:**

```json
"1\n00:00:00,000 --> 00:00:02,500\nHello world\n"
```

### 422 Validation Error

**Content type:** `application/json`

schema: `HTTPValidationError`

- **`detail`**: `array`

  **Items:**

  schema: `ValidationError`
  - **`loc` (required)**: `array of (string | integer)`
  - **`msg` (required)**: `string`
  - **`type` (required)**: `string`
  - **`ctx`**: `object`
  - **`input`**: `any`

**Example:**

```json
{
  "detail": [
    {
      "loc": [
        ""
      ],
      "msg": "",
      "type": "",
      "input": null,
      "ctx": {}
    }
  ]
}
```

### 504 Sync transcription stalled — no progress for 300s.

## Schemas

- `HTTPValidationError` — shown above.
- `TimestampItem` — shown above.
- `TranscribeRequest` — shown above.
- `TranscriptionStartedResponse` — shown above.
- `TranscriptionSyncResult` — shown above.
- `ValidationError` — shown above.