音效生成
- 生成短音效，异步任务
- 支持单次与可循环两种类型
- 可指定调性与速度
认证
All endpoints authenticate with a Bearer token.
Get an API key: open the console and create one.
Add it to the request header:
Authorization: Bearer YOUR_OAIRoute_KEY请求参数
音频模型，当前仅支持 suno，不传时默认为 suno。
公共版本，取值 v6（默认）、v6-wild、v6-mini。
音效的文本描述。建议用英文提示词，效果更好。
缺失时提交阶段返回 400 且不扣费。
音效类型，默认 one-shot。
one-shot单次播放loop可无缝循环
速度，取值 1 到 300。超出范围在提交阶段直接返回 400。
调性。只接受升号写法，降号（如 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
输出音频格式，取值 mp3、m4a、wav。
The audio model, currently only suno; defaults to suno.
The public version: v6 (default), v6-wild, or v6-mini.
A text description of the sound effect. English prompts work better.
Missing returns a 400 at submission with no charge.
The sound effect type; defaults to one-shot.
one-shotplays oncelooploops seamlessly
Tempo, from 1 to 300. Out of range returns a 400 straight away at submission.
The key. Only sharp spellings are accepted; flats (such as Db or Eb) and B# return a 400.
12 major keys: C, C#, D, D#, E, F, F#, G, G#, A, A#, B
12 minor keys: Cm, C#m, Dm, D#m, Em, Fm, F#m, Gm, G#m, Am, A#m, Bm
Output audio format: mp3, m4a, or wav.
本端点不支持的字段
custom_model_id、Max 相关字段、variety、目标时长字段都不支持。传了不生效。
custom_model_id, the Max-related fields, variety, and the target duration fields are all unsupported. Passing them has no effect.
响应
响应状态码。
提交后为 submitted。
任务唯一标识，用于轮询。
轮询时 status 可能为 pending 或 processing，直到 completed 或 failed。progress 是 0 到 100 的整数，变化节点不固定。完成后从 data.result.music[].audio_url 取音频地址。失败时 data.error.message 给出原因，并自动退回预扣额度。
The response status code.
submitted after submission.
The unique task identifier, for polling.
During polling status may be pending or processing, until completed or failed. progress is an integer from 0 to 100 and isn't guaranteed to change on fixed steps. On completion, take the audio URL from data.result.music[].audio_url. On failure, data.error.message gives the reason and the held balance is refunded automatically.
写提示词的经验
音效提示词与音乐提示词写法不同，音效更强调「材质 + 动作 + 空间」：
| 想要的效果 | 提示词写法 |
|---|---|
| 关门声 | 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。
key 字段容易踩坑。音乐里习惯写 Db，但这个接口只认 C#。转换时注意：Db = C#，Eb = D#，Gb = F#，Ab = G#，Bb = A#。
Sound effect prompts differ from music prompts; sound effects favour "material + action + space":
| Desired effect | Prompt phrasing |
|---|---|
| Door closing | wooden door closing, close mic, indoor |
| Keyboard typing | mechanical keyboard typing, fast, crisp clicks |
| Rain loop | steady rain on window, no thunder, seamless loop |
| Notification | soft digital notification chime, short, pleasant |
For a looping sound effect remember to pass type: loop and write seamless loop or continuous in the prompt.
The key field is easy to trip over. Music notation habits make people write Db, but this endpoint only accepts C#. When converting: Db = C#, Eb = D#, Gb = F#, Ab = G#, Bb = A#.
错误码
For error response formats, status codes, and retry guidance see Error codes and rate limits; for troubleshooting steps on common errors see the FAQ.
使用示例
提交一个任务并拿到 task_id：
提交成功只表示任务已受理。真正的产物要拿返回的 task_id 去任务查询接口轮询，status 变成 completed 之后才有结果。
Submit a task and get a task_id:
A successful submission only means the task was accepted. To get the actual output, poll the task query endpoint with the returned task_id; results appear only after status becomes completed.