音乐生成 | ToAPIs Documentation

POST

/v1/music/generations/generation

国内用户请注意： 中国大陆用户请使用 https://toapis.cn 作为接口地址（Base URL）。文档示例中的 https://toapis.com 请替换为 https://toapis.cn。

根据文本描述或自定义歌词生成完整歌曲（每次返回 2 个候选）
异步任务管理，通过任务 ID 查询结果
custom 决定 prompt 的语义：自定义歌词模式 vs 灵感描述模式

Authorizations

Authorizationstring请求头必填

使用 Bearer Token 进行认证

Authorization: Bearer YOUR_API_KEY

Body

modelstring请求体必填

固定为 "suno"

customboolean请求体

模式开关，默认 false

false：灵感模式，gpt_description（或 prompt）描述想要的音乐
true：自定义歌词模式，prompt 作为歌词文本，title/style/negative_tags 生效

gpt_descriptionstring请求体

灵感模式下的音乐描述，如 "一首雨夜咖啡馆的 lo-fi".自定义模式下不用传

promptstring请求体

自定义模式下的歌词文本（支持 [Verse]/[Chorus] 结构标记）

titlestring请求体

歌曲标题，自定义模式生效

stylestring请求体

风格标签，自定义模式生效，如 "dreamy synthwave, female vocal"

negative_tagsstring请求体

需要避免的元素，自定义模式生效

instrumentalboolean请求体

是否生成无人声纯音乐

versionstring请求体

Suno 引擎版本：v6 / v6-wild / v6-mini

max_modeboolean请求体

Max 高质量档，按两倍计费（$0.10/次），需 custom 为 true

persona_idstring请求体

使用已创建的人声角色 ID，与 custom_model_id 互斥

custom_model_idstring请求体

使用自定义训练模型 ID，与 version、persona_id 互斥

可选调优参数

style_weight、weirdness、audio_weight、vocal_gender、auto_lyrics、variety 均为可选，不传使用上游默认值。

Response

task_idstring

任务 ID(tsk_aud_ 前缀），用于查询任务状态

statusstring

初始状态，submitted / queued / in_progress

完成后 result.music[] 返回 2 个候选曲目，各含 audio_url、image_url（封面）、title、tags、lyrics、duration 等字段，媒体 URL 已镜像至本站 CDN。

请求示例

curl --request POST \
  --url https://toapis.com/v1/music/generations/generation \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "suno",
    "gpt_description": "一首雨夜咖啡馆的 lo-fi 爵士",
    "instrumental": false,
    "version": "v6"
  }'

import requests

resp = requests.post(
    "https://toapis.com/v1/music/generations/generation",
    headers={"Authorization": "Bearer <token>"},
    json={
        "model": "suno",
        "custom": True,
        "prompt": "[Verse]\n街灯亮起来\n风吹过站台\n[Chorus]\n我们一起走过的年代",
        "title": "站台",
        "style": "chinese pop ballad",
        "max_mode": True
    }
)
print(resp.json())

const resp = await fetch("https://toapis.com/v1/music/generations/generation", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "suno",
    gpt_description: "dreamy synthwave with female vocals",
    version: "v6-wild"
  })
});
console.log(await resp.json());