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

# Create transcription

> Transcribe audio with optional message context and a dynamic ASR dictionary.

Creates a transcription from an audio file. You can optionally provide chat-style messages and dictionary terms to improve recognition.

<Note>
  This endpoint requires a developer API key on beta. Use either `Authorization: Bearer vos_...` or `X-Api-Key: vos_...`.
</Note>

## Authentication

Send a developer API key in either header:

```http theme={null}
Authorization: Bearer vos_...
```

or:

```http theme={null}
X-Api-Key: vos_...
```

## Endpoint

```http theme={null}
POST https://beta.api.voiceos.com/v1/audio/transcriptions
Content-Type: multipart/form-data
```

## Request body

<ParamField body="file" type="file" required>
  Audio file to transcribe. Supported formats: `wav`, `webm`, `mp3`, `m4a`, and `ogg`.
</ParamField>

<ParamField body="messages" type="string">
  Optional. JSON string containing an array of chat-style messages. Omit this field to run plain transcription from audio only.
</ParamField>

<ParamField body="languages" type={'"auto" | string | string[]'}>
  Language constraint. Omit or set to `"auto"` for auto-detect, pass a single language code like `"en"`, or pass an array like `["en", "ja"]`.
</ParamField>

<ParamField body="dictionary" type="string[]">
  Optional JSON array or comma-separated list of explicit dictionary terms.
</ParamField>

<ParamField body="response_format" type={'"json"'}>
  Response format. Only `json` is supported.
</ParamField>

## Response

<ResponseField name="text" type="string">
  Final transcript output.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl https://beta.api.voiceos.com/v1/audio/transcriptions \
    -H "Authorization: Bearer vos_..." \
    -F "file=@sample.mp3" \
    -F 'messages=[{"role":"system","content":"You are in a voice agent coding session."},{"role":"user","content":"Mention QdrantVectorCache, LangGraph, and RAGPipelineConfig."}]' \
    -F 'languages=["en","ja"]' \
    -F 'dictionary=["VoiceOS","ASR"]' \
    -F 'response_format=json'
  ```

  ```json Response theme={null}
  {
    "text": "Let's wire QdrantVectorCache into LangGraph and compare it with the RAGPipelineConfig."
  }
  ```
</CodeGroup>

## Errors

| Status | Code                          | Meaning                                                     |
| ------ | ----------------------------- | ----------------------------------------------------------- |
| `400`  | `invalid_request`             | `messages`, `languages`, or `dictionary` failed validation. |
| `400`  | `missing_file`                | The multipart request did not include `file`.               |
| `400`  | `unsupported_audio_type`      | The uploaded file type is not supported.                    |
| `400`  | `unsupported_response_format` | Only `response_format=json` is supported.                   |
| `415`  | `unsupported_media_type`      | Request was not `multipart/form-data`.                      |
| `502`  | `transcription_failed`        | ASR or LLM provider failed.                                 |