# 音效生成
> 生成短音效，异步任务
> 支持单次与可循环两种类型
> 可指定调性与速度
`POST /v1/music/generations/sounds`
## 认证
- `Authorization` (string / 必填) — 所有接口均使用 Bearer Token 进行认证。 获取 API Key：[访问控制台](https://api.oairoute.com/keys) 创建。 请求时在请求头中添加： ```http Authorization: Bearer YOUR_OAIRoute_KEY ```
## 请求参数
- `model` (string / 可选) — 音频模型，当前仅支持 `suno`，不传时默认为 `suno`。
- `version` (string / 可选) — 公共版本，取值 `v6`（默认）、`v6-wild`、`v6-mini`。
- `prompt` (string / 必填) — 音效的文本描述。**建议用英文提示词**，效果更好。 缺失时提交阶段返回 400 且不扣费。
- `type` (string / 可选) — 音效类型，默认 `one-shot`。 - `one-shot` 单次播放 - `loop` 可无缝循环
- `bpm` (integer / 可选) — 速度，取值 1 到 300。超出范围在提交阶段直接返回 400。
- `key` (string / 可选) — 调性。**只接受升号写法**，降号（如 `Db`、`Eb`）与 `B#` 会返回 400。 大调 12 个：`C`、`C#`、`D`、`D#`、`E`、`F`、`F#`、`G`、`G#`、`A`、`A#`、`B` 小调 12 个：`Cm`、`C#m`、`Dm`、`D#m`、`Em`、`Fm`、`F#m`、`Gm`、`G#m`、`Am`、`A#m`、`Bm`
- `audio_format` (string / 可选) — 输出音频格式，取值 `mp3`、`m4a`、`wav`。
## 本端点不支持的字段
`custom_model_id`、Max 相关字段、`variety`、目标时长字段都不支持。传了不生效。
## 响应
- `code` (integer) — 响应状态码。
- `data[].status` (string) — 提交后为 `submitted`。
- `data[].task_id` (string) — 任务唯一标识，用于轮询。
轮询时 `status` 可能为 `pending` 或 `processing`，直到 `completed` 或 `failed`。`progress` 是 0 到 100 的整数，变化节点不固定。完成后从 `data.result.music[].audio_url` 取音频地址。失败时 `data.error.message` 给出原因，并自动退回预扣额度。
## 写提示词的经验
音效提示词与音乐提示词写法不同，音效更强调「材质 + 动作 + 空间」：
| 想要的效果 | 提示词写法 |
|---|---|
| 关门声 | `wooden door closing, close mic, indoor` |
| 键盘敲击 | `mechanical keyboard typing, fast, crisp clicks` |
| 雨声循环 | `steady rain on window, no thunder, seamless loop` |
| 通知提示 | `soft digital notification chime, short, pleasant` |
要循环用的音效，记得 `type` 传 `loop`，并在提示词里写 `seamless loop` 或 `continuous`。
> **Note:** 
> `key` 字段容易踩坑。音乐里习惯写 `Db`，但这个接口只认 `C#`。转换时注意：Db = C#，Eb = D#，Gb = F#，Ab = G#，Bb = A#。
## 错误码
错误响应的格式、状态码与重试建议见[错误码与限流](../../../support/errors.html)，常见报错的排查步骤见[常见问题](../../../support/faq.html)。
## 使用示例
提交一个任务并拿到 `task_id`：
> **Note:** 
> 提交成功只表示任务已受理。真正的产物要拿返回的 `task_id` 去任务查询接口轮询，`status` 变成 `completed` 之后才有结果。
**音效生成{Generate sound effect}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/music/generations/sounds' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "suno",
    "prompt": "wooden door closing slowly, close mic, indoor",
    "type": "one-shot",
    "audio_format": "wav"
  }'
```
**音效生成{Generate sound effect}::Python**
```
import requests
res = requests.post(
    "https://api.oairoute.com/v1/music/generations/sounds",
    headers={
        "Authorization": "Bearer YOUR_OAIRoute_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "suno",
        "prompt": "soft digital notification chime, short, pleasant",
        "type": "one-shot",
        "audio_format": "mp3",
    },
)
print(res.json()["data"][0]["task_id"])
```
**音效生成{Generate sound effect}::JavaScript**
```
const url = "https://api.oairoute.com/v1/music/generations/sounds";
const options = {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "suno",
    "prompt": "wooden door closing slowly, close mic, indoor",
    "type": "one-shot",
    "audio_format": "wav"
  }),
};
fetch(url, options)
  .then((res) => res.json())
  .then((json) => console.log(json))
  .catch((err) => console.error(err));
```
**200 音效生成{Generate sound effect}**
```
{
  "code": 200,
  "data": [
    { "status": "submitted", "task_id": "task_01K8C44M0HP1GJWBJYZMKX1XS1" }
  ]
}
```
**循环音效{Looping sound}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/music/generations/sounds' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "suno",
  "prompt": "steady rain on window, no thunder, seamless loop",
  "type": "loop",
  "bpm": 60,
  "key": "Am",
  "audio_format": "m4a"
}'
```
**循环音效{Looping sound}::Python**
```
import requests
url = "https://api.oairoute.com/v1/music/generations/sounds"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
      "model": "suno",
      "prompt": "steady rain on window, no thunder, seamless loop",
      "type": "loop",
      "bpm": 60,
      "key": "Am",
      "audio_format": "m4a"
    }
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**循环音效{Looping sound}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/music/generations/sounds", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "suno",
    "prompt": "steady rain on window, no thunder, seamless loop",
    "type": "loop",
    "bpm": 60,
    "key": "Am",
    "audio_format": "m4a"
  }),
});
console.log(await res.json());
```
**200 循环音效{Looping sound}**
```
{
  "code": 200,
  "data": [
    { "status": "submitted", "task_id": "task_01K8C44M0HP1GJWBJYZMKX1XS1" }
  ]
}
```