迁移指南
从历史 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。历史路径仅用于兼容已有客户端，不应继续用于新开发。
路径映射
| 历史路径 | 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，不要重新创建任务。