API 文档音色管理
音色设计
根据文字描述设计音色、试听候选，并保存为可复用音色。
音色设计
音色设计分为两步：先创建临时设计并试听候选，再保存其中一个候选，获得可用于 TTS 的永久 voiceId。
1. 创建试听
POST /api/open/v1/voice-designs
Authorization: Bearer YOUR_API_KEY
Idempotency-Key: unique-preview-request
Content-Type: application/json{
"prompt": "温暖、沉稳、吐字清晰的女性旁白",
"previewText": "你好，这是为你设计的新音色。",
"providers": ["fishaudio", "minimax"]
}响应包含临时 designId、一个或多个 candidateId、受保护的 previewAudioUrl 和计费信息。下载试听音频时需要使用同一个 Bearer API 密钥。
2. 保存候选
POST /api/open/v1/voice-designs/{designId}/voices
Authorization: Bearer YOUR_API_KEY
Idempotency-Key: unique-save-request
Content-Type: application/json{
"candidateId": "vdc_example",
"name": "温暖旁白",
"visibility": "private"
}保存成功后返回永久 voiceId。后续 TTS 请求应使用 voiceId，不要把 designId 或 candidateId 当作音色 ID。
试听会话会按服务端配置过期。两个 POST 请求都必须使用各自的 Idempotency-Key；相同请求可以安全重放，修改请求体时必须更换 Key。