文档
Suno 音乐子功能与 Voice 工作流
更新于 2026-11-16
调用方式与可用性
所有子功能使用 POST /v1/audios/tasks,随后使用 GET /v1/tasks/{task_id} 查询本站任务。API Base URL 为 https://api.rokoapi.com。
本文描述 Kie Suno 子功能适配协议。部署代码不等于所有功能已发布:请先通过 /v1/models 确认密钥可调用的模型,再与 /api/catalog/models 按精确模型 ID 合并能力与价格。未发布或未完成定价的子功能不可据本文推断为已上线。
这些子功能使用供应商无关的 suno-{版本}-{功能} 或 suno-{功能} 模型 ID,参数放在 input 对象中。原有 suno-v6、suno-v6-mini、suno-v6-wild 的平铺参数与生成/续写协议保持兼容,不能混用两套请求。
curl https://api.rokoapi.com/v1/audios/tasks \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
-d '{
"model": "suno-v6-generate",
"input": {
"model": "V6",
"custom_mode": true,
"instrumental": false,
"title": "夏日来信",
"style": "轻快流行,原声吉他",
"lyrics": "[Verse]\n阳光落在窗前",
"style_weight": 0,
"variety": 0
}
}'
外层 model 固定功能与音乐版本,并选择计费项目;内层 input.model 可省略,显式提供时必须与公开 ID 对应的 V6、V6_MINI、V6_WILD 一致。不要传外层 action、上游 callBackUrl、费用或未经说明的透传字段。0 与 false 会原样保留。
提交返回公开 task_id;异步队列可能先返回排队确认。下游始终使用本站公开 ID,不使用供应商 ID。幂等、排队和错误规则沿用音频生成任务及统一任务幂等规则。
功能清单
下表第一列为上游操作标识,公开模型 ID 及映射见文末完整表;字段均位于 input 中,版本由公开 ID 固定。完整字段约束可从已发布模型的 generation_config.input_schema 获取。
| 操作标识 | 功能 | 主要输入与前置条件 |
|---|---|---|
generate | 生成歌曲或纯音乐 | model、custom_mode、instrumental;自定义模式还需标题及风格/歌词/排除风格之一 |
extend | 续写歌曲 | 本站 task_id、源曲 audio_id、model;可提供正数 continue_at |
upload-and-extend-audio | 上传音频并续写 | upload_url、model |
upload-and-cover-audio | 改编音频 | model、instrumental;upload_url 或 task_id + audio_id 二选一 |
add-vocals | 给伴奏添加人声 | upload_url、title、negative_tags、style;可附歌词 |
add-instrumental | 给人声添加伴奏 | upload_url、title、negative_tags、tags |
replace-section | 替换局部音乐 | prompt、tags、title、full_lyrics、infill_start_s、infill_end_s;源任务与曲目,或上传 URL 与版本 |
mashup | 融合两段音频 | upload_url_list 恰好 2 个 URL,及 model、style、title |
sounds | 声音与循环素材 | prompt、model;可选 sound_loop、sound_tempo、sound_key |
generate-lyrics | 生成歌词文本 | prompt |
timeStamped-lyrics | 获取时间轴歌词 | 本站 task_id、源曲 audio_id;注意 ID 中的大小写 |
boost-music-style | 优化风格描述 | content |
generate-persona | 创建音乐角色 | 本站 task_id、源曲 audio_id、name、description;可选人声区间 |
separate-vocals | 人声/乐器分轨 | audio_url 或 task_id + audio_id 二选一;type 决定模式 |
generate-midi-from-audio | 转为 MIDI 音符数据 | 已完成分轨的本站 task_id;可选分轨 audio_id |
convert-to-wav-format | 转 WAV | 本站 task_id、源曲或分轨 audio_id |
cover-generate | 生成封面图片 | 本站音乐 task_id,不是音频翻唱 |
create-music-video | 生成音乐展示视频 | 本站 task_id、源曲 audio_id;可选 author、domain_name |
suno-recovery-audio | 恢复原曲链接 | 已完成音乐生成任务的本站 task_id |
validation-phrase | 创建 Voice 验证短句 | voice_url、vocal_start_s、vocal_end_s;可选 language |
create-voice | 提交录音验证并创建歌声 | 验证短句任务的本站 task_id、verify_url |
regenerate-phrase | 重新生成验证短句 | 原验证短句任务的本站 task_id |
check-voice | 查询歌声可用性 | 原验证短句任务的本站 task_id |
共用限制
- 歌曲风格通常最多 1000 字符,歌词最多 5000 字符;具体功能以其字段约束为准。
duration若被该功能支持,范围为 10–360 秒;不能拿任意时长字段绕过校验。style_weight、weirdness_constraint、audio_weight为 0–1;variety为整数 0–4。- 替换片段开始时间不能为负,结束必须晚于开始,片段至少 10 秒。
- Persona 分析片段为 10–30 秒;默认区间为 0–30 秒。
sounds.prompt最多 500 字符,BPM 为整数 1–300。grab_lyrics=true不开放,请单独提交已定价的时间轴歌词任务。- 非自定义生成模式使用风格、歌词或参考附件,总数为 1–10;图片最多 5 个,视频与 MIDI 各最多 1 个。该模式不接受仅在自定义模式有效的时长、权重等参数。
- 上传 URL 必须为供应商可读取的 HTTP(S) 文件地址。文件编码、大小和媒体实际时长仍需满足上游限制,提交校验并不表示已检查远程文件内容。
引用自己的作品
input.task_id 和 input.persona_id 都必须填写当前用户在本站创建的公开任务 ID。系统检查用户归属、渠道与已保存的渠道凭据,再转换为供应商 ID。不能拿旧供应商的 suno-v6 任务直接引用到 Kie 子功能。
audio_id 来自该源任务结果中的曲目/分轨 id,必须属于所引用任务。普通处理操作要求源任务已完成;Voice 验证步骤允许引用正在等待用户录音的验证任务。
同一工作流应配置到同一个 Kie 渠道和凭据;跨渠道、跨账户、源任务尚未提交、曲目不属于源任务都会返回 invalid_source_task。不要让跨渠道重试将原曲或 Voice 当成全局公共资源。
Voice 完整流程
- 上传本人清唱录音,提交
kie-suno-validation-phrase:
{
"model": "kie-suno-validation-phrase",
"input": {
"voice_url": "https://your-storage.example/my-singing.mp3",
"vocal_start_s": 0,
"vocal_end_s": 20,
"language": "zh"
}
}
- 轮询该公开任务,在响应
data.data.result.verify_phrase_text出现后显示给用户。此时任务可能仍为in_progress,不能等到completed才让用户录音。 - 用户录制验证短句并上传,提交创建操作:
{
"model": "kie-suno-create-voice",
"input": {
"task_id": "task_validation_public_id",
"verify_url": "https://your-storage.example/verification.mp3",
"voice_name": "我的歌声",
"singer_skill_level": "beginner"
}
}
- 轮询创建任务,直到
state=completed且data.data.result.voice_ready=true。提交成功不等于验证通过。 - 生成歌曲时将已完成的创建任务 ID 或已验证成功的原短句任务 ID 填入
input.persona_id。本站会选择voice_persona,前端无需保存或传递上游 Voice ID。
验证短句支持 en、zh、es、fr、pt、de、ja、ko、hi、ru。这是验证语言列表,不是全语种演唱质量承诺。Voice 需要本人完成声音匹配验证;Suno 官方要求用户年满 18 岁并处于支持地区。上线前应确认供应商渠道的适用条件。
重新生成短句会更新上游原验证任务;重新生成任务返回短句后,再用原验证任务 ID 提交录音。如果原任务已在本站终止或过期,请重新开始验证流程。不要重用旧短句录音。
查询结果与前端展示
{
"code": "success",
"data": {
"task_id": "task_public_id",
"state": "completed",
"status": "SUCCESS",
"data": {
"task_id": "task_public_id",
"operation": "generate-lyrics",
"result": {
"resultObject": {
"lyricsData": [{ "title": "夏日来信", "text": "[Verse]\n阳光落在窗前" }]
}
}
}
}
}
data.data.result保留各功能的结构化结果:歌词、时间轴、风格文本、MIDI 音符、声音可用状态等。不同功能不共享同一种结果结构。- 音乐曲目通常位于
result.data[];歌词位于result.resultObject.lyricsData[];MIDI 包含乐器及音符数据,不保证提供可下载.mid文件。 - Persona 返回本站公开任务 ID 作为可复用句柄;Voice 返回验证短句与就绪状态。前端不需要上游任务 ID。
check-voice调用成功且isAvailable=false是正常查询结果,不是请求失败。assets是可归档的音频、封面、视频或歌词;纯文本/结构化结果可能没有result_url,不能据此判断任务失败。- 媒体归档和有效期遵循音频任务归档规则。长期使用应及时转存,不要把供应商恢复链接功能当成永久存储承诺。
计费
每个子功能是独立模型与独立任务,按后台发布的 pricing_display.rates 和 unit=request 展示费用。一次请求返回两首歌或多个音轨,不代表按文件数重复收费。分轨的 type 对应 generation_type 定价维度,三个模式可分别定价。
整条创作流程的费用等于其中各操作费用之和。供应商免费不等于本站一定免费,以目录中的执行价格为准;未发布价格的功能不能自动当作免费功能。失败退款、幂等重放和结算复用现有统一任务机制。
本站基础售价
价格按每次请求计费,同一次生成返回多首歌曲不会按歌曲数量重复计费。实际可用性与用户分组价格以模型目录和密钥可调用列表为准。
| 功能 | USD/请求 |
|---|---|
| 生成、续写、上传续写、改编、添加人声、添加伴奏、Mashup | 0.06 |
| 替换片段 | 0.025 |
| Sounds | 0.0125 |
| 生成歌词、优化风格、转 WAV | 0.002 |
| 时间轴歌词 | 0.0025 |
| 人声与伴奏分离 | 0.05 |
| 多轨乐器分离 | 0.25 |
| 高级指定分轨 | 0.10 |
| 音乐展示视频 | 0.01 |
| 封面、Persona、MIDI、Voice 验证短句/创建/重新生成短句/可用性查询 | 免费 |
| 恢复音频 | 暂不开放 |
免费步骤不包含前置付费操作:例如分轨后转 MIDI,MIDI 免费,分轨仍按所选模式收费。前端从 pricing_display 读取当前报价,不应硬编码本表。
输入文件上传校验元数据
前端从 /api/catalog/models 对应模型的 generation_config.upload_constraints 读取约束,键是 input 中的字段名。数组字段的大小、格式和时长限制均针对每个文件。
| 功能/字段 | 大小 | 扩展名 | 时长 |
|---|---|---|---|
分轨 audio_url(三种模式) | 20 MB | 未明确 | 未明确 |
生成参考音频 audio_urls | 每个 500 MB | 未明确 | 6–1800 秒 |
上传续写、上传改编 upload_url | 200 MB | mp3、wav、ogg、m4a、flac、aac | 最多 480 秒 |
添加人声、添加伴奏 upload_url | 200 MB | 同上 | 未明确 |
Mashup upload_url_list | 每个 200 MB | 同上 | 未明确 |
生成参考图片 image_urls | 每个 10 MB,最多 5 个 | jpeg、png、webp、bmp | 不适用 |
生成参考视频 video_urls | 100 MB,最多 1 个 | mp4、mov、webm | 最多 241 秒 |
生成参考 MIDI midi_urls | 256 KB,最多 1 个 | mid、midi | 未明确 |
| Voice 源音频、验证录音;替换片段上传音频 | 未明确 | 未明确 | 未明确 |
参考附件仅适用于 custom_mode=false。MIDI 还要求文件头 4d54686400000006,供应商说明仅支持 V6_WILD,其他版本会切换至 V6_WILD。
元数据结构示例:
{
"audio_url": {
"rules": { "max_size_mb": 20 },
"source_url": "https://docs.kie.ai/suno-api/separate-vocals.md",
"evidence_type": "api_documentation"
}
}
rules 包含已确认的 max_size_mb/max_size_kb、extensions、min_duration_seconds、max_duration_seconds、max_files 或 required_header_hex。when 表示生效条件。上传续写/改编的时长依据与上传控件不同,放在同字段的 duration.max_seconds 中,附独立来源。
200 MB 和相应格式来自供应商网页上传控件,标记为 playground_upload_control;其余明确参数来自 API 文档,标记为 api_documentation。大小保留供应商的 MB/KB 单位,供应商未说明十进制/二进制换算,不声称存在精确字节上限。
字段缺失或空对象表示尚未明确,不表示不限大小,也不表示零。 前端仅对已存在的限制校验,不补全未知格式或时长;格式名称是扩展名列表,不是已确认的 MIME 列表。文件格式仍需检查实际内容,不能只信扩展名。本站 URL 提交校验目前不下载远程文件验证实际大小或时长,前端校验不能替代上游校验。
来源:生成音乐、分轨、上传改编、上传续写、上传控件。核对记录:2026-11-16;依据前次已读取的供应商规范。
2026-11-16:公开模型命名与渠道 58 映射
公开 ID 使用 suno-{version}-{operation};无独立版本的辅助功能使用 suno-{operation}。渠道 58 映射至完整的 ai-music-api/*,不能使用省略前缀的 operationId。统一注册表 constant/suno_models.tsv 由后端和发布脚本共用。
共 38 个启用 ID(8 个操作 × 3 个版本 + 14 个辅助操作),另有 suno-audio-recover 保持禁用。公开 ID 固定版本:缺省 input.model 自动补齐,显式冲突返回 400;MIDI 参考生成须选择 suno-v6-wild-generate,避免上游静默切换版本。辅助操作不虚构版本。
新 ID 沿用原操作已确认的售价、v2 表达式与上传约束;分轨保留三档。旧 kie-suno-* 保留兼容调用和历史任务,新接入使用下表。源任务仍须属于当前用户、同一渠道及凭据。已有 suno-v6 和图片、视频模型保持原契约。
发布脚本现在输出 39 条配置(38 启用、1 禁用),取代前文旧的 23 条数量;运维工具写入完整映射并保留其他渠道模型。
| 公开 ID | 上游 model | 固定 input.model |
|---|---|---|
suno-v6-generate | ai-music-api/generate | V6 |
suno-v6-extend | ai-music-api/extend | V6 |
suno-v6-upload-extend | ai-music-api/upload-and-extend-audio | V6 |
suno-v6-upload-cover | ai-music-api/upload-and-cover-audio | V6 |
suno-v6-add-vocals | ai-music-api/add-vocals | V6 |
suno-v6-add-instrumental | ai-music-api/add-instrumental | V6 |
suno-v6-mashup | ai-music-api/mashup | V6 |
suno-v6-sounds | ai-music-api/sounds | V6 |
suno-v6-mini-generate | ai-music-api/generate | V6_MINI |
suno-v6-mini-extend | ai-music-api/extend | V6_MINI |
suno-v6-mini-upload-extend | ai-music-api/upload-and-extend-audio | V6_MINI |
suno-v6-mini-upload-cover | ai-music-api/upload-and-cover-audio | V6_MINI |
suno-v6-mini-add-vocals | ai-music-api/add-vocals | V6_MINI |
suno-v6-mini-add-instrumental | ai-music-api/add-instrumental | V6_MINI |
suno-v6-mini-mashup | ai-music-api/mashup | V6_MINI |
suno-v6-mini-sounds | ai-music-api/sounds | V6_MINI |
suno-v6-wild-generate | ai-music-api/generate | V6_WILD |
suno-v6-wild-extend | ai-music-api/extend | V6_WILD |
suno-v6-wild-upload-extend | ai-music-api/upload-and-extend-audio | V6_WILD |
suno-v6-wild-upload-cover | ai-music-api/upload-and-cover-audio | V6_WILD |
suno-v6-wild-add-vocals | ai-music-api/add-vocals | V6_WILD |
suno-v6-wild-add-instrumental | ai-music-api/add-instrumental | V6_WILD |
suno-v6-wild-mashup | ai-music-api/mashup | V6_WILD |
suno-v6-wild-sounds | ai-music-api/sounds | V6_WILD |
suno-lyrics-generate | ai-music-api/generate-lyrics | — |
suno-lyrics-align | ai-music-api/timeStamped-lyrics | — |
suno-style-enhance | ai-music-api/boost-music-style | — |
suno-section-replace | ai-music-api/replace-section | — |
suno-stems-separate | ai-music-api/separate-vocals | — |
suno-midi-extract | ai-music-api/generate-midi-from-audio | — |
suno-audio-export-wav | ai-music-api/convert-to-wav-format | — |
suno-artwork-generate | ai-music-api/cover-generate | — |
suno-music-video-generate | ai-music-api/create-music-video | — |
suno-persona-create | ai-music-api/generate-persona | — |
suno-voice-validation-phrase | ai-music-api/validation-phrase | — |
suno-voice-validation-phrase-regenerate | ai-music-api/regenerate-phrase | — |
suno-voice-create | ai-music-api/create-voice | — |
suno-voice-check | ai-music-api/check-voice | — |
suno-audio-recover | ai-music-api/suno-recovery-audio | — |