# Prerecorded

Transcribe a complete audio file.

```
POST https://api.reson8.dev/v1/speech-to-text/prerecorded
```

## Request

### Headers

| Header         | Value                                         |
|----------------|-----------------------------------------------|
| Authorization  | `ApiKey <api_key>` or `Bearer <access_token>` |
| Content-Type   | `application/octet-stream`                             |

### Query Parameters

| Parameter        | Type   | Default     | Description                                           |
|------------------|--------|-------------|-------------------------------------------------------|
| `encoding`              | string  | `auto`  | Audio encoding: `auto` for detected container formats, `m4a`, `m4v`, `mp4`, `mov`, `3gp`, or `3g2` for explicit seekable media containers, or `pcm_s16le` for raw PCM |
| `sample_rate`           | number  | `16000` | Sample rate in Hz (only used depending on encoding)        |
| `channels`              | number  | `1`     | Number of audio channels (only used depending on encoding) |
| `language`              | string  |         | Language to transcribe. Recommended for best quality. When omitted, the server auto-detects each utterance independently. See [Languages](../../documentation/speech-to-text/languages.md) for supported codes |
| `custom_model_id`       | string  |         | Optional. ID of a [custom model](../custom-model/create.md) to bias transcription. Overrides the model configured on the API client |
| `include_timestamps`    | boolean | `false` | Include `start_ms` and `duration_ms` on transcripts and words |
| `include_words`         | boolean | `false` | Include word-level detail on transcripts                   |
| `include_confidence`    | boolean | `false` | Include `confidence` on words                              |

### Example

=== "curl"

    ```bash
    curl -X POST "https://api.reson8.dev/v1/speech-to-text/prerecorded" \
      -H "Authorization: ApiKey <your_api_key>" \
      -H "Content-Type: application/octet-stream" \
      --data-binary @recording.wav
    ```

=== "Python"

    ```python
    import requests

    with open("recording.wav", "rb") as f:
        response = requests.post(
            "https://api.reson8.dev/v1/speech-to-text/prerecorded",
            headers={
                "Authorization": "ApiKey <your_api_key>",
                "Content-Type": "application/octet-stream",
            },
            data=f,
        )

    transcript = response.json()
    ```

## Response

`200 OK`

### Fields

| Field         | Type   | Included                         | Description                        |
|---------------|--------|----------------------------------|------------------------------------|
| `text`        | string | Always                           | Full transcript of the audio file  |
| `start_ms`    | number | When `include_timestamps=true`     | Start time in milliseconds         |
| `duration_ms` | number | When `include_timestamps=true`  | Duration in milliseconds           |
| `words`       | array  | When `include_words=true`        | Word-level detail                  |

Each word contains:

| Field         | Type   | Included                         | Description                |
|---------------|--------|----------------------------------|----------------------------|
| `text`        | string | Always                           | The recognized word        |
| `start_ms`    | number | When `include_timestamps=true`     | Start time in milliseconds |
| `duration_ms` | number | When `include_timestamps=true`  | Duration in milliseconds   |
| `confidence`  | number | When `include_confidence=true`   | Natural log-probability (≤ 0); apply `exp` for probability in `(0, 1]` |

### Example

=== "Default"

    ```json
    {
      "text": "the patient presented with chest pain and shortness of breath"
    }
    ```

=== "Everything Included"

    ```json
    {
      "text": "the patient presented with chest pain and shortness of breath",
      "start_ms": 0,
      "duration_ms": 4800,
      "words": [
        { "text": "the", "start_ms": 0, "duration_ms": 200, "confidence": -0.010 },
        { "text": "patient", "start_ms": 210, "duration_ms": 450, "confidence": -0.020 },
        { "text": "presented", "start_ms": 680, "duration_ms": 500, "confidence": -0.030 },
        { "text": "with", "start_ms": 1200, "duration_ms": 200, "confidence": -0.010 },
        { "text": "chest", "start_ms": 1420, "duration_ms": 350, "confidence": -0.041 },
        { "text": "pain", "start_ms": 1800, "duration_ms": 600, "confidence": -0.030 },
        { "text": "and", "start_ms": 2500, "duration_ms": 200, "confidence": -0.010 },
        { "text": "shortness", "start_ms": 2720, "duration_ms": 500, "confidence": -0.051 },
        { "text": "of", "start_ms": 3240, "duration_ms": 150, "confidence": -0.010 },
        { "text": "breath", "start_ms": 3410, "duration_ms": 1390, "confidence": -0.041 }
      ]
    }
    ```

## Errors

| Status | Code                     | Description                          |
|--------|--------------------------|--------------------------------------|
| 400    | `INVALID_REQUEST`        | Missing or invalid parameters        |
| 401    | `UNAUTHORIZED`           | Invalid or expired access token      |
| 413    | `PAYLOAD_TOO_LARGE`      | Audio file exceeds maximum size      |
| 500    | `INTERNAL_ERROR`         | Unexpected server error              |