{
  "customMode": false,
  "instrumental": false,
  "prompt": "一段慵懒的 lo-fi 节奏并带柔和人声",
  "lyrics": "[Verse] 夜晚城市 灯火辉煌",
  "style": "lo-fi, chill",
  "imageUrls": [
    "https://example.com/reference-image.png"
  ],
  "videoUrls": [
    "https://example.com/reference-video.mp4"
  ],
  "audioUrls": [
    "https://example.com/reference-audio.mp3"
  ],
  "model": "V6",
  "callBackUrl": "https://example.com/callback"
}

{
  "customMode": true,
  "instrumental": false,
  "title": "宁静钢琴冥想",
  "style": "Classical",
  "lyrics": "[Verse] 夜晚城市 灯火辉煌",
  "prompt": "一段平静舒缓的钢琴曲，带有柔和的旋律",
  "negativeTags": "重金属, 快节奏鼓点",
  "vocalGender": "m",
  "styleWeight": 0.65,
  "weirdnessConstraint": 0.65,
  "audioWeight": 0.65,
  "variety": 1,
  "duration": 20,
  "model": "V6",
  "callBackUrl": "https://example.com/callback"
}

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e"
  }
}

POST

api

generate

{
  "customMode": false,
  "instrumental": false,
  "prompt": "一段慵懒的 lo-fi 节奏并带柔和人声",
  "lyrics": "[Verse] 夜晚城市 灯火辉煌",
  "style": "lo-fi, chill",
  "imageUrls": [
    "https://example.com/reference-image.png"
  ],
  "videoUrls": [
    "https://example.com/reference-video.mp4"
  ],
  "audioUrls": [
    "https://example.com/reference-audio.mp3"
  ],
  "model": "V6",
  "callBackUrl": "https://example.com/callback"
}

{
  "customMode": true,
  "instrumental": false,
  "title": "宁静钢琴冥想",
  "style": "Classical",
  "lyrics": "[Verse] 夜晚城市 灯火辉煌",
  "prompt": "一段平静舒缓的钢琴曲，带有柔和的旋律",
  "negativeTags": "重金属, 快节奏鼓点",
  "vocalGender": "m",
  "styleWeight": 0.65,
  "weirdnessConstraint": 0.65,
  "audioWeight": 0.65,
  "variety": 1,
  "duration": 20,
  "model": "V6",
  "callBackUrl": "https://example.com/callback"
}

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e"
  }
}

模型版本

当前模型：V6（默认）、V6_WILD、V6_MINI
已废弃模型：V5_5、V5、V4_5PLUS、V4_5ALL、V4_5、V4
废弃值仅为向后兼容保留，新接入请使用 V6 系列模型。

使用指南

此接口根据您的文本提示创建音乐
每个请求会生成多个变体
您可以通过自定义模式和纯音乐设置来控制细节级别

参数详情

始终必填：customMode、instrumental、model
自定义模式下（customMode: true）:
- title 可选，最多 80 字符。仅此模式可用；customMode 为 false 时不支持
- prompt 可选；提供时将严格作为歌词使用并在生成的音轨中演唱。若同时传入 lyrics，优先使用 lyrics 作为歌词
- style、lyrics、negativeTags 至少提供一项，全部为空时将拒绝生成
- 如果 instrumental: true：生成纯音乐（无歌词）
- 如果 instrumental: false：使用 lyrics（未传则回退到 prompt）作为歌词
- negativeTags、vocalGender、duration 仅此模式可用。customMode 为 false 时请勿传入
- 可选：duration（10–360 秒）、negativeTags（V6 最多 1000 字符）、vocalGender（m / f）、styleWeight、weirdnessConstraint、audioWeight、variety、personaId、personaModel
- 不同模型的字符限制：
  - V4（已废弃）：prompt 3000 字符，style 200 字符
  - V4_5、V4_5PLUS、V4_5ALL、V5、V5_5（已废弃）：prompt 5000 字符，style 1000 字符
  - V6、V6_MINI、V6_WILD：style 1000 字符；lyrics 5000 字符；negativeTags 1000 字符
- title 长度限制：80 字符（所有模型）
非自定义模式下（customMode: false）:
- prompt 可选；作为核心创意，歌词将根据它自动生成（不严格匹配输入），最多 3000 字符
- lyrics 可作为歌词附件，与 prompt 同时使用
- imageUrls、videoUrls、audioUrls、style、lyrics 至少提供一项，全部为空时将拒绝生成
- imageUrls、videoUrls、audioUrls 仅在此模式下有效
- 请勿传入仅自定义模式可用的参数：title、negativeTags、duration、vocalGender、styleWeight、weirdnessConstraint、audioWeight、variety、personaId、personaModel
- 附件总数不超过 10：style + lyrics + imageUrls + videoUrls + audioUrls

可选参数

以下字段为可选控制项：

prompt（string）：描述所需音频内容的提示词。可选。自定义模式下作为歌词；非自定义模式下作为核心创意（最多 3000 字符）。
lyrics（string）：歌词内容。可选。V6 系列最多 5000 字符。自定义模式优先于 prompt 作为歌词；非自定义模式可作为歌词附件与 prompt 同时使用。
imageUrls（array）：图片参考。仅在 customMode 为 false 时有效。最多 5 张，单张不超过 10 MB，支持 jpeg、png、webp、bmp。
videoUrls（array）：视频参考。仅在 customMode 为 false 时有效。最多 1 个，单个不超过 100 MB，时长不超过 241 秒，支持 mp4、mov、webm。
audioUrls（array）：音频参考。仅在 customMode 为 false 时有效。时长需在 6 秒至 30 分钟之间，单个不超过 500 MB。
style（string）：音乐风格规范。字符限制见上方「参数详情」。
title（string）：曲目标题。可选。仅当 customMode 为 true 时可用。最多 80 字符。将显示在播放器界面和文件名中。
negativeTags（string）：从生成音频中排除的音乐风格或特征。仅当 customMode 为 true 时可用。V6、V6_MINI、V6_WILD 最多 1000 字符。
vocalGender（string）：人声性别偏好。m 男声，f 女声。仅当 customMode 为 true 时可用。根据实践，此参数只能加强概率，但不能保证一定遵循男女声的指令。
styleWeight（number）：对指定风格的遵循强度。范围 0–1，保留两位小数。仅在 customMode 为 true 时有效。
weirdnessConstraint（number）：创意/离散程度。范围 0–1，保留两位小数。仅在 customMode 为 true 时有效。
audioWeight（number）：音频要素相对权重。范围 0–1，保留两位小数。仅在 customMode 为 true 时有效。
variety（number）：生成结果的多样性。范围 0–4 的整数，默认 1。仅在 customMode 为 true 时有效。0 off（严格同一风格），1 normal（默认，平衡），2 high（风格差异明显），3 extra（大胆探索），4 max（最大差异）。
personaId（string）：Persona ID 或 Voice ID。可选。要生成 Persona ID，请访问生成 Persona 接口。
personaModel（string）：persona 模型，可选 style_persona 或 voice_persona。仅 V5（已废弃）、V5_5（已废弃）、V6、V6_MINI、V6_WILD 可用。
duration（number）：音频时长，单位为秒。范围 10–360，默认 20。仅当 customMode 为 true 时可用，且仅对 V5_5、V6、V6_MINI、V6_WILD 生效。

{
  "customMode": false,
  "instrumental": false,
  "prompt": "一段慵懒的 lo-fi 节奏并带柔和人声",
  "lyrics": "[Verse] 夜晚城市 灯火辉煌",
  "style": "lo-fi, chill",
  "imageUrls": [
    "https://example.com/reference-image.png"
  ],
  "videoUrls": [
    "https://example.com/reference-video.mp4"
  ],
  "audioUrls": [
    "https://example.com/reference-audio.mp3"
  ],
  "model": "V6",
  "callBackUrl": "https://example.com/callback"
}

{
  "customMode": true,
  "instrumental": false,
  "title": "宁静钢琴冥想",
  "style": "Classical",
  "lyrics": "[Verse] 夜晚城市 灯火辉煌",
  "prompt": "一段平静舒缓的钢琴曲，带有柔和的旋律",
  "negativeTags": "重金属, 快节奏鼓点",
  "vocalGender": "m",
  "styleWeight": 0.65,
  "weirdnessConstraint": 0.65,
  "audioWeight": 0.65,
  "variety": 1,
  "duration": 20,
  "model": "V6",
  "callBackUrl": "https://example.com/callback"
}

开发者注意事项

新用户建议：以 customMode: false 开始使用，更简单
生成的文件将保留14天
回调过程分三个阶段：text（文本生成）、first（第一首完成）、complete（全部完成）

授权

Authorization

string

header

必填

🔑 API 认证说明

所有接口都需要通过 Bearer Token 方式进行认证。

获取 API Key

访问 API Key 管理页面获取您的 API Key

使用方式

在请求头中添加：

Authorization: Bearer YOUR_API_KEY

⚠️ 注意：

请妥善保管您的 API Key，不要泄露给他人

如果怀疑 API Key 泄露，请立即在管理页面重置

请求体

application/json

customMode

boolean

必填

确定是否启用高级参数自定义。

如果为 true：允许详细控制
如果为 false：简化模式

示例:

true

instrumental

boolean

必填

确定音频是否为纯音乐（无歌词）。

在自定义模式（customMode: true）下：
- 如果为 true：生成纯音乐（无歌词）
- 如果为 false：使用 lyrics（未传则回退到 prompt）作为歌词
在非自定义模式（customMode: false）下：
- 如果为 true：生成纯音乐（无歌词）
- 如果为 false：lyrics 可作为歌词附件，可与 prompt 中的音频描述同时使用

示例:

true

model

enum<string>

默认值:V6

必填

用于生成的 AI 模型版本。所有请求都必填。默认值：V6。可用选项：

V6_WILD：突破风格边界，带来更大胆、更独特的音乐表达。
V6_MINI：轻量快速，兼顾音质与效率，灵感创作更简单。
V6：更强的音乐表现力，更自然的人声与丰富细节。推荐默认使用。
V5_5（已废弃）：量身定制的专属模型，贴合您的独特品味。
V5（已废弃）：更卓越的音乐表现力，生成速度更快。
V4_5PLUS（已废弃）：V4.5+ 的音色更丰富，新的创作方式，最长 8 分钟。
V4_5（已废弃）：V4.5 更智能的提示词，更快的生成速度，最长 8 分钟。
V4_5ALL（已废弃）：V4.5ALL 更智能的提示词，更快的生成速度，最长 8 分钟。
V4（已废弃）：V4 改进的人声质量，最长 4 分钟。废弃值仅为向后兼容保留，新接入请使用 V6 系列模型。

可用选项:

V6,

V6_WILD,

V6_MINI,

V5_5,

V5,

V4_5PLUS,

V4_5ALL,

V4_5,

V4

示例:

"V6"

callBackUrl

string<uri>

必填

接收任务完成通知的URL。回调过程有三个阶段：text（文本生成）、first（第一首完成）、complete（全部完成）。注意：某些情况下可能会跳过 text 和 first 阶段，直接返回 complete。

详细的回调格式和实现指南，请参见音乐生成回调
或者，您也可以使用获取音乐生成详情接口来轮询任务状态

示例:

"https://api.example.com/callback"

prompt

string

描述所需音频内容的提示词。可选。

自定义模式（customMode: true）：当提供 prompt 时，提示词将严格作为歌词使用并在生成的音轨中演唱。若同时传入 lyrics，优先使用 lyrics 作为歌词。不同模型的字符限制：
- V4（已废弃）：最多 3000 字符
- V4_5、V4_5PLUS、V4_5ALL、V5、V5_5（已废弃）：最多 5000 字符
非自定义模式（customMode: false）：当提供 prompt 时，提示词作为核心创意，歌词将根据提示词自动生成，不严格匹配输入，最多 3000 字符。生成时无需强制填写 prompt，但非自定义模式下 imageUrls、videoUrls、audioUrls、style、lyrics 至少提供一项；自定义模式下 style、lyrics、negativeTags 至少提供一项。所有相关输入均为空时将拒绝生成。

示例:

"一段平静舒缓的钢琴曲，带有柔和的旋律"

lyrics

string

歌词内容。可选。

V6、V6_MINI、V6_WILD：最多 5000 字符。
自定义模式（customMode: true）时优先使用 lyrics 作为歌词；未传入 lyrics 时使用 prompt 作为歌词。
非自定义模式（customMode: false）时，lyrics 作为歌词附件，可与 prompt 中的音频描述同时使用。

示例:

"[Verse] 夜晚城市灯火辉煌"

imageUrls

string[]

图片参考。仅在 customMode 为 false 时有效。

可选
最多上传 5 张图片；单张图片大小不超过 10 MB
支持 jpeg、png、webp 和 bmp 格式
非自定义模式下，附件总数不超过 10：style + lyrics + imageUrls + videoUrls + audioUrls

Maximum array length: 5

示例:

["https://example.com/reference-image.png"]

videoUrls

string[]

视频参考。仅在 customMode 为 false 时有效。

可选
最多上传 1 个视频文件；单个文件大小不超过 100 MB，时长不超过 241 秒且无最短时长限制
支持 mp4、mov 和 webm 格式

Maximum array length: 1

示例:

["https://example.com/reference-video.mp4"]

audioUrls

string[]

音频参考。仅在 customMode 为 false 时有效。

可选
音频时长需在 6 秒至 30 分钟之间，单个音频文件大小不超过 500 MB

示例:

["https://example.com/reference-audio.mp3"]

style

string

生成音频的音乐风格规范。

不同模型的字符限制：
- V4（已废弃）：最多 200 字符
- V4_5、V4_5PLUS、V4_5ALL、V5、V5_5（已废弃）：最多 1000 字符
- V6、V6_MINI、V6_WILD：最多 1000 字符
常见示例：爵士乐、古典乐、电子乐、流行乐、摇滚乐、嘻哈等。
自定义模式下与 lyrics、negativeTags 至少提供一项；非自定义模式下与 imageUrls、videoUrls、audioUrls、lyrics 至少提供一项。

示例:

"Classical"

title

string

生成音乐曲目的标题。可选。

仅当 customMode 为 true 时可用。customMode 为 false 时不支持该字段。
最多 80 字符。
将显示在播放器界面和文件名中。

Maximum string length: 80

示例:

"宁静钢琴冥想"

negativeTags

string

从生成的音频中排除的音乐风格或特征。可选。

仅当 customMode 为 true 时可用。customMode 为 false 时请勿传入。
V6、V6_MINI、V6_WILD 最多 1000 字符。
自定义模式下与 style、lyrics 至少提供一项。

Maximum string length: 1000

示例:

"重金属, 快节奏鼓点"

vocalGender

enum<string>

人声性别偏好。可选。

仅当 customMode 为 true 时可用。customMode 为 false 时请勿传入。
m 表示男声，f 表示女声。
根据实践，此参数只能加强概率，但不能保证一定遵循男女声的指令。

可用选项:

m,

f

示例:

"m"

styleWeight

number

仅当启用自定义模式（customMode: true）时可用。对指定风格的遵循强度。可选。范围 0–1，保留两位小数。

必填范围: 0 <= x <= 1必须是以下数值的倍数 0.01

示例:

0.65

weirdnessConstraint

number

仅当启用自定义模式（customMode: true）时可用。控制实验性/创意偏离程度。可选。范围 0–1，保留两位小数。

必填范围: 0 <= x <= 1必须是以下数值的倍数 0.01

示例:

0.65

audioWeight

number

仅当启用自定义模式（customMode: true）时可用。音频要素相对权重。可选。范围 0–1，保留两位小数。

无人声时不支持 audioWeight

必填范围: 0 <= x <= 1必须是以下数值的倍数 0.01

示例:

0.65

variety

number

默认值:1

仅当启用自定义模式（customMode: true）时可用。控制生成结果的多样性和风格差异程度。可选。范围 0–4，取整数，默认值为 1。

0：off（exact style），完全关闭，严格用同一风格
1：normal（balanced variety），默认值，在稳定性和多样性之间保持平衡
2：high（distinct styles），生成风格差异明显的结果
3：extra（bold exploration），提供更高程度的变化，鼓励大胆探索不同风格
4：max（unreasonably varied），最大程度增加多样性，生成结果可能具有非常明显的风格差异

必填范围: 0 <= x <= 4必须是以下数值的倍数 1

示例:

1

personaId

string

用于应用于生成音乐的 Persona ID 或 Voice ID。可选。仅在 customMode 为 true 时有效。使用此选项可将特定的 Persona 风格应用于您的音乐生成。

要生成 Persona ID，请使用生成 Persona 端点，基于生成的音乐创建个性化的音乐 Persona。

要生成 Voice ID，请使用生成 Voice 端点。当使用 Voice 生成的 ID 时，必须设置 personaModel: voice_persona。

示例:

"persona_123"

personaModel

enum<string>

默认值:style_persona

persona 模型，可选 style_persona 或 voice_persona。仅 V5（已废弃）、V5_5（已废弃）、V6、V6_MINI、V6_WILD 可用。仅在 customMode 为 true 时有效。

style_persona（默认）：用于生成 Persona 接口返回的 Persona ID。
voice_persona：当 personaId 使用 Suno Voice 生成的 voiceId 时必须选择该值。

可用选项:

style_persona,

voice_persona

示例:

"style_persona"

duration

number

默认值:20

音频时长，单位为秒。可选。

仅当 customMode 为 true 时可用。customMode 为 false 时请勿传入。
范围 10–360 秒，默认 20。
仅当 model 为 V5_5（已废弃）、V6、V6_MINI、V6_WILD 时有效。

必填范围: 10 <= x <= 360

示例:

20

回调

POST

{request.body#/callBackUrl}audioGenerated

请求体

application/json

code

integer

状态码

示例:

200

msg

string

返回消息

示例:

"All generated successfully"

data

object

Show child attributes

响应

200

回调接收成功

响应

请求成功

code

enum<integer>

状态码说明

✅ 200 - 请求成功
⚠️ 400 - 参数错误
⚠️ 401 - 没有访问权限
⚠️ 404 - 请求方式或者路径错误
⚠️ 405 - 调用超过限制
⚠️ 413 - 主题或者prompt过长
⚠️ 429 - 积分不足
⚠️ 430 - 您的调用频率过高。请稍后再试。
⚠️ 455 - 网站维护
❌ 500 - 服务器异常

可用选项:

200,

400,

401,

404,

405,

413,

429,

430,

455,

500

示例:

200

msg

string

当 code != 200 时，展示错误信息

示例:

"success"

data

object

Show child attributes

Generate Music

Suno Voice

Generate Lyrics

Generate Sounds

WAV Conversion

Vocal Removal

Music Video Generation

Account Management

文件上传API

生成音乐

模型版本

使用指南

参数详情

可选参数

开发者注意事项

授权

🔑 API 认证说明

获取 API Key

使用方式

请求体

回调

请求体

响应

响应

状态码说明

​模型版本

​使用指南

​参数详情

​可选参数

​开发者注意事项

授权

🔑 API 认证说明

获取 API Key

使用方式

请求体

回调

请求体

响应

响应

状态码说明

模型版本

使用指南

参数详情

可选参数

开发者注意事项