# 生成混搭
> 把两首已有歌曲融合成一首新歌，异步任务
> `task_ids` 必须恰好两个
> 其余生成参数与「风格翻唱」同源
`POST /v1/music/generations/mashup`
## 认证
- `Authorization` (string / 必填) — 所有接口均使用 Bearer Token 进行认证。 获取 API Key：[访问控制台](https://api.oairoute.com/keys) 创建。 请求时在请求头中添加： ```http Authorization: Bearer YOUR_OAIRoute_KEY ```
## 引用两个源
- `task_ids` (array / 必填) — 两个源音轨所在任务的 task_id。**长度必须恰好为 2**，数量不对时提交阶段直接返回 400。
- `audio_indexes` (array / 可选) — 指定每个任务从结果 `data.result.music[]` 中取第几首，默认 `[1, 1]`，与 `task_ids` 一一对应。
- `instrumental` (boolean / 可选) — `true` 为纯器乐（无人声），`false` 为带人声。默认 `false`。
## 生成参数
- `model` (string / 可选) — 音频模型，默认 `suno`。
- `version` (string / 可选) — 公共版本，取值 `v6`（默认）、`v6-wild`、`v6-mini`。使用 `custom_model_id` 时应省略本字段。
- `custom_model_id` (string / 可选) — 创建模型任务时返回的完整 UUID。与 `version`、`persona_id` 互斥。
- `custom` (boolean / 可选) — `true` 为自定义模式（`prompt` 作歌词）；`false` 为灵感模式（用 `gpt_description`）。 不传时按内容推断：有 `prompt` 则 `true`；无 `prompt` 有 `gpt_description` 则 `false`；否则有 `tags` 或 `title` 则 `true`。
- `prompt` (string / 条件必填) — `custom` 为 `true` 且 `instrumental` 为 `false` 时必须给出歌词。 灵感模式下不生效，但已提交的内容仍须满足长度限制。
- `gpt_description` (string / 条件必填) — 灵感模式提示词。`custom` 为 `false` 时必填，缺失会在提交阶段返回 400 且不扣费。
- `title` (string / 可选) — 标题，仅 `custom` 为 `true` 时生效。
- `tags` (string / 可选) — 风格标签，仅 `custom` 为 `true` 时生效。
- `negative_tags` (string / 可选) — 需排除的风格标签，仅 `custom` 为 `true` 时生效。
- `auto_lyrics` (boolean / 可选) — `true` 表示对输入歌词再做一次创作，仅 `custom` 为 `true` 时生效。
- `style_weight` (number / 可选) — 风格权重，0.00 到 1.00。越界在提交阶段返回 400。仅 `custom` 为 `true` 时生效。
- `weirdness` (number / 可选) — 创意权重，0.00 到 1.00。兼容旧名 `weirdness_constraint`，新请求建议用 `weirdness`。
- `audio_weight` (number / 可选) — 音频权重，0.00 到 1.00。仅 `custom` 为 `true` 时生效。
- `vocal_gender` (string / 可选) — 人声性别，取值 `Male` 或 `Female`。两种模式都生效。
- `persona_id` (string / 可选) — 风格 ID，仅 `custom` 为 `true` 时生效，与 `custom_model_id` 互斥。
- `variety` (string / 可选) — 风格变化程度，取值 `off`、`normal`、`high`、`extra`、`max`。可省略。
- `max_mode` (boolean / 可选) — 启用 Max 模式，默认 `false`。要求处于自定义模式，按普通售价 2 倍计费。
- `audio_format` (string / 可选) — 输出音频格式，取值 `mp3`、`m4a`、`wav`。
本接口**不支持**指定目标时长。
## 响应
- `code` (integer) — 响应状态码，成功为 200。
- `data[].status` (string) — 任务状态，取值 `submitted`。
- `data[].task_id` (string) — 任务唯一标识，用于轮询 `GET /v1/music/tasks/{task_id}`。
轮询间隔 3 到 5 秒，音乐生成通常 30 到 120 秒。中间态 `pending` 或 `processing`，`progress` 为 0 到 100 整数且不保证按固定节点变化。完成后从 `data.result.music[]` 取 `audio_url`。失败时 `data.error.message` 说明原因，预扣额度自动退回。
## 参数校验的顺序
`custom` 只决定哪些字段生效，**但未生效的字段若已提交，仍需满足类型、范围与长度要求**。
也就是说：传了 `tags` 却用灵感模式，`tags` 不参与生成，但如果它超长，照样会 400。不用的字段就别传。
## 错误码
错误响应的格式、状态码与重试建议见[错误码与限流](../../../support/errors.html)，常见报错的排查步骤见[常见问题](../../../support/faq.html)。
## 使用示例
提交一个任务并拿到 `task_id`：
> **Note:** 
> 提交成功只表示任务已受理。真正的产物要拿返回的 `task_id` 去任务查询接口轮询，`status` 变成 `completed` 之后才有结果。
**生成混搭{Generate mashup}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/music/generations/mashup' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "suno",
    "task_ids": ["task_A", "task_B"],
    "audio_indexes": [1, 1],
    "custom": true,
    "prompt": "[Verse]\n两首歌的旋律在这里交汇",
    "tags": "electronic, orchestral",
    "style_weight": 0.65
  }'
```
**生成混搭{Generate mashup}::Python**
```
import requests
res = requests.post(
    "https://api.oairoute.com/v1/music/generations/mashup",
    headers={
        "Authorization": "Bearer YOUR_OAIRoute_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "suno",
        "task_ids": ["task_A", "task_B"],
        "audio_indexes": [1, 1],
        "custom": True,
        "prompt": "[Verse]\n两首歌的旋律在这里交汇",
        "tags": "electronic, orchestral",
        "style_weight": 0.65,
    },
)
print(res.json()["data"][0]["task_id"])
```
**生成混搭{Generate mashup}::JavaScript**
```
const url = "https://api.oairoute.com/v1/music/generations/mashup";
const options = {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "suno",
    "task_ids": [
      "task_A",
      "task_B"
    ],
    "audio_indexes": [
      1,
      1
    ],
    "custom": true,
    "prompt": "[Verse]\n两首歌的旋律在这里交汇",
    "tags": "electronic, orchestral",
    "style_weight": 0.65
  }),
};
fetch(url, options)
  .then((res) => res.json())
  .then((json) => console.log(json))
  .catch((err) => console.error(err));
```
**200 生成混搭{Generate mashup}**
```
{
  "code": 200,
  "data": [
    { "status": "submitted", "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K" }
  ]
}
```
**纯器乐混搭{Instrumental mashup}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/music/generations/mashup' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "suno",
  "task_ids": ["task_A", "task_B"],
  "instrumental": true,
  "tags": "jazz, lo-fi",
  "max_mode": true
}'
```
**纯器乐混搭{Instrumental mashup}::Python**
```
import requests
url = "https://api.oairoute.com/v1/music/generations/mashup"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
      "model": "suno",
      "task_ids": ["task_A", "task_B"],
      "instrumental": true,
      "tags": "jazz, lo-fi",
      "max_mode": true
    }
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**纯器乐混搭{Instrumental mashup}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/music/generations/mashup", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "suno",
    "task_ids": ["task_A", "task_B"],
    "instrumental": true,
    "tags": "jazz, lo-fi",
    "max_mode": true
  }),
});
console.log(await res.json());
```
**200 纯器乐混搭{Instrumental mashup}**
```
{
  "code": 200,
  "data": [
    { "status": "submitted", "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K" }
  ]
}
```