音频转写

音频转写接口。支持 multipart file、file_id、url、audio_url，不支持 audio_data。

POST

/v1/audio/transcriptions

语音识别。请求体为 multipart/form-data 或 JSON。moss-transcribe-1.0 同步返回 { text }；moss-transcribe-diarize-pro 传 diarize=true 返回结构化 segments，可再传 stream=true 以 SSE 返回转写事件。

认证

在请求头中加入 Authorization: Bearer <API_KEY> 完成鉴权，密钥可在控制台「API 密钥」页生成。

curl -X POST https://api.mosi.cn/v1/audio/transcriptions \
  -H "Authorization: Bearer $MOSS_API_KEY"

支持模型

字段	允许值
model	`moss-transcribe-1.0` / `moss-transcribe-diarize-pro`

选择转写模式

场景	model	返回形式
普通音频转写	`moss-transcribe-1.0`	JSON / text
多说话人转写	`moss-transcribe-diarize-pro`	JSON，含 `segments`；可通过 `stream=true` 返回 SSE

请求字段

字段	类型	必填	说明
model	string	是	取值见「选择转写模式」。
diarize	boolean	否	是否返回说话人分离结果；使用 `moss-transcribe-diarize-pro` 时建议传 `true`。
stream	boolean	否	`moss-transcribe-diarize-pro` 支持传 `true`，用于返回 SSE 转写事件；不支持同时传 `async=true`。
response_format	string	否	`json` 返回 JSON；`diarized_json` 返回包含说话人和时间段的结构化 JSON；`text` 返回纯文本。流式场景传 `json` 或 `diarized_json`。
keyterms	string[]	否	热词列表，用于提升专有名词、人名、品牌名、术语等识别准确率。当前版本 `moss-transcribe-diarize-pro` 支持；最多 20 个，每个最多 30 个字符；不传或传 `[]` 表示不启用。
async	boolean	否	设为 `true` 时创建异步任务。
webhook_url	string	否	异步任务完成后回调的 HTTPS URL。
file	multipart file	条件必填	本地文件；单文件最大 512 MB。
file_id	string	条件必填	`/v1/files` 返回的文件 ID。
url	string	条件必填	公网音频 URL；不得指向 localhost、回环地址或私网地址。
audio_url	string	条件必填	`url` 的兼容字段，访问限制相同。

支持格式与上传限制

项目	说明
单文件大小	最大 512 MB；直接上传与 `/v1/files` 保持一致。
已支持格式	AAC、AMR、FLAC、M4A、ALAC、MOV、MP3、MP4、MPG、OGG、OPUS、WAV、WebM、WMA
音视频容器	MOV、MP4、MPG、WebM均可完成转写

请求示例

{
  "model": "moss-transcribe-1.0",
  "file_id": "<file_id>",
  "response_format": "json"
}

{
  "model": "moss-transcribe-diarize-pro",
  "file_id": "<file_id>",
  "diarize": true,
  "response_format": "json"
}

{
  "model": "moss-transcribe-diarize-pro",
  "file_id": "<file_id>",
  "diarize": true,
  "response_format": "diarized_json",
  "keyterms": ["MOSS", "SGLang", "矩池云"]
}

{
  "model": "moss-transcribe-diarize-pro",
  "file_id": "<file_id>",
  "diarize": true,
  "stream": true,
  "response_format": "json"
}

响应字段

普通转写（`response_format=json`）

字段	类型	必返	说明
text	string	是	识别出的完整文本。

多说话人转写

字段	类型	必返	说明
task	string	是	任务类型，当前返回 `transcribe`。
duration	number	是	音频时长，单位为秒。
text	string	是	完整转写文本。
segments	array	是	分段列表；短音频或无有效分段时可能为空数组。
segments[].type	string	有分段时	分段事件类型。
segments[].id	string	有分段时	分段 ID。
segments[].start	number	有分段时	分段起始时间，单位为秒。
segments[].end	number	有分段时	分段结束时间，单位为秒。
segments[].text	string	有分段时	该段文本。
segments[].speaker	string	有分段时	说话人标识，例如 `S01`。

文本响应（`response_format=text`）

多说话人转写流式输出（SSE）

stream=true 时返回 text/event-stream；SSE 帧仅由 data: 行构成（无 event: 行），事件类型写在每帧 JSON 的 type 字段。

字段	类型	必返	说明
task.created	SSE event	是	流式任务创建事件，携带 `task_id` / `object` / `status` / `model`。
transcript.text.delta	SSE event	按内容返回	增量文本事件，携带 `delta` 文本片段。
transcript.segment.done	SSE event	按内容返回	分段完成事件，携带 `content_index` / `speaker` / `text` 等字段。
transcript.text.done	SSE event	是	转写结束事件，可能携带完整 `text` 或 `usage`。
usage	object	事件中可选	用量信息，按服务端实际事件返回。

data: {"type":"task.created","task_id":"<task_id>","object":"audio.transcription","status":"PROCESSING","model":"moss-transcribe-diarize-pro"}

data: {"type":"transcript.text.delta","delta":"大家"}

data: {"type":"transcript.segment.done","content_index":0,"speaker":"S01","text":"大家好，"}

data: {"type":"transcript.segment.done","content_index":1,"speaker":"S02","text":"你好。"}

data: {"type":"transcript.text.done","text":"大家好，你好。","usage":{"prompt_tokens":142,"completion_tokens":12,"total_tokens":154}}

异步创建响应（`async=true`）

字段	类型	必返	说明
id	string	是	任务 ID。
task_id	string	是	任务查询 ID，通常与 `id` 相同。
object	string	是	固定为 `audio.transcription`。
status	string	是	初始状态，例如 `PENDING`。
retry_after	integer	否	建议轮询间隔，单位为秒。
created_at	integer	是	创建时间，Unix 时间戳，单位为秒。
updated_at	integer	否	更新时间，Unix 时间戳，单位为秒。

异步任务完成后的结果字段见 GET /v1/audio/tasks/{task_id}。

下一步

上传文件

上传音频文件并获取 file_id。

查询音色列表

查询当前账号可用音色列表。

错误说明

以下情况返回参数错误：

keyterms 不是字符串数组。
keyterms 包含非字符串元素。
普通 moss-transcribe-1.0 携带非空 keyterms。