创建语音
- 从音频里提取音色，生成可复用的声音，异步任务
- 与 Persona 不同：本接口直接接收音频 URL，不用 task_id
- 结果按实际返回展示，不要当 persona_id 用
认证
All endpoints authenticate with a Bearer token.
Get an API key: open the console and create one.
Add it to the request header:
Authorization: Bearer YOUR_OAIRoute_KEY请求参数
音频模型，当前只支持 suno。
源音轨的公网可访问 URL，系统据此提取音色。
仅接受 MP3 与 WAV。缺失时报 400。
The audio model; currently only suno is supported.
A publicly reachable URL for the source track; the system extracts the timbre from it.
Only MP3 and WAV are accepted. Missing returns a 400.
与其他引用方式的区别
本接口是音频类接口里的一个例外：
| 接口 | 引用方式 |
|---|---|
| 大多数 suno 操作 | task_id + audio_index |
| 创建语音（本页） | 直接给 audio_url |
所以这里不需要 task_id，也不需要 audio_index。传了不生效。
本端点没有版本维度，传 version 会被忽略。
This endpoint is an exception among the audio endpoints:
| Endpoint | How it references |
|---|---|
| Most suno operations | task_id + audio_index |
| Create voice (this page) | An audio_url directly |
So no task_id and no audio_index here. Passing them has no effect.
This endpoint has no version dimension; passing version is ignored.
响应
响应状态码。
任务状态，提交成功为 submitted。
任务唯一标识符，用于轮询结果。
响应里没有固定的 voice_id 字段。请按实际返回展示，不要把它当 persona_id 使用——两者是不同概念，persona_id 用于绑定演唱风格，这里的产出是音色。
The response status code.
The task status; submitted on success.
The unique task identifier, for polling the result.
The response has no fixed voice_id field. Render whatever is actually returned, and don't treat it as a persona_id — they're different concepts. persona_id binds a singing style; what's produced here is a timbre.
取结果
用 GET /v1/music/tasks/{task_id} 轮询，间隔 3 到 5 秒，直到 status 为 completed 或 failed。
完成后的结构以实际返回为准。第一次接入时先打印整个 result 看字段名，再写解析逻辑。
Poll GET /v1/music/tasks/{task_id} every 3 to 5 seconds until status is completed or failed.
The completed structure follows whatever is actually returned. On first integration, print the whole result to see the field names before writing parsing logic.
错误
| HTTP | type | 说明 |
|---|---|---|
| 400 | invalid_request_error | 参数无效，如 audio_url 缺失或格式不是 MP3/WAV |
| 401 | authentication_error | 身份验证失败 |
| 402 | payment_required | 账户余额不足 |
| 429 | rate_limit_error | 请求过于频繁 |
| HTTP | type | Notes |
|---|---|---|
| 400 | invalid_request_error | Invalid parameters, e.g. audio_url missing or not MP3/WAV |
| 401 | authentication_error | Authentication failed |
| 402 | payment_required | Insufficient account balance |
| 429 | rate_limit_error | Too many requests |
For more status codes and retry guidance see Error codes and rate limits; for troubleshooting steps on common errors see the FAQ.
使用示例
提交一个任务并拿到 task_id：
提交成功只表示任务已受理。真正的产物要拿返回的 task_id 去任务查询接口轮询，status 变成 completed 之后才有结果。
Submit a task and get a task_id:
A successful submission only means the task was accepted. To get the actual output, poll the task query endpoint with the returned task_id; results appear only after status becomes completed.