基础概念

了解 Moss API 的模型标识、输入格式、请求执行方式和响应方式。

模型与场景

接入时先从业务场景出发选择模型。场景指南提供推荐调用方式和可复制示例；API Reference 提供完整请求参数、返回值和错误说明。

场景	实际调用方式
单人语音生成	`model=moss-tts-1.5-flash`
多说话人转写	`model=moss-transcribe-diarize-pro`
图片与视频理解	`model=moss-vl-1.0`

不同 endpoint 接受的输入方式不同。文本和配置通常放在 JSON 请求体中；本地文件直接上传使用 multipart/form-data；已上传或托管的文件可以通过 file_id 或 URL 引用。

方式	说明	常见场景
JSON 字段	直接在请求体中传文本、参数和引用 ID	TTS `input`、VL `input_text`、`voice_id`
本地文件	通过接口指定的文件字段上传，例如 `file`；创建音色使用 `audio_sample`	音频转写、创建音色、上传文件
`file_id`	先上传文件，再在业务接口中复用	音频转写、多模态理解
URL	传公网 URL 或对象存储 URL，服务端需要能访问	音频转写、多模态理解

voice_id 是语音生成使用的音色唯一标识。TTS 和 TTSD 只接受音色 ID，不接受 voice_url、voice_data、内联音频或参考音频作为音色输入。

获取方式	说明
查询音色列表	调用 `GET /v1/audio/voices` 获取当前账号可用音色。
创建音色	调用 `POST /v1/audio/voices` 上传参考音频并生成新音色。
音色库复制	在 Mossland 音色库中复制音色卡片上的 ID。

同步、异步和流式是三种不同的执行方式。流式不等于异步，也不等于双向实时对话。

方式	说明	适合场景
同步	请求保持连接，完成后直接返回结果。	短文本 TTS、短音频转写、图片理解
异步	传 `async=true` 创建任务；通过 `task_id` 查询完整结果，可选通过 `webhook_url` 接收终态通知。	较长语音生成、较长音频处理
流式	传 `stream=true`，服务端持续返回音频分片或事件。	低延迟 TTS、转写事件实时返回

如果某个 endpoint 支持流式，API Reference 会在请求参数中明确 stream、stream_format 和对应响应事件。通常不要同时传 stream=true 与 async=true。

不同 endpoint 的返回对象不同。客户端应按具体 Reference 读取需要的字段，并忽略未使用的兼容字段。

响应类型	读取方式
音频二进制	当 `Content-Type` 为 `audio/*` 时，直接读取响应体并保存或播放音频，不要按 JSON 解析。
音频结果 JSON	确认 `status=SUCCESS` 后读取 `url` 获取生成音频，并及时下载结果文件。
异步创建 JSON	读取 `task_id` 和 `retry_after`，再调用 `GET /v1/audio/tasks/{task_id}` 查询任务。
任务查询 JSON	根据 `status` 判断任务状态；成功后按具体能力读取 `url`、`text` 或 `segments`，失败时读取 `error`。
转写 JSON	普通转写读取 `text`；说话人分离结果读取 `text` 和 `segments`。
Responses API 对象	确认 `status=completed` 后读取 `output[].content[].text`；`status=incomplete` 时检查 `incomplete_details`。
SSE 事件流	当 `Content-Type` 为 `text/event-stream` 时，按顺序解析每条 `data:` 中的 JSON，并根据 `type` 处理增量和结束事件。
错误 JSON	请求失败时，读取 `error.code`、`error.message` 和 `error.param` 等字段定位问题。

排查时优先确认 endpoint、model、输入方式、文件大小、URL 可访问性和错误体中的 error.code。完整错误结构见错误码。