# 创建语音
> 从音频里提取音色，生成可复用的声音，异步任务
> 与 Persona 不同：本接口直接接收音频 URL，不用 task_id
> 结果按实际返回展示，不要当 persona_id 用
`POST /v1/music/generations/createVoice`
## 认证
- `Authorization` (string / 必填) — 所有接口均使用 Bearer Token 进行认证。 获取 API Key：[访问控制台](https://api.oairoute.com/keys) 创建。 请求时在请求头中添加： ```http Authorization: Bearer YOUR_OAIRoute_KEY ```
## 请求参数
- `model` (string / 可选) — 音频模型，当前只支持 `suno`。
- `audio_url` (string / 必填) — 源音轨的公网可访问 URL，系统据此提取音色。 **仅接受 MP3 与 WAV**。缺失时报 400。
## 与其他引用方式的区别
本接口是音频类接口里的一个例外：
| 接口 | 引用方式 |
|---|---|
| 大多数 suno 操作 | `task_id` + `audio_index` |
| **创建语音（本页）** | **直接给 `audio_url`** |
所以这里不需要 `task_id`，也不需要 `audio_index`。传了不生效。
> **Note:** 
> 本端点没有版本维度，传 `version` 会被忽略。
## 响应
- `code` (integer) — 响应状态码。
- `data[].status` (string) — 任务状态，提交成功为 `submitted`。
- `data[].task_id` (string) — 任务唯一标识符，用于轮询结果。
> **Note:** 
> 响应里**没有固定的 `voice_id` 字段**。请按实际返回展示，不要把它当 `persona_id` 使用——两者是不同概念，`persona_id` 用于绑定演唱风格，这里的产出是音色。
## 取结果
用 `GET /v1/music/tasks/{task_id}` 轮询，间隔 3 到 5 秒，直到 `status` 为 `completed` 或 `failed`。
完成后的结构以实际返回为准。第一次接入时先打印整个 `result` 看字段名，再写解析逻辑。
## 错误
| HTTP | type | 说明 |
|---|---|---|
| 400 | invalid_request_error | 参数无效，如 `audio_url` 缺失或格式不是 MP3/WAV |
| 401 | authentication_error | 身份验证失败 |
| 402 | payment_required | 账户余额不足 |
| 429 | rate_limit_error | 请求过于频繁 |
更多状态码与重试建议见[错误码与限流](../../../support/errors.html)，常见报错的排查步骤见[常见问题](../../../support/faq.html)。
## 使用示例
提交一个任务并拿到 `task_id`：
> **Note:** 
> 提交成功只表示任务已受理。真正的产物要拿返回的 `task_id` 去任务查询接口轮询，`status` 变成 `completed` 之后才有结果。
**创建语音{Create voice}::cURL**
```
curl -X POST https://api.oairoute.com/v1/music/generations/createVoice \
  -H 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
    "model": "suno",
    "audio_url": "https://your-bucket.s3.amazonaws.com/voice-sample.mp3"
  }'
```
**创建语音{Create voice}::Python**
```
import requests
res = requests.post(
    "https://api.oairoute.com/v1/music/generations/createVoice",
    headers={
        "Authorization": "Bearer YOUR_OAIRoute_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "suno",
        "audio_url": "https://your-bucket.s3.amazonaws.com/voice-sample.mp3",
    },
)
print(res.json()["data"][0]["task_id"])
```
**创建语音{Create voice}::JavaScript**
```
const res = await fetch(
  "https://api.oairoute.com/v1/music/generations/createVoice",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_OAIRoute_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "suno",
      audio_url: "https://your-bucket.s3.amazonaws.com/voice-sample.mp3",
    }),
  }
);
const { data } = await res.json();
console.log(data[0].task_id);
```
**200 创建语音{Create voice}**
```
{
  "code": 200,
  "data": [
    { "status": "submitted", "task_id": "task_01K8E66M0HP1GJWBJYZMKX1XS1" }
  ]
}
```