# 上传音频并翻唱
> 上传一段音频，用新风格重新演绎，一步完成，异步任务
> 与「风格翻唱」不同：这里直接收 `audio_url`，不用 task_id
> 适合用户上传自己哼唱的场景
`POST /v1/music/generations/uploadCover`
## 认证
- `Authorization` (string / 必填) — 所有接口均使用 Bearer Token 进行认证。 获取 API Key：[访问控制台](https://api.oairoute.com/keys) 创建。 请求时在请求头中添加： ```http Authorization: Bearer YOUR_OAIRoute_KEY ```
## 请求参数
- `model` (string / 可选) — 固定为 `suno`，默认值也是 `suno`。
- `audio_url` (string / 必填) — 公网可直链访问的 HTTP(S) 音频地址。 本地路径、`blob:` 地址、以及需要登录才能打开的页面链接都不支持。**建议音频长度不超过 8 分钟**。
- `version` (string / 可选) — 可选 `v6`（默认）、`v6-wild`、`v6-mini`。使用 `custom_model_id` 时不要填写。
- `custom_model_id` (string / 可选) — 创建模型任务时返回的完整 UUID。与 `version`、`persona_id` 不能同时使用。
- `custom` (boolean / 可选) — **建议明确传入**。 为 `false` 时使用 `gpt_description`；为 `true` 时使用歌词和风格字段。
- `instrumental` (boolean / 可选) — 是否生成纯音乐，默认 `false`。 当 `custom=true` 且本字段为 `false` 时，**必须填写 `prompt`**。
- `gpt_description` (string / 条件必填) — 灵感描述。`custom=false` 时必填，上限 3000 字符。
- `prompt` (string / 条件必填) — 自定义模式歌词，上限 5000 字符。
- `tags` (string / 可选) — 风格描述，上限 1000 字符。
- `title` (string / 可选) — 标题，上限 80 字符。
- `negative_tags` (string / 可选) — 不希望出现的风格。
- `style_weight` (number / 可选) — 风格权重，0 到 1。
- `weirdness` (number / 可选) — 创意度权重，0 到 1。
- `audio_weight` (number / 可选) — 音频权重，0 到 1。
- `auto_lyrics` (boolean / 可选) — 是否对输入的歌词再做一次改编。
- `vocal_gender` (string / 可选) — `Male` 或 `Female`。
- `persona_id` (string / 可选) — Persona ID。与 `custom_model_id` 不能同时使用。
- `duration_s` (integer / 可选) — 目标时长，10 到 360 秒。**只在自定义模式下有效**。
- `variety` (string / 可选) — 风格变化程度：`off`、`normal`、`high`、`extra` 或 `max`。
- `max_mode` (boolean / 可选) — Max 模式，默认 `false`。要求使用自定义模式，费用按普通售价的 2 倍计算。
- `audio_format` (string / 可选) — 输出格式：`mp3`、`m4a` 或 `wav`。
## 与其他上传接口的分工
| 接口 | 输入 | 产出 |
|---|---|---|
| 上传音频 | `audioFilePath` | 只有 task_id，供后续引用 |
| **上传并翻唱（本页）** | `audio_url` | **直接出翻唱成品** |
| 上传并延伸 | `audio_url` | 直接出延伸成品 |
本接口是「上传 + 翻唱」一步到位，省掉先传后引用的两步操作。
> **Note:** 
> `custom` 建议明确传。不传时后端会按内容推断，推断结果可能与你预期不同——尤其是同时传了 `prompt` 和 `gpt_description` 的时候。
## 响应
- `code` (integer) — 状态码。
- `data[0].status` (string) — 提交状态，例如 `submitted`。
- `data[0].task_id` (string) — 任务 ID，用于轮询查询结果。
成功时返回 `code: 200`。读取 `data[0].task_id` 后轮询 `GET /v1/music/tasks/{task_id}` 即可。
## 音频准备
`audio_url` 的要求比一般素材更严：
- 必须公网直接可下载，不能要登录态
- 不能是 `blob:` 或本地路径
- 建议不超过 8 分钟
8 分钟以上会被拒或处理质量下降。长音频先自己切出最有代表性的片段。
## 错误码
错误响应的格式、状态码与重试建议见[错误码与限流](../../../support/errors.html)，常见报错的排查步骤见[常见问题](../../../support/faq.html)。
## 使用示例
### 用上传音频做翻唱
给一段公网可下载的音频，模型按提示词重新编曲演唱。`audio_url` 只接受 HTTP(S)，本地路径和 `blob:` 都不行。
### 灵感模式重写
`custom` 保持默认 `false` 时，`prompt` 按创意描述理解。想要精确控制歌词时把 `custom` 设为 `true`，改用 `prompt` 传歌词本体。
### 自定义模式并具名
`custom` 设为 `true` 后，`title`、`tags`、`negative_tags` 才会生效。灵感模式下这几个字段会被直接丢弃。
### 生成纯音乐
`instrumental` 设为 `true` 输出无人声版本，适合做背景乐或伴奏。
**上传音频并翻唱{Upload and cover}::cURL**
```
curl -X POST https://api.oairoute.com/v1/music/generations/uploadCover \
  -H 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
    "model": "suno",
    "audio_url": "https://your-bucket.s3.amazonaws.com/humming.mp3",
    "custom": true,
    "prompt": "[Verse]\n哼出来的旋律",
    "tags": "acoustic, warm",
    "version": "v6"
  }'
```
**上传音频并翻唱{Upload and cover}::Python**
```
import requests
res = requests.post(
    "https://api.oairoute.com/v1/music/generations/uploadCover",
    headers={
        "Authorization": "Bearer YOUR_OAIRoute_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "suno",
        "audio_url": "https://your-bucket.s3.amazonaws.com/humming.mp3",
        "custom": True,
        "prompt": "[Verse]\n哼出来的旋律",
        "tags": "acoustic, warm",
        "version": "v6",
    },
)
print(res.json()["data"][0]["task_id"])
```
**上传音频并翻唱{Upload and cover}::JavaScript**
```
const url = "https://api.oairoute.com/v1/music/generations/uploadCover";
const options = {
  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/humming.mp3",
    "custom": true,
    "prompt": "[Verse]\n哼出来的旋律",
    "tags": "acoustic, warm",
    "version": "v6"
  }),
};
fetch(url, options)
  .then((res) => res.json())
  .then((json) => console.log(json))
  .catch((err) => console.error(err));
```
**200 上传音频并翻唱{Upload and cover}**
```
{
  "code": 200,
  "data": [
    { "status": "submitted", "task_id": "task_01K8F11M0HP1GJWBJYZMKX1XS1" }
  ]
}
```
**灵感模式{Inspiration mode}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/music/generations/uploadCover' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "suno",
  "audio_url": "https://your-bucket.s3.amazonaws.com/humming.mp3",
  "custom": false,
  "gpt_description": "把这段哼唱改造成轻松的民谣",
  "tags": "folk"
}'
```
**灵感模式{Inspiration mode}::Python**
```
import requests
url = "https://api.oairoute.com/v1/music/generations/uploadCover"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
      "model": "suno",
      "audio_url": "https://your-bucket.s3.amazonaws.com/humming.mp3",
      "custom": false,
      "gpt_description": "把这段哼唱改造成轻松的民谣",
      "tags": "folk"
    }
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**灵感模式{Inspiration mode}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/music/generations/uploadCover", {
  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/humming.mp3",
    "custom": false,
    "gpt_description": "把这段哼唱改造成轻松的民谣",
    "tags": "folk"
  }),
});
console.log(await res.json());
```
**200 灵感模式{Inspiration mode}**
```
{
  "code": 200,
  "data": [
    { "status": "submitted", "task_id": "task_01K8F11M0HP1GJWBJYZMKX1XS1" }
  ]
}
```
**用上传音频做翻唱{Cover from upload}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/music/generations/uploadCover' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "suno",
    "audio_url": "https://example.com/song.mp3",
    "prompt": "改成爵士风格，加入萨克斯和轻柔的鼓",
    "version": "v6"
  }'
```
**用上传音频做翻唱{Cover from upload}::Python**
```
import requests
url = "https://api.oairoute.com/v1/music/generations/uploadCover"
headers = {"Authorization": "Bearer YOUR_OAIRoute_KEY"}
payload = {
    "model": "suno",
    "audio_url": "https://example.com/song.mp3",
    "prompt": "改成爵士风格，加入萨克斯和轻柔的鼓",
    "version": "v6"
  }
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**用上传音频做翻唱{Cover from upload}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/music/generations/uploadCover", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "suno",
    "audio_url": "https://example.com/song.mp3",
    "prompt": "改成爵士风格，加入萨克斯和轻柔的鼓",
    "version": "v6"
  }),
});
console.log(await res.json());
```
**灵感模式重写{Inspiration-mode rewrite}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/music/generations/uploadCover' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "suno",
    "audio_url": "https://example.com/demo.mp3",
    "gpt_description": "温暖的民谣翻唱，木吉他为主，人声清晰",
    "version": "v6"
  }'
```
**灵感模式重写{Inspiration-mode rewrite}::Python**
```
import requests
url = "https://api.oairoute.com/v1/music/generations/uploadCover"
headers = {"Authorization": "Bearer YOUR_OAIRoute_KEY"}
payload = {
    "model": "suno",
    "audio_url": "https://example.com/demo.mp3",
    "gpt_description": "温暖的民谣翻唱，木吉他为主，人声清晰",
    "version": "v6"
  }
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**灵感模式重写{Inspiration-mode rewrite}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/music/generations/uploadCover", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "suno",
    "audio_url": "https://example.com/demo.mp3",
    "gpt_description": "温暖的民谣翻唱，木吉他为主，人声清晰",
    "version": "v6"
  }),
});
console.log(await res.json());
```
**自定义模式并具名{Custom mode with title}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/music/generations/uploadCover' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "suno",
    "audio_url": "https://example.com/song.mp3",
    "custom": true,
    "prompt": "夏末的风穿过长街\n我们并肩走过",
    "title": "夏末",
    "tags": "pop, acoustic, warm",
    "negative_tags": "heavy metal, screaming",
    "version": "v6"
  }'
```
**自定义模式并具名{Custom mode with title}::Python**
```
import requests
url = "https://api.oairoute.com/v1/music/generations/uploadCover"
headers = {"Authorization": "Bearer YOUR_OAIRoute_KEY"}
payload = {
    "model": "suno",
    "audio_url": "https://example.com/song.mp3",
    "custom": true,
    "prompt": "夏末的风穿过长街\n我们并肩走过",
    "title": "夏末",
    "tags": "pop, acoustic, warm",
    "negative_tags": "heavy metal, screaming",
    "version": "v6"
  }
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**自定义模式并具名{Custom mode with title}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/music/generations/uploadCover", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "suno",
    "audio_url": "https://example.com/song.mp3",
    "custom": true,
    "prompt": "夏末的风穿过长街\n我们并肩走过",
    "title": "夏末",
    "tags": "pop, acoustic, warm",
    "negative_tags": "heavy metal, screaming",
    "version": "v6"
  }),
});
console.log(await res.json());
```
**生成纯音乐{Generate instrumental}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/music/generations/uploadCover' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "suno",
    "audio_url": "https://example.com/song.mp3",
    "prompt": "去掉人声，保留钢琴与弦乐",
    "instrumental": true,
    "version": "v6"
  }'
```
**生成纯音乐{Generate instrumental}::Python**
```
import requests
url = "https://api.oairoute.com/v1/music/generations/uploadCover"
headers = {"Authorization": "Bearer YOUR_OAIRoute_KEY"}
payload = {
    "model": "suno",
    "audio_url": "https://example.com/song.mp3",
    "prompt": "去掉人声，保留钢琴与弦乐",
    "instrumental": true,
    "version": "v6"
  }
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**生成纯音乐{Generate instrumental}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/music/generations/uploadCover", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "suno",
    "audio_url": "https://example.com/song.mp3",
    "prompt": "去掉人声，保留钢琴与弦乐",
    "instrumental": true,
    "version": "v6"
  }),
});
console.log(await res.json());
```
**200 用上传音频做翻唱{Cover from upload}**
```
{
  "code": 200,
  "data": [
    { "status": "submitted", "task_id": "task_01K8F11M0HP1GJWBJYZMKX1XS1" }
  ]
}
```
**200 灵感模式重写{Inspiration-mode rewrite}**
```
{
  "code": 200,
  "data": [
    { "status": "submitted", "task_id": "task_01K8F11M0HP1GJWBJYZMKX1XS1" }
  ]
}
```
**200 自定义模式并具名{Custom mode with title}**
```
{
  "code": 200,
  "data": [
    { "status": "submitted", "task_id": "task_01K8F11M0HP1GJWBJYZMKX1XS1" }
  ]
}
```
**200 生成纯音乐{Generate instrumental}**
```
{
  "code": 200,
  "data": [
    { "status": "submitted", "task_id": "task_01K8F11M0HP1GJWBJYZMKX1XS1" }
  ]
}
```