# 语音转写

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

上传一段音频，使用具有语音识别能力的 Genesis 模型将其转为文本。本接口同步返回完整结果。

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

## 调用前准备

1. 按[调用 Genesis API](../../../developer/quickstart/genesis/http-api.md#sdk-genesis-http-prepare)配置服务地址和具有 Genesis 模型权限的访问凭据。
2. 从[模型广场](../../../guides/genesis/models.md)选择当前环境开放的语音识别模型，并通过[查询可调用模型](models.md)确认当前凭据可用，保存公开模型 ID。
3. 准备一份音频文件。Qwen3-ASR Flash 同步转写适用于约 5 分钟以内的短音频；同时满足下面的文件大小限制。

公开模型 ID 由部署配置决定，不能直接用上游供应商模型名称替代。

(id3)=

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

## 请求参数

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

以下使用本地 WAV 文件。将模型标识替换为前一步选定的公开模型 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'
```

使用 `-F` 时让 cURL 自动生成带 boundary 的 `Content-Type`。每个请求只上传一个音频文件，不用 JSON、文件 URL 或 Base64 字符串替代文件 part。

:::::
:::::{tab-item} 参数说明

| 字段 | 位置 | 必填 | 说明 |
| --- | --- | --- | --- |
| `file` | multipart 文件 | 是 | 非空音频文件；填写正确 MIME 类型或使用可识别的扩展名。 |
| `model` | multipart 表单 | 是 | 当前凭据可调用且已启用的公开语音识别模型 ID、名称或别名。 |
| `language` | multipart 表单 | 否 | 语言代码，例如 `zh`、`en`；仅使用字母、数字、下划线或连字符。具体供应商可能忽略此字段。 |

同名字段只能出现一次。接口固定为非流式，未列出的表单字段不作为可用能力；无需添加 `stream`、`response_format` 或时间戳参数。

| 格式 | 文件扩展名 | 推荐 MIME 类型 |
| --- | --- | --- |
| 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 编码后不得超过 10 MiB，原始文件约不超过 7.5 MiB；部署的请求体上限还可能更小。大小超限时缩短录音或分段后分别调用；不要仅更换文件扩展名。

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

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

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

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `text` | string | 完整转写文本。上游成功却没有有效文本时，接口返回错误。 |
| `model` | string | 请求使用的公开模型标识。 |
| `request_id` | string | 可选；供应商提供时返回。排障时保留。 |
| `usage` | object | 可选；供应商返回的真实用量。包含 `seconds` 时可用于按分钟计费。 |

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

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

## 错误响应

错误使用 Genesis 的 OpenAI 兼容错误结构。先保留 HTTP 状态、错误消息和可用的请求 ID，再按原因处理。

| HTTP 状态 | 检查项 |
| --- | --- |
| `400` | 是否使用 multipart；文件和模型是否非空；是否有重复字段或非法语言代码。 |
| `401` | 凭据是否有效，是否只发送一种认证请求头。 |
| `404` | 公开模型是否存在、启用并对当前凭据开放。 |
| `413` | 音频编码后大小和部署请求体上限；缩短输入后重试。 |
| `429` | 限流提示；按服务返回的信息控制重试。 |
| `501` | 该模型缺少可用的语音识别供应商端点，请联系部署管理员。 |
| `502` | 上游响应无效或转写文本为空。 |
| `503` | 当前模型没有可用的供应商路由。 |

调用超时不证明服务没有执行。检查请求记录后再决定是否重试，避免重复调用与计费。
