语音转写

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

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

调用前准备

  1. 按调用 Genesis API配置服务地址和具有 Genesis 模型权限的访问凭据。

  2. 从模型广场选择当前环境开放的语音识别模型,并通过查询可调用模型确认当前凭据可用,保存公开模型 ID。

  3. 准备一份音频文件。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。

字段

位置

必填

说明

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;部署的请求体上限还可能更小。大小超限时缩短录音或分段后分别调用;不要仅更换文件扩展名。

成功响应

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

字段

类型

说明

text

string

完整转写文本。上游成功却没有有效文本时,接口返回错误。

model

string

请求使用的公开模型标识。

request_id

string

可选;供应商提供时返回。排障时保留。

usage

object

可选;供应商返回的真实用量。包含 seconds 时可用于按分钟计费。

错误响应

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

HTTP 状态

检查项

400

是否使用 multipart;文件和模型是否非空;是否有重复字段或非法语言代码。

401

凭据是否有效,是否只发送一种认证请求头。

404

公开模型是否存在、启用并对当前凭据开放。

413

音频编码后大小和部署请求体上限;缩短输入后重试。

429

限流提示;按服务返回的信息控制重试。

501

该模型缺少可用的语音识别供应商端点,请联系部署管理员。

502

上游响应无效或转写文本为空。

503

当前模型没有可用的供应商路由。

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

最后更新于