专业模式生成 API

更新于 2026-09-15 · Suno-API 团队

接口说明

专业模式适合已经准备好歌词、风格和标题，并希望控制演唱声音、风格参考强度和生成随机度的场景。

接口地址: POST /api/music/create/custom

计费: 收费，当前默认 0.6 元/次。每次通常返回 2 首歌曲，实际扣费以后台价格配置为准。

Max Mode / Variety：本接口支持可选参数 max_mode 与 variety（0-4）。开启 max_mode 时本次按 2 倍价格计费（0.6 → 1.2 元/次），variety 不额外计费；两者含义与写法见 新版 API 总览 的「高级参数」一节。

等待时间与超时（重要）：本接口是同步接口，响应返回时才代表订单已被受理并提交生成。实测多数请求 1–3 秒返回，约 10% 超过 30 秒，最长约 230 秒。请把客户端超时设置为 300 秒以上；未收到响应不等于没有生成，超时后请勿立即重试（会重复下单、重复扣费）。 连接中断可稍后用 GET /api/music/songs 确认。详见新版 API 总览的「等待时间与超时设置」。

请求参数

Headers

Body 参数

高级参数说明

声音性别 vocal_gender

• 男声传 m 或 male，女声传 f 或 female。
• 服务端会将 male、female 分别规范化为 m、f。
• 当 instrumental=true 时，不会向生成服务发送声音性别参数。

风格参考度 style_weight

控制生成结果对 style_tags 的参考强度。值越高，生成结果通常越倾向遵循所填写的风格标签。

随机度 weirdness_constraint

控制生成结果的变化和实验性倾向。值越高，结果通常越有变化；值越低，结果通常越稳妥。

两个数值参数的范围均为 0.0 到 1.0，其中 0 是有效的显式值。只有完全不传字段时，才表示不指定该项。

填写时请注意：这两个参数是比例小数，不是百分比整数。推荐参考：0.0 到 0.3 偏保守，0.4 到 0.6 较均衡，0.7 到 1.0 更偏实验性；没有明确偏好时可使用 0.5，也可以直接省略。示例：weirdness_constraint: 0.5，不要填写 50 或 50%。

instrumental=true 时会生成纯音乐，歌词和声音性别不会按人声歌曲方式生效；如需要人声，请传 false 或省略该字段。布尔字段必须使用 JSON 的 true/false，不要使用字符串。

Python 请求示例

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/create/custom',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'model': 'suno-v6',
        'lyrics': '[Verse]\n夜色落在海面上\n晚风轻轻经过窗',
        'style_tags': 'Mandopop, acoustic guitar, warm vocal',
        'song_title': '海边的晚风',
        'vocal_gender': 'male',
        'style_weight': 0.68,
        'weirdness_constraint': 0.32,
    },
    timeout=300,
)
response.raise_for_status()
songs = response.json()

受理回执模式（可选）

本接口同样支持灵感模式生成 API 里的受理回执模式：请求体加 "accept_mode": "async"（或请求头 X-Accept-Mode: async）时，接口立刻返回 202 和受理号， 生成在后台继续，用 GET /api/music/requests/{request_id} 查询进度。

适用于客户端不适合挂长连接、或不想因为超时误判"没有生成"的场景。不带该参数时行为与以前完全一致。

curl -X POST https://www.suno-api.io/api/music/create/custom \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "style_tags": "Mandopop, acoustic guitar, warm vocal",
    "song_title": "海边的晚风",
    "vocal_gender": "male",
    "accept_mode": "async"
  }'

返回结构与轮询方式见灵感模式生成 API 的「受理回执模式」一节。

参数校验

以下情况会返回 HTTP 400，错误响应的 message 会指出无效字段：

• style_weight 或 weirdness_constraint 不是数字。
• 数值小于 0.0 或大于 1.0。
• vocal_gender 不是 m、f、male、female 之一。

文本字段长度上限

以下字段超长同样返回 HTTP 400，且不会进入生成、不会预扣费。计数按 Unicode 字符（一个汉字算 1 个字符），首尾空格也计入：

错误信息形如 style_tags must not exceed 1000 characters; received 2772：第一个词是超限的字段名，末尾是实际字数，拿到 400 直接按这两个数字裁剪即可，不用逐个字段试。通用约定见新版 API 总览的「文本字段长度上限」。

响应结果

接口通常返回包含 2 首歌曲的数组。异步请求初始状态一般为 pending，请保存 song_id，并通过歌曲查询 API获取最终状态和音频地址。歌曲字段同灵感模式生成 API。

兼容字段

新接入请统一使用 snake_case。若同一请求同时传入 snake_case 和 camelCase，snake_case 的值优先。