迁移指南
从历史 Open API 路径迁移到 Open API v1。
迁移指南
TTS v3 迁移
新的 TTS 客户端应使用 HTTP v3 和 Realtime v3；现有 HTTP v1/v2 与 Realtime v2 继续兼容。HTTP 路径改为 /api/open/v3/speech/tts、/api/open/v3/speech/tts/jobs、/api/open/v3/voices，OpenAPI 为 /api/open/v3/openapi.json。请求只保留平台 voiceId、公共 modelId 和通用控制项。Realtime 改用 /v3/tts/live、realtime.tts.msgpack.v3 和 camelCase 字段，以 ready.effectiveRequest 作为实际配置。HTTP 重试保持稳定的 X-Request-Id，Realtime 可靠模式保持稳定的 requestId。
除上文使用 v3 的 TTS 接口外，其他尚未提供 v3 的 Open API 新接入使用 /api/open/v1。历史路径仅用于兼容已有客户端，不应继续用于新开发。
HTTP v2 同步迁移到 v3
POST /api/open/v2/speech/tts 目前仍可用，退役日期尚未确定。迁移时按以下步骤更新客户端：
- 将生成地址改为
POST /api/open/v3/speech/tts，继续通过Authorization: Bearer传递 API Key。v2 请求体中的token不属于 v3 请求字段，应移除。 - 保留
text、voiceId和 v3 支持的通用控制项。通过GET /api/open/v3/speech/tts/capabilities查询可用模型，再确认所选音色的modelIds包含该模型。将选定的公共模型 ID 放入modelId；不要把 v2 的engineModelId、version或qwenModel原样传给 v3。 - 如使用 v2 的
minimaxEmotion，先确认目标模型支持情绪控制，再改用 v3 的emotion。删除其他供应商专属字段；v3 对未知字段返回400。 - 为每次逻辑生成提供稳定的
Idempotency-Key，将X-Request-Id用于追踪。先用测试音色和真实业务参数核对音频、错误处理及积分，再切换正式流量。 - 长文本或需要在超时后找回结果时，使用
POST /api/open/v3/speech/tts/jobs，保存任务 ID 并轮询、下载；同步 v3 响应不会重放已经生成的音频。
本节仅针对 HTTP 同步 v2。/v2/tts/live 是另一套 Realtime 协议，不在此次迁移范围内。
路径映射
| 历史路径 | Open API v1 路径 |
|---|---|
POST /api/open/create-model | POST /api/open/v1/voices |
POST /api/open/delete-model | DELETE /api/open/v1/voices/{voiceId} |
POST /api/open/list-models | GET /api/open/v1/voices |
POST /api/open/lip-sync/create | POST /api/open/v1/media/lip-sync/jobs |
GET /api/open/lip-sync/list | GET /api/open/v1/media/lip-sync/jobs |
GET /api/open/lip-sync/query | GET /api/open/v1/media/lip-sync/jobs/{jobId} |
最终请求和响应结构以机器可读定义为准：
GET /api/openapi.json建议迁移顺序
- 先迁移账户、音色列表和任务查询等只读接口。
- 为请求和响应解析补充测试后，再迁移创建类接口。
- 发布期间记录旧路径、新路径、HTTP 状态码和
requestId。 - 确认产线流量不再依赖旧路径后，再从客户端移除兼容代码。
V1 请求统一使用 Bearer API Key。TTS 的音色 ID 使用 voiceId，引擎模型使用 modelId；reference_id 仅作为历史音色字段别名保留。
首次联通测试可以使用系统测试音色 00a1b221-6137-4b73-ad62-b0cbce134167；验证成功后再替换为通过 GET /api/open/v1/voices 查询到的目标音色 ID。
异步接口创建成功后应立即保存任务 ID。网络中断、轮询和支持排查都应继续使用这个 ID，不要重新创建任务。