POST https://api.acedata.cloud/suno/projects 是管理多轨工程的 Beta 接口。通过 action 区分创建、保存、生成候选、提交候选和导出。
retrieve 外,每次操作都需要 Idempotency-Key。相同键和相同请求只回读原结果;相同键配不同请求返回 409。收费生成遇到网络超时或提交结果不确定时,先用原任务 ID 或同一幂等键查询,不能直接换键重发。
标识符和时间单位
start_seconds / end_seconds 是源音频内的秒数;start_beats / end_beats 是工程时间线上的拍数。state.timing.bps 是每秒拍数,默认 2。例如 41 秒的片段从第 0 拍开始,默认终点为第 82 拍。generate_track 的秒数区间用于指定生成参考,不保证候选只有该区间的长度。
操作流程
如果只做局部替换,已有可用源音频即可,不需要先
render;如果源音频已在工程中,也可跳过 upload 和 add_track。render_audio_id 仅是 generate_track 的必填参考。
异步操作提交时先返回 { "task_id": "...", "trace_id": "..." },不表示生成成功。轮询:
finished_at,且其中的 response.success 为 true,才算成功;response.success=false 时读取 response.error。save 虽可能带 task_id,但它在本接口内同步完成。upload、render、generate_track、replace_section 不修改工程版本;save、add_track、commit_candidate、remove_track 成功后应取新 version_id。
请求约定
下列示例串联展示各操作之间的 ID 和版本传递。响应只列出与当前步骤有关的字段;接入时请以当前应用的响应值替换示例 ID。
创建与读取工程
创建工程:create
请求:
读取工程:retrieve
请求:```json
{
“action”: “retrieve”,
“id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”
}
保存工程状态
state.timing.bps 必须为正数,默认 2。state.tracks 是轨道数组;已有音频片段的 clipId 引用音频 ID,startBeats、endBeats、readStartBeats 使用工程拍单位。最安全的编辑方式是读取完整 state,只修改目标轨道或片段,再整体 save。新增空目标轨道至少应有唯一 id、type:"audio"、clips:[];完整的空轨道结构见“生成新音轨”中的示例。不要把音频分析结果中的拍点直接当工程时间线坐标。
首次保存:save
新建工程没有 version_id,第一次保存省略它:
上传音频并添加轨道
上传素材:upload
添加源轨道:add_track
生成新音轨
候选与生成时的工程版本绑定。先保存接收候选的空轨道,再导出当前混音作为生成参考;生成完成后选一个候选提交到该空轨道。预留目标轨道:save
generate_track 的候选与当前工程版本绑定。在上一条 add_track 终态返回的完整 state 上,向 state.tracks 添加以下空轨道,再以 save 保存;其他已有字段原样保留:
导出参考混音:render
成功后从任务终态
response.data.audio_id 取 render_audio_id。
生成候选:generate_track
每次固定按 2 个候选提交。
start_seconds/end_seconds 不是输出时长保证。
采用候选:commit_candidate
生成只产生候选,不会自动放入工程。
commit_candidate 会检查候选仍属于当前版本。局部替换候选只有在实际时长与完整源音频或选中区间可可靠匹配时才能自动提交;不匹配时保留原工程并返回错误,不能靠手动猜测拍数强行拼接。
提交后导出
提交新轨候选后,包含该候选的整曲导出被拒绝。请求与终态:studio_audio_unavailable 时,应保留原工程并检查所引用音频的可用性。
替换已有片段
replace_section 可以直接使用已有的源音频,无须先导出混音。生成只返回候选;提交时选择包含唯一源片段的原轨道。
生成替换候选:replace_section
候选时长不匹配
提交局部替换候选时,track_id 应指向包含唯一源片段的原轨道,并省略 start_beats、end_beats。只有候选时长与完整源音频或所选区间可可靠匹配时,接口才会更新工程。
选择 8 秒区间后,两个候选均为 36 秒,既不等于原音频的 41 秒,也不等于所选 8 秒。提交其中一个候选时返回:
删除轨道
remove_track 需要当前 version_id 和 state.tracks[].id;成功后使用返回的新版本。下面删除无法用于整曲导出的候选轨道,并回读工程状态。
删除后导出
删除该候选轨道后,原源轨道仍在,使用最新版本再次导出成功:audio_url 可用于下载或播放。音频链接可访问,并不能证明其他候选也具有工程导出资格。
错误与恢复
工程和候选与创建它们的应用绑定,请使用原应用访问。请持久化成功导出的最终音频 URL,并保留
trace_id 便于排查。
