# 样本转歌曲
> 用一段音频样本扩展成完整歌曲，异步任务
> 源音轨必须来自上传接口
> 用 `start_s` 与 `end_s` 框出采样区间
`POST /v1/music/generations/sample`
## 认证
- `Authorization` (string / 必填) — 所有接口均使用 Bearer Token 进行认证。 获取 API Key：[访问控制台](https://api.oairoute.com/keys) 创建。 请求时在请求头中添加： ```http Authorization: Bearer YOUR_OAIRoute_KEY ```
## 引用源音轨
- `task_id` (string / 必填) — 产出源音轨的那次任务的 ID。**必须是 uploadTask 上传任务**，否则提交期返回 400。
- `audio_index` (integer / 可选) — 引用源任务 `data.result.music[]` 中的第几首，默认 `1`，从 1 开始。一次生成通常 2 首。
## 采样区间
- `start_s` (number / 必填) — 采样起点，单位秒。缺失即 400。
- `end_s` (number / 必填) — 采样终点，单位秒。须满足 `0 ≤ start_s < end_s`，源时长已知时不能越界。
## 生成参数
- `instrumental` (boolean / 可选) — `true` 为纯器乐、无人声，默认 `false`。
- `model` (string / 可选) — 音频模型，默认 `suno`。
- `version` (string / 可选) — 可选 `v6`（默认）、`v6-wild`、`v6-mini`。与 `custom_model_id` 互斥。
- `custom_model_id` (string / 可选) — 自建模型任务返回的完整 UUID，与 `version` 互斥。
- `custom` (boolean / 可选) — `true` 为自定义模式（`prompt` 当歌词）；`false` 为灵感模式（用 `gpt_description`）。不传则后端按内容推断。
- `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`。
- `audio_weight` (number / 可选) — 0.00 到 1.00，仅 `custom=true` 生效。
- `vocal_gender` (string / 可选) — `Male` 或 `Female`，两种模式都生效。
- `variety` (string / 可选) — 风格变化程度：`off`、`normal`、`high`、`extra`、`max`。
- `max_mode` (boolean / 可选) — Max 模式，默认 `false`。要求自定义模式，按普通售价 2 倍计费。
- `audio_format` (string / 可选) — 输出格式 `mp3`、`m4a`、`wav`。本接口无目标时长字段。
## 响应
- `code` (integer) — 响应状态码。
- `data[].status` (string) — 任务状态，提交成功为 `submitted`。
- `data[].task_id` (string) — 任务唯一标识，用于轮询结果。
## 取结果
轮询 `GET /v1/music/tasks/{task_id}`，间隔 3 到 5 秒，直到状态为 `completed` 或 `failed`。
- `status` (string) — 取值 `pending`、`processing`、`completed`、`failed`。
- `progress` (integer) — 0 到 100 的整数，不保证按固定节点变化。
- `result.music[].audio_url` (string) — 完成后从中取生成的音频地址。
- `error.message` (string) — 失败原因。预扣额度自动退回。
## 采样技巧
采样区间决定了模型能听到多少「素材」：
| 采样长度 | 效果 |
|---|---|
| 3 秒以内 | 只能抓到一小段动机，成品与原素材关联很弱 |
| 5 到 15 秒 | 最常用，能抓住旋律与音色特征 |
| 30 秒以上 | 更接近改编，成品会明显带有原曲影子 |
> **Note:** 
> 采样区间是**从上传的源音频里取**，不是从生成结果里取。所以 `task_id` 必须是 uploadTask 的产物。
## 错误码
错误响应的格式、状态码与重试建议见[错误码与限流](../../../support/errors.html)，常见报错的排查步骤见[常见问题](../../../support/faq.html)。
## 使用示例
提交一个任务并拿到 `task_id`：
> **Note:** 
> 提交成功只表示任务已受理。真正的产物要拿返回的 `task_id` 去任务查询接口轮询，`status` 变成 `completed` 之后才有结果。
**样本转歌曲{Sample to song}::cURL**
```
curl -X POST https://api.oairoute.com/v1/music/generations/sample \
  -H 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
    "model": "suno",
    "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K",
    "audio_index": 1,
    "start_s": 12,
    "end_s": 24,
    "custom": true,
    "prompt": "[Verse]\n从这里长出一首歌",
    "tags": "pop, bright"
  }'
```
**样本转歌曲{Sample to song}::Python**
```
import requests
res = requests.post(
    "https://api.oairoute.com/v1/music/generations/sample",
    headers={
        "Authorization": "Bearer YOUR_OAIRoute_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "suno",
        "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K",
        "audio_index": 1,
        "start_s": 12,
        "end_s": 24,
        "custom": True,
        "prompt": "[Verse]\n从这里长出一首歌",
        "tags": "pop, bright",
    },
)
print(res.json()["data"][0]["task_id"])
```
**样本转歌曲{Sample to song}::JavaScript**
```
const url = "https://api.oairoute.com/v1/music/generations/sample";
const options = {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "suno",
    "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K",
    "audio_index": 1,
    "start_s": 12,
    "end_s": 24,
    "custom": true,
    "prompt": "[Verse]\n从这里长出一首歌",
    "tags": "pop, bright"
  }),
};
fetch(url, options)
  .then((res) => res.json())
  .then((json) => console.log(json))
  .catch((err) => console.error(err));
```
**200 样本转歌曲{Sample to song}**
```
{
  "code": 200,
  "data": [
    { "status": "submitted", "task_id": "task_01K8E77M0HP1GJWBJYZMKX1XS1" }
  ]
}
```
**纯器乐{Instrumental}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/music/generations/sample' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "suno",
  "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K",
  "start_s": 0,
  "end_s": 8,
  "instrumental": true,
  "tags": "ambient, piano"
}'
```
**纯器乐{Instrumental}::Python**
```
import requests
url = "https://api.oairoute.com/v1/music/generations/sample"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
      "model": "suno",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K",
      "start_s": 0,
      "end_s": 8,
      "instrumental": true,
      "tags": "ambient, piano"
    }
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**纯器乐{Instrumental}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/music/generations/sample", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "suno",
    "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K",
    "start_s": 0,
    "end_s": 8,
    "instrumental": true,
    "tags": "ambient, piano"
  }),
});
console.log(await res.json());
```
**200 纯器乐{Instrumental}**
```
{
  "code": 200,
  "data": [
    { "status": "submitted", "task_id": "task_01K8E77M0HP1GJWBJYZMKX1XS1" }
  ]
}
```