文档

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 完整流程

  1. 上传本人清唱录音,提交 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"
  }
}
  1. 轮询该公开任务,在响应 data.data.result.verify_phrase_text 出现后显示给用户。此时任务可能仍为 in_progress,不能等到 completed 才让用户录音。
  2. 用户录制验证短句并上传,提交创建操作:
{
  "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"
  }
}
  1. 轮询创建任务,直到 state=completed 且 data.data.result.voice_ready=true。提交成功不等于验证通过。
  2. 生成歌曲时将已完成的创建任务 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/请求
生成、续写、上传续写、改编、添加人声、添加伴奏、Mashup0.06
替换片段0.025
Sounds0.0125
生成歌词、优化风格、转 WAV0.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_url200 MBmp3、wav、ogg、m4a、flac、aac最多 480 秒
添加人声、添加伴奏 upload_url200 MB同上未明确
Mashup upload_url_list每个 200 MB同上未明确
生成参考图片 image_urls每个 10 MB,最多 5 个jpeg、png、webp、bmp不适用
生成参考视频 video_urls100 MB,最多 1 个mp4、mov、webm最多 241 秒
生成参考 MIDI midi_urls256 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-generateai-music-api/generateV6
suno-v6-extendai-music-api/extendV6
suno-v6-upload-extendai-music-api/upload-and-extend-audioV6
suno-v6-upload-coverai-music-api/upload-and-cover-audioV6
suno-v6-add-vocalsai-music-api/add-vocalsV6
suno-v6-add-instrumentalai-music-api/add-instrumentalV6
suno-v6-mashupai-music-api/mashupV6
suno-v6-soundsai-music-api/soundsV6
suno-v6-mini-generateai-music-api/generateV6_MINI
suno-v6-mini-extendai-music-api/extendV6_MINI
suno-v6-mini-upload-extendai-music-api/upload-and-extend-audioV6_MINI
suno-v6-mini-upload-coverai-music-api/upload-and-cover-audioV6_MINI
suno-v6-mini-add-vocalsai-music-api/add-vocalsV6_MINI
suno-v6-mini-add-instrumentalai-music-api/add-instrumentalV6_MINI
suno-v6-mini-mashupai-music-api/mashupV6_MINI
suno-v6-mini-soundsai-music-api/soundsV6_MINI
suno-v6-wild-generateai-music-api/generateV6_WILD
suno-v6-wild-extendai-music-api/extendV6_WILD
suno-v6-wild-upload-extendai-music-api/upload-and-extend-audioV6_WILD
suno-v6-wild-upload-coverai-music-api/upload-and-cover-audioV6_WILD
suno-v6-wild-add-vocalsai-music-api/add-vocalsV6_WILD
suno-v6-wild-add-instrumentalai-music-api/add-instrumentalV6_WILD
suno-v6-wild-mashupai-music-api/mashupV6_WILD
suno-v6-wild-soundsai-music-api/soundsV6_WILD
suno-lyrics-generateai-music-api/generate-lyrics—
suno-lyrics-alignai-music-api/timeStamped-lyrics—
suno-style-enhanceai-music-api/boost-music-style—
suno-section-replaceai-music-api/replace-section—
suno-stems-separateai-music-api/separate-vocals—
suno-midi-extractai-music-api/generate-midi-from-audio—
suno-audio-export-wavai-music-api/convert-to-wav-format—
suno-artwork-generateai-music-api/cover-generate—
suno-music-video-generateai-music-api/create-music-video—
suno-persona-createai-music-api/generate-persona—
suno-voice-validation-phraseai-music-api/validation-phrase—
suno-voice-validation-phrase-regenerateai-music-api/regenerate-phrase—
suno-voice-createai-music-api/create-voice—
suno-voice-checkai-music-api/check-voice—
suno-audio-recoverai-music-api/suno-recovery-audio—