{
  "instrumental": false,
  "lyrics": "[Chorus] 灯火更亮，我们继续向前",
  "prompt": "[Verse] 霓虹雨下城市低鸣",
  "style": "Cinematic",
  "title": "Dark Reprise",
  "uploadUrl": "https://storage.example.com/upload",
  "model": "V6",
  "callBackUrl": "https://example.com/callback",
  "vocalGender": "m",
  "styleWeight": 0.61,
  "weirdnessConstraint": 0.72,
  "audioWeight": 0.65,
  "variety": 1
}

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

POST

api

generate

upload-cover

{
  "instrumental": false,
  "lyrics": "[Chorus] 灯火更亮，我们继续向前",
  "prompt": "[Verse] 霓虹雨下城市低鸣",
  "style": "Cinematic",
  "title": "Dark Reprise",
  "uploadUrl": "https://storage.example.com/upload",
  "model": "V6",
  "callBackUrl": "https://example.com/callback",
  "vocalGender": "m",
  "styleWeight": 0.61,
  "weirdnessConstraint": 0.72,
  "audioWeight": 0.65,
  "variety": 1
}

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

模型版本

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

参数使用指南

本接口固定为自定义参数，简单模式不可用。
源音频输入方式二选一：提供 uploadUrl，或同时提供 taskId 和 audioId 以使用已有生成音频。两种方式不可同时使用。
lyrics、prompt、style、title 均为选填。
instrumental（boolean，可选）：决定是否生成纯音乐，默认值为 false
- 如果 instrumental 为 true：生成纯音乐。无需填写 prompt 和 lyrics
- 如果 instrumental 为 false：优先使用 lyrics 作为歌词；未传 lyrics 时使用 prompt。二者均为选填
prompt 为选填，按歌词语义使用。同时传入 lyrics 时，优先使用 lyrics，prompt 不再作为歌词
lyrics 为选填，优先于 prompt 作为歌词。未传 lyrics 时使用 prompt 作为歌词
字符限制（基于模型）：
- V4 模型（已废弃）：prompt 最多 3000 字符，style 最多 200 字符，title 最多 80 字符
- V4_5、V4_5PLUS、V5、V5_5 和 V4_5ALL 模型（已废弃）：prompt 最多 5000 字符，style 最多 1000 字符；V4_5ALL 的 title 最多 80 字符，其余最多 100 字符
- V6、V6_WILD 和 V6_MINI 模型：prompt 与 lyrics 最多 5000 字符，style 最多 1000 字符，title 最多 80 字符
model（string，必填）：V6、V6_WILD、V6_MINI。已废弃：V4_5ALL、V4、V4_5、V4_5PLUS、V5、V5_5。
uploadUrl 为源音频 URL，使用上传音频时必填。请确保上传的音频长度不超过 8 分钟。
taskId 为已有音乐生成任务的任务 ID，audioId 为已有音乐 ID。使用已有生成音频时必须同时提供这两个参数。

可选参数

以下字段为可选控制项：

lyrics（string）：翻唱所用歌词。选填。优先于 prompt；未传时使用 prompt 作为歌词。V6、V6_WILD、V6_MINI 最多 5000 字符。
vocalGender（string）：偏好人声性别。允许值：m（男）、f（女）
styleWeight（number）：风格贴合权重，范围 0–1（建议保留两位小数）
weirdnessConstraint（number）：创造性/新颖度约束，范围 0–1（建议保留两位小数）
audioWeight（number）：音频一致性相对权重，范围 0–1（建议保留两位小数）
variety（integer）：生成结果的多样性。范围 0–4 的整数，默认 1。0 关，1 普通（默认），2 高，3 额外，4 最大。
personaId（string）：应用到生成音乐的 Persona ID 或 Suno Voice 生成的 voiceId。如果使用 Voice 生成的 ID，personaModel 必须设置为 voice_persona。
personaModel（string）：Persona 类型。生成 Persona 接口返回的 ID 使用 style_persona，Suno Voice 生成的 ID 使用 voice_persona。

{
  "instrumental": false,
  "lyrics": "[Chorus] 灯火更亮，我们继续向前",
  "prompt": "[Verse] 霓虹雨下城市低鸣",
  "style": "Cinematic",
  "title": "Dark Reprise",
  "uploadUrl": "https://storage.example.com/upload",
  "model": "V6",
  "callBackUrl": "https://example.com/callback",
  "vocalGender": "m",
  "styleWeight": 0.61,
  "weirdnessConstraint": 0.72,
  "audioWeight": 0.65,
  "variety": 1
}

{
  "instrumental": false,
  "taskId": "5c79****be8e",
  "audioId": "e231****-****-****-****-****8cadc7dc",
  "model": "V6",
  "callBackUrl": "https://example.com/callback"
}

开发者注意事项

新用户推荐设置：将 instrumental 设为 false，只提供 uploadUrl。这是最简单的配置，可以快速测试API并体验结果。
生成的文件将保留15天后删除
本接口固定为自定义参数。请在 uploadUrl 或 taskId + audioId 两种源音频方式中选择一种，不要同时提供两种方式
请注意 prompt、lyrics、style 和 title 的字符长度限制，确保成功处理
回调过程有三个阶段：text（文本生成完成）、first（第一首完成）、complete（全部完成）
您可以使用音乐生成详情查询接口主动检查任务状态，而不必等待回调
使用上传方式时，uploadUrl 参数用于指定音频文件的 URL；请提供有效的 URL。

授权

Authorization

string

header

必填

🔑 API 认证说明

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

获取 API Key

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

使用方式

在请求头中添加：

Authorization: Bearer YOUR_API_KEY

⚠️ 注意：

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

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

请求体

application/json

使用上传音频进行翻唱
使用已有音频进行翻唱

uploadUrl

string<uri>

必填

要翻唱的源音频 URL。使用上传音频时必填。不可与 taskId 和 audioId 同时使用。

上传音频时长限制：最大上传时长为 8 分钟

示例:

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

instrumental

boolean

必填

决定音频是否为纯音乐（无歌词）。本接口固定为自定义参数，简单模式不可用。

如果为 true：生成纯音乐。无需填写 prompt 和 lyrics。
如果为 false：优先使用 lyrics 作为歌词；未传 lyrics 时使用 prompt。二者均为选填。
style 和 title 在两种情况下均为选填。

示例:

true

model

enum<string>

默认值:V6

必填

AI 模型版本。默认值：V6。

V6：当前标准模型，推荐默认使用。
V6_WILD：当前实验性、创造性更强的模型。
V6_MINI：当前轻量模型。
已废弃：V5_5、V5、V4_5PLUS、V4_5ALL、V4_5、V4。这些值仅为向后兼容保留，新接入请使用 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

翻唱所用歌词。选填。提供后将严格作为歌词使用并在生成的音轨中演唱。若同时传入 lyrics，优先使用 lyrics，prompt 不再作为歌词。不同模型的字符限制：

V4（已废弃）：最多3000字符
V4_5、V4_5PLUS、V5、V5_5 和 V4_5ALL（已废弃）：最多5000字符
V6、V6_WILD 和 V6_MINI：最多5000字符

示例:

"[Verse] 霓虹雨下城市低鸣"

lyrics

string

翻唱所用歌词。选填。优先于 prompt 作为歌词。未传 lyrics 时使用 prompt 作为歌词。

V6、V6_WILD 和 V6_MINI：最多5000字符

示例:

"[Chorus] 灯火更亮，我们继续向前"

style

string

音乐风格或流派，例如"爵士"、"古典"、"电子"。选填。仅提供源音频（uploadUrl）即可生成。不同模型的字符限制：

V4（已废弃）：最大长度为200字符
V4_5、V4_5PLUS、V5、V5_5 和 V4_5ALL（已废弃）：最大长度为1000字符
V6、V6_WILD 和 V6_MINI：最大长度为1000字符

示例:

"古典"

title

string

生成音乐的标题。选填。不同模型的字符限制：

V4 和 V4_5ALL（已废弃）：最大长度80字符
V4_5、V4_5PLUS、V5 和 V5_5（已废弃）：最大长度100字符
V6、V6_WILD 和 V6_MINI：最大长度80字符

示例:

"宁静钢琴冥想"

personaId

string

应用到生成音乐的 Persona ID，可选。你可以传入以下两类 ID：

通过生成 Persona 接口生成的 Persona ID。此时可使用 personaModel: style_persona，或省略 personaModel 使用默认值。
通过 Suno Voice 流程生成的 voiceId。当使用 Voice 生成的 ID 时，必须设置 personaModel: voice_persona。

示例:

"persona_123"

personaModel

enum<string>

默认值:style_persona

使用 personaId 时应用的 Persona 模型类型，可选。

style_persona（默认）：用于生成 Persona 接口返回的 Persona ID。
voice_persona：当 personaId 使用 Suno Voice 生成的 voiceId 时必须选择该值。该选项仅在 V5（已废弃）、V5_5（已废弃）、V6、V6_WILD 和 V6_MINI 模型下可用。

可用选项:

style_persona,

voice_persona

示例:

"style_persona"

negativeTags

string

需要在生成的音频中排除的音乐风格或特征。

可选。用于避免特定风格。
示例："重金属, 强节奏鼓点"

示例:

"重金属, 强节奏鼓点"

vocalGender

enum<string>

偏好人声性别。可选。允许值：'m'（男）、'f'（女）

可用选项:

m,

f

示例:

"m"

styleWeight

number

风格贴合权重。可选。范围：0-1。建议保留两位小数。

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

示例:

0.65

weirdnessConstraint

number

创造性/新颖度约束。可选。范围：0-1。建议保留两位小数。

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

示例:

0.65

audioWeight

number

音频一致性与其他控制项的相对权重。可选。范围：0-1。建议保留两位小数。

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

示例:

0.65

duration

number

时长（秒）。可选。仅在 model 为 V5_5（已废弃）、V6、V6_WILD 或 V6_MINI 时有效。

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

示例:

20

variety

integer

默认值:1

生成结果的多样性。可选。范围 0–4 的整数，默认值为 1。

0：关，完全关闭，严格用同一风格
1：普通，默认值，在稳定性和多样性之间保持平衡
2：高，生成风格差异明显的结果
3：额外，更高程度的变化，鼓励大胆探索
4：最大，最大程度增加多样性

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

示例:

1

回调

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

Lyrics Generation

Generate Sounds

WAV Conversion

Vocal Removal

Music Video Generation

Account Management

文件上传API

上传并翻唱音乐

模型版本

参数使用指南

可选参数

开发者注意事项

授权

🔑 API 认证说明

获取 API Key

使用方式

请求体

回调

请求体

响应

响应

状态码说明

​模型版本

​参数使用指南

​可选参数

​开发者注意事项

授权

🔑 API 认证说明

获取 API Key

使用方式

请求体

回调

请求体

响应

响应

状态码说明

模型版本

参数使用指南

可选参数

开发者注意事项