action 决定操作类型。Project 主键统一使用 id；version_id 表示当前工程版本，所有修改和导出操作都必须提交最新版本，避免并发覆盖。
操作概览
异步操作立即返回
task_id。使用免费的 /suno/tasks 接口轮询，或传入 callback_url 接收终态结果。
创建和读取
Idempotency-Key Header。创建成功后响应中的 data.id 是 Project ID。新建空工程在首次保存前可能没有 version_id。
state。新建空工程返回 {"tracks":[],"timing":{"bps":2}}，可直接用于首次保存。timing.bps 表示每秒拍数，默认 2（120 BPM），必须为正数；片段的 startBeats、endBeats 和 readStartBeats 使用工程拍单位，不能把音频分析中的小节位置直接当成时间轴坐标。
保存完整状态
version_id；首次保存生成版本后，后续保存必须提交最新值。如果版本已变化，接口返回 HTTP 409。此时重新 retrieve，合并修改后再用新的幂等键提交；不要盲目重试旧请求。
上传和添加轨道
response.data.candidate.audio_id 读取音频 ID。再将其加入工程：
timing.bps 把音频时长转换为拍数。每次 save、add_track、commit_candidate 或 remove_track 后，都应使用响应中的新 version_id。
生成和替换
generate_track 为工程区间生成音轨候选；replace_section 返回两个局部替换候选。两个操作都不会自动选择艺术结果。模型必须使用公开名称：chirp-v3-5、chirp-v4、chirp-v4-5、chirp-v4-5-plus、chirp-v5、chirp-v5-5、chirp-v6、chirp-v6-wild 或 chirp-v6-mini；具体操作的可用性仍以任务终态为准，不支持的名称会在提交前返回 400。不会自动改用另一模型。
generate_track 还必须提供 render_audio_id（已完成的工程导出音频）、stem_control_tags 和源音频 source_audio_id。batch_size 为 1–4，默认为 2；start_seconds、end_seconds 是源音频秒数。fixed=true 的替换区间必须短于 26 秒。
选择候选后提交：
start_beats、end_beats。新轨候选应提交到提前保存的空轨道，默认沿用源片段起点，或显式传入无重叠范围；同一轨道上已有片段重叠会返回 400。不要先生成再新建轨道，否则版本变化会使候选过期。
导出完整歌曲
start_beats、end_beats 时，默认导出所有可听片段的最早起点到最晚终点；静音轨道/片段不参与，solo 轨道存在时仅选择 solo 轨道。空工程或无有效可听轨道返回 400。终态结果包含 render_id、audio_id、audio_url 和时长。项目绑定创建时的执行环境，不能跨环境迁移或自动故障切换。
仅可上传或处理您拥有合法使用权的音频。工程 API 当前为 Beta；请持久化重要结果中的最终音频 URL。
轮询与失败恢复
/suno/tasks。Projects 任务以 finished_at 存在且 response.success=true 表示成功；response.success=false 表示失败。提交返回 HTTP 200 或 task_id 只代表已受理，不代表音频完成。
同一个 Idempotency-Key 与相同请求会回读原结果（包括失败），不会自动重新生成或重复扣费。想显式重试一个已失败的操作时，先查询原任务确认失败，再使用新键；不要在原任务仍处理中或结果不确定时重新提交。
错误分类包括 studio_unavailable / studio_model_unavailable（503，暂时无法处理或模型不可用）、studio_model_unsupported（400，模型不支持该操作）、studio_state_invalid（400，工程状态或导出范围无效）、too_many_requests（429）、studio_audio_unavailable（403，引用音频不能用于工程导出）和 content_rejected（403）。保留 trace_id 用于排查。