# 灵感生成
> 用 1 到 4 段公网音频直链作为参考，生成新歌
> 与翻唱不同：这里给的是音频参考，不是源曲引用
> 直接用 URL，不需要 task_id
`POST /v1/music/generations/inspo`
## 认证
- `Authorization` (string / 必填) — 所有接口均使用 Bearer Token 进行认证。 获取 API Key：[访问控制台](https://api.oairoute.com/keys) 创建。 请求时在请求头中添加： ```http Authorization: Bearer YOUR_OAIRoute_KEY ```
## 请求参数
- `model` (string / 可选) — 音频模型，默认 `suno`，当前只有这一个取值。
- `audio_urls` (array / 必填) — 可公开访问的音频 URL 数组，**1 到 4 个元素**。 直接给音频直链，不是 task_id。模型会参考这些音频的风格与结构生成新曲。
- `version` (string / 可选) — 公共版本，取值 `v6`（默认）、`v6-wild`、`v6-mini`。与 `custom_model_id` 互斥。
- `custom_model_id` (string / 可选) — 创建模型任务返回的完整 UUID。使用时省略 `version` 字段。
- `prompt` (string / 可选) — 歌词或内容。
- `title` (string / 可选) — 标题。
- `tags` (string / 可选) — 风格标签。
- `negative_tags` (string / 可选) — 排除的风格标签。
- `style_weight` (number / 可选) — 风格权重，取值 0.00 到 1.00。
- `weirdness` (number / 可选) — 创意度权重，取值 0.00 到 1.00。兼容旧名 `weirdness_constraint`，新请求请用 `weirdness`。
- `audio_weight` (number / 可选) — 音频权重，取值 0.00 到 1.00。
- `vocal_gender` (string / 可选) — 人声性别，取值 `Male` 或 `Female`。
- `auto_lyrics` (boolean / 可选) — 为 `true` 时对输入歌词进行二次创作。
- `variety` (string / 可选) — 风格变化程度，取值 `off`、`normal`、`high`、`extra`、`max`。可省略。
- `max_mode` (boolean / 可选) — 启用 Max 模式，默认 `false`，按普通售价的 2 倍计费。
- `audio_format` (string / 可选) — 输出音频格式，取值 `mp3`、`m4a`、`wav`。
## 这个端点不接受的字段
| 字段 | 说明 |
|---|---|
| `custom` | 本端点没有灵感/自定义模式的区分 |
| `instrumental` | 不支持纯音乐标记 |
| `gpt_description` | 用 `prompt` 而非这个字段 |
| `persona_id` | 不支持绑定 Persona |
| 目标时长字段 | 不支持指定 `duration` 或 `duration_s` |
传了这些字段不会报错，但也不会生效。
## 提交响应
- `code` (integer) — 响应状态码，成功为 200。
- `data[].status` (string) — 任务状态，提交成功时固定为 `submitted`。
- `data[].task_id` (string) — 任务唯一标识，用于轮询 `GET /v1/music/tasks/{task_id}`。
## 轮询结果
- `status` (string) — 取值 `pending`、`processing`、`completed`、`failed`。生成中为前两者。
- `progress` (integer) — 进度百分比，0 到 100，节点不保证固定变化。
- `result.music[].audio_url` (string) — 任务完成后的成品音频地址。
- `error.message` (string) — 失败原因。失败自动退回预扣额度。
轮询间隔建议 3 到 5 秒，直到 `status` 变为 `completed` 或 `failed`。典型耗时 30 到 120 秒。
## 参考音频怎么准备
`audio_urls` 用的链接必须是公网可访问的直链。几个实际要求：
- 不能是需要登录才能下载的地址
- 不能是网页地址（比如 YouTube 链接），必须是音频文件本身
- 音频格式建议用 mp3 或 wav
- 单条音频不宜过长，截取代表性片段即可
> **Note:** 
> 四段参考音频不要风格冲突太大。模型会试图融合所有参考，一段重金属加一段摇篮曲，结果往往两边都不像。想要某种风格占主导，把它放在数组第一位，并调高 `style_weight`。
## 错误码
错误响应的格式、状态码与重试建议见[错误码与限流](../../../support/errors.html)，常见报错的排查步骤见[常见问题](../../../support/faq.html)。
## 使用示例
提交一个任务并拿到 `task_id`：
> **Note:** 
> 提交成功只表示任务已受理。真正的产物要拿返回的 `task_id` 去任务查询接口轮询，`status` 变成 `completed` 之后才有结果。
**灵感生成{Inspiration generation}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/music/generations/inspo' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "suno",
    "audio_urls": [
      "https://example.com/ref-a.mp3",
      "https://example.com/ref-b.mp3"
    ],
    "tags": "lo-fi, mellow",
    "style_weight": 0.75
  }'
```
**灵感生成{Inspiration generation}::Python**
```
import requests
res = requests.post(
    "https://api.oairoute.com/v1/music/generations/inspo",
    headers={
        "Authorization": "Bearer YOUR_OAIRoute_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "suno",
        "audio_urls": [
            "https://example.com/ref-a.mp3",
            "https://example.com/ref-b.mp3",
        ],
        "tags": "lo-fi, mellow",
        "style_weight": 0.75,
    },
)
print(res.json()["data"][0]["task_id"])
```
**灵感生成{Inspiration generation}::JavaScript**
```
const url = "https://api.oairoute.com/v1/music/generations/inspo";
const options = {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "suno",
    "audio_urls": [
      "https://example.com/ref-a.mp3",
      "https://example.com/ref-b.mp3"
    ],
    "tags": "lo-fi, mellow",
    "style_weight": 0.75
  }),
};
fetch(url, options)
  .then((res) => res.json())
  .then((json) => console.log(json))
  .catch((err) => console.error(err));
```
**200 灵感生成{Inspiration generation}**
```
{
  "code": 200,
  "data": [
    { "status": "submitted", "task_id": "task_01K8C33M0HP1GJWBJYZMKX1XS1" }
  ]
}
```