> For the complete documentation index, see [llms.txt](https://dataqueue.gitbook.io/voicehub-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dataqueue.gitbook.io/voicehub-docs/api-reference/stt-v1/stt-transcribe-api-v1.md).

# STT Transcribe API V1

### POST /stt-transcribe/public/transcribe

Transcribes an uploaded audio file using the STT provider configured for the workspace.

**Response:** Returns the detected language, provider used, audio duration, and a list of transcription segments.

**Usage:** Use this endpoint to convert recorded audio into text. Diarization is supported for providers that allow it, enabling per-speaker segment labeling.

***

### 🔐 Authentication

**Prerequisite:** This endpoint requires a valid API access key.

**Required headers:**

```
x-api-access-key: <API_KEY>
voicehub-agent-id: <yourAgentId>
```

| Header              | Description                                                                  |
| ------------------- | ---------------------------------------------------------------------------- |
| `voicehub-agent-id` | Dataqueue Workspace ID. All STT configuration for this workspace will apply. |
| `x-api-access-key`  | API key for authenticating the request.                                      |

***

### 🧾 Request

**Content-Type:** `multipart/form-data`

| Field                 | Type       | Required | Description                                                                                      |
| --------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------ |
| `file`                | `binary`   | ✅        | Audio file to transcribe. Supported formats: WAV (PCM 16kHz), OGG, MP3. Maximum size: **15 MB**. |
| `language`            | `string`   | ✅        | BCP-47 language code (e.g. `en`, `ar`).                                                          |
| `diarizationEnabled`  | `boolean`  | ❌        | Enable speaker diarization. Defaults to `false`.                                                 |
| `additionalLanguages` | `string[]` | ❌        | Additional BCP-47 language codes for multi-language audio.                                       |

***

### ✅ Example Request

```bash
curl -X POST "https://voicehub.dataqueue.ai/stt-transcribe/public/transcribe" \
  -H "x-api-access-key: sk_live_abc123" \
  -H "voicehub-agent-id: ws_123" \
  -F "file=@/path/to/audio.wav" \
  -F "language=en" \
  -F "diarizationEnabled=true"
```

***

### 📤 Response

**Status:** `200 OK`

```json
{
  "language": "en",
  "provider": "deepgram",
  "durationSeconds": 42.5,
  "segments": [
    {
      "text": "Hello, how can I help you today?",
      "confidence": 0.98,
      "speaker": "speaker_0"
    },
    {
      "text": "I'd like to check my account balance.",
      "confidence": 0.95,
      "speaker": "speaker_1"
    }
  ]
}
```

#### Response Fields

| Field             | Type     | Description                                                            |
| ----------------- | -------- | ---------------------------------------------------------------------- |
| `language`        | `string` | The language code used for transcription.                              |
| `provider`        | `string` | The STT provider that processed the audio (e.g. `deepgram`, `google`). |
| `durationSeconds` | `number` | Duration of the audio file in seconds.                                 |
| `segments`        | `array`  | List of transcription segments. See segment fields below.              |

#### Segment Fields

| Field        | Type     | Description                                                                              |
| ------------ | -------- | ---------------------------------------------------------------------------------------- |
| `text`       | `string` | Transcribed text for this segment.                                                       |
| `confidence` | `number` | *(Optional)* Confidence score between `0` and `1`. Not all providers return this.        |
| `speaker`    | `string` | *(Optional)* Speaker label (e.g. `speaker_0`). Only present when diarization is enabled. |

***

### ❌ Error Responses

| Status | Description                                      |
| ------ | ------------------------------------------------ |
| `400`  | Missing or invalid audio file, or bad parameters |
| `401`  | Invalid or missing API key                       |
| `403`  | Insufficient credits                             |
| `405`  | Operation not allowed for this workspace         |