入口与鉴权

基础地址为 https://top.qingyuntop.ai。创建时使用 Authorization: Bearer YOUR_API_KEY 和 Content-Type: application/json。

入口中转模型请求主体
POST /suno/submit/music自动选择 suno_music，无需填写 model歌曲参数对象
POST /suno/submit/lyrics自动选择 suno_lyrics，无需填写 modelprompt 创作要求
POST /v1/responsesmodel 必须选择 suno_music 或 suno_lyricsinput 与 metadata，详见 Responses

歌曲参数

以下字段与类型来自 SunoAPI 项目的请求 schema，含义结合插件默认值与上游转换逻辑核对。插件原样转发多数业务字段；“能通过 JSON”不表示上游实现了该功能。

字段类型含义与使用条件
continue_atnumber续写起点，单位为秒，可含小数；应在原歌曲有效时长内。插件没有校验时间范围。
continue_clip_idstring原结果中单首歌曲的 id，不是任务 ID。仅在上游可访问原歌曲时用于续写。
gpt_description_promptstring灵感模式的歌曲描述。非空时上游采用灵感模式，并清空 prompt；自定义歌词或续写时省略此字段。
make_instrumentalboolean是否生成纯音乐；插件未收到此字段时补 false。使用 JSON 布尔值 true / false。
mvstring上游歌曲版本字符串；未填或为空时插件补 chirp-v3-0。插件不验证版本枚举，不代表任意版本均可用。
promptstring自定义模式为歌词文本；纯音乐可为空。生成歌词接口中则为创作要求，必须非空。
tagsstring自定义风格描述，如 folk, acoustic guitar；不是固定枚举。
task_idstring续写的原任务标识。上游项目要求它非空；当前插件原样转发，不执行原任务绑定或上游 ID 转换。
titlestring自定义歌曲标题；灵感模式不保证采用。

模式选择与优先级

模式应当填写应当省略
灵感歌曲gpt_description_prompt；make_instrumental=false自定义歌词 prompt
自定义歌词歌曲prompt、title、tags；make_instrumental=falsegpt_description_prompt
灵感纯音乐gpt_description_prompt；make_instrumental=true歌词 prompt
自定义纯音乐title、tags；make_instrumental=true；prompt 可为空gpt_description_prompt
续写原任务与歌曲标识、continue_at、自定义参数gpt_description_prompt

上游项目对非空 gpt_description_prompt 优先采用灵感分支，清空 prompt，并且不采用自定义分支的 title、tags、continue_at 和 continue_clip_id。不要同时填写两个模式的内容再期待两者合并。

mv 不是 model

插件声明的模型只有 suno_music 和 suno_lyrics。music 请求省略 mv 或传入空字符串时，插件补的是 chirp-v3-0，不是 chirp-v4、v4.5 或 v5。

mv 没有插件内的版本枚举与可用性校验，因此旧文档列出的 chirp-v3-5、chirp-v4、chirp-auk、chirp-v5 不能仅凭字段可透传就当作本站当前支持列表。本文示例显式使用插件默认值；若上游已停用它，需要换成当前上游已确认支持的值。不要将 mv 的值填入 Responses 的 model。

歌词参数

字段类型含义与使用条件
promptstring自定义模式为歌词文本；纯音乐可为空。生成歌词接口中则为创作要求，必须非空。

lyrics 只生成文本，不生成配乐或音频。将得到的歌词再次作为 music 的自定义 prompt 提交，才会创建歌曲，这是另一次生成请求。

不应照搬的旧参数

notify_hook、negative_tags、generation_type、vocal_gender、persona、上传和拼接相关字段没有在已核对的上游请求 schema 中形成可用合同，当前文档不承诺这些效果。SunoAPI 格式的 metadata 也不是本插件主动解释的音乐参数容器；只有 Responses 的 metadata 会展开为上游请求体。

生成数量与计费

clips、action 是插件的计量维度，不是用户用来指定生成数量的参数。插件提交估算为 music 两份、lyrics 一份，完成后再依据返回数据提取数量；最终扣费与当前模型定价及账单为准。本目录不固定价格，也不承诺每次一定返回两首。

请求示例见灵感模式、自定义歌词与纯音乐。