语音转写¶
上传一段音频,使用具有语音识别能力的 Genesis 模型将其转为文本。本接口同步返回完整结果。
POST https://token.moi.matrixorigin.cn/v1/audio/transcriptions
调用前准备¶
按调用 Genesis API配置服务地址和具有 Genesis 模型权限的访问凭据。
准备一份音频文件。Qwen3-ASR Flash 同步转写适用于约 5 分钟以内的短音频;同时满足下面的文件大小限制。
公开模型 ID 由部署配置决定,不能直接用上游供应商模型名称替代。
请求参数¶
以下使用本地 WAV 文件。将模型标识替换为前一步选定的公开模型 ID:
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。
字段 |
位置 |
必填 |
说明 |
|---|---|---|---|
|
multipart 文件 |
是 |
非空音频文件;填写正确 MIME 类型或使用可识别的扩展名。 |
|
multipart 表单 |
是 |
当前凭据可调用且已启用的公开语音识别模型 ID、名称或别名。 |
|
multipart 表单 |
否 |
语言代码,例如 |
同名字段只能出现一次。接口固定为非流式,未列出的表单字段不作为可用能力;无需添加 stream、response_format 或时间戳参数。
格式 |
文件扩展名 |
推荐 MIME 类型 |
|---|---|---|
WAV |
|
|
MP3 |
|
|
M4A |
|
|
WebM |
|
|
OGG |
|
|
FLAC |
|
|
音频经过 Base64 编码后不得超过 10 MiB,原始文件约不超过 7.5 MiB;部署的请求体上限还可能更小。大小超限时缩短录音或分段后分别调用;不要仅更换文件扩展名。
成功响应¶
{
"text": "你好,这是一段语音转写示例。",
"model": "<公开语音识别模型 ID>",
"request_id": "<上游请求 ID>",
"usage": {"seconds": 48}
}
字段 |
类型 |
说明 |
|---|---|---|
|
string |
完整转写文本。上游成功却没有有效文本时,接口返回错误。 |
|
string |
请求使用的公开模型标识。 |
|
string |
可选;供应商提供时返回。排障时保留。 |
|
object |
可选;供应商返回的真实用量。包含 |
错误响应¶
错误使用 Genesis 的 OpenAI 兼容错误结构。先保留 HTTP 状态、错误消息和可用的请求 ID,再按原因处理。
HTTP 状态 |
检查项 |
|---|---|
|
是否使用 multipart;文件和模型是否非空;是否有重复字段或非法语言代码。 |
|
凭据是否有效,是否只发送一种认证请求头。 |
|
公开模型是否存在、启用并对当前凭据开放。 |
|
音频编码后大小和部署请求体上限;缩短输入后重试。 |
|
限流提示;按服务返回的信息控制重试。 |
|
该模型缺少可用的语音识别供应商端点,请联系部署管理员。 |
|
上游响应无效或转写文本为空。 |
|
当前模型没有可用的供应商路由。 |
调用超时不证明服务没有执行。检查请求记录后再决定是否重试,避免重复调用与计费。