<span id="语音转写"></span>

# Transcribe audio

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

Upload an audio file and use an available Genesis speech-recognition model to return its transcript. This endpoint returns a complete synchronous response.

```text
POST https://token.moi.matrixorigin.cn/v1/audio/transcriptions
```

<span id="调用前准备"></span>

## Before you begin

1. [Configure the Genesis endpoint and credential](../../../developer/quickstart/genesis/http-api.md#sdk-genesis-http-prepare).
2. Select a speech-recognition model in the [model marketplace](../../../guides/genesis/models.md) and confirm that your credential can call it through [List models](models.md). Preserve its public model ID.
3. Prepare an audio file. Synchronous Qwen3-ASR Flash transcription is intended for short recordings of about five minutes or less, subject to the size limits below.

Public model IDs depend on the deployment. An upstream provider's native model name is not a substitute.

(id3)=

<span id="请求示例"></span>

<span id="请求参数"></span>

## Request parameters

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

Use a local WAV file and the selected public model ID:

```bash
export ASR_MODEL_ID='<公开语音识别模型 ID>'

curl --fail-with-body "$GENESIS_BASE_URL/audio/transcriptions"   -H "Authorization: Bearer $GENESIS_ACCESS_TOKEN"   -F "model=$ASR_MODEL_ID"   -F 'language=zh'   -F 'file=@sample.wav;type=audio/wav'
```

When using `-F`, let cURL generate `Content-Type` with its boundary. Upload one audio file per request. Do not replace the file part with JSON, a file URL, or a Base64 string.

:::::
:::::{tab-item} Parameters

| Field | Location | Required | Description |
| --- | --- | --- | --- |
| `file` | Multipart file | Yes | A nonempty audio file with a correct MIME type or recognized extension. |
| `model` | Multipart form | Yes | ID, name, or alias of an enabled public ASR model available to the credential. |
| `language` | Multipart form | No | Language code, such as `zh` or `en`, using only letters, digits, underscores, or hyphens. A provider may ignore this field. |

Each field may appear only once. This API is nonstreaming. Unlisted form fields are not supported options; do not add `stream`, `response_format`, or timestamp parameters.

| Format | File extension | Recommended MIME type |
| --- | --- | --- |
| WAV | `.wav` | `audio/wav` |
| MP3 | `.mp3` | `audio/mpeg` |
| M4A | `.m4a` | `audio/mp4` |
| WebM | `.webm` | `audio/webm` |
| OGG | `.ogg` | `audio/ogg` |
| FLAC | `.flac` | `audio/flac` |

Base64-encoded audio must not exceed 10 MiB, corresponding to about 7.5 MiB of raw audio. The deployment's request-size limit can be smaller. Shorten or split oversized recordings rather than renaming their extensions.

:::::
::::::
:::::::

<span id="成功响应"></span>

## Successful response

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{
  "text": "你好，这是一段语音转写示例。",
  "model": "<公开语音识别模型 ID>",
  "request_id": "<上游请求 ID>",
  "usage": {"seconds": 48}
}
```

:::::
:::::{tab-item} Fields

| Field | Type | Description |
| --- | --- | --- |
| `text` | string | Complete transcript. An upstream success without valid text is treated as an error. |
| `model` | string | Requested public model identifier. |
| `request_id` | string | Optional; returned when supplied by the provider. Preserve it for troubleshooting. |
| `usage` | object | Optional provider-reported usage. Duration in `seconds` can be used for per-minute billing. |

:::::
::::::
:::::::

<span id="错误处理"></span>

<span id="错误响应"></span>

## Error response

Errors use the Genesis OpenAI-compatible error structure. Preserve the HTTP status, message, and available request ID.

| HTTP status | What to check |
| --- | --- |
| `400` | Multipart encoding, nonempty file and model, duplicate fields, and language syntax. |
| `401` | Credential validity and a single authentication header. |
| `404` | Public model existence, enabled state, and access. |
| `413` | Encoded audio size and deployment request-size limit; shorten the input. |
| `429` | Rate-limit feedback before retrying. |
| `501` | Missing provider ASR endpoint; contact the deployment administrator. |
| `502` | Invalid upstream response or empty transcript. |
| `503` | No available provider route for the model. |

A timeout does not establish that processing never ran. Inspect request records before retrying to avoid duplicate calls and charges.
