总览 - MountSea API

使用 Studio（Song Editor）API 编辑单个 clip，并导出为一首新歌。

基路径：POST /suno/v2/studio/*
异步：均返回 { "taskId": "..." } — 用查询任务状态轮询至 status=success，再从 data 取新 clip
选号：传原曲 clip_id 即可（同账号归属），不要再传原曲 taskId

Studio 能做什么 / 不做什么

用 Studio	请在产品端完成
多项剪辑（裁剪、删段、复制、倒放、淡入淡出、变速…）→ `/studio/edit`	混音台、EQ、插件、MIDI、多轨拼多首歌
单动作快捷接口（`/studio/crop`、`fadeIn` 等）
插入新生成段落（`addSection` → commit）	片头/片尾续写 → 用 `/generate` 的 extend
替换某一段（`/studio/replace`）

Studio 负责「对单个 clip 导出一首新歌」；时间线 / DAW 体验放在前端。

与老接口的关系

能力	Studio	老接口
裁剪 / 淡入淡出 / 倒放	`/studio/*`（`edit_v3_export`）	`/suno/v2/audio/crop\|fade\|reverse`
变速	`/studio/setSpeed`	`/suno/v2/adjustSpeed`
生歌 / 扩展	—	`/suno/v2/generate`

两者可并存。若要 Song Editor 体验与可串联编辑，优先用 Studio。

通用约定（重要）

时间单位是秒，相对当前时间线。
/studio/edit 的 ops 顺序执行。第 N 个 op 的秒数，是做完前 N−1 个之后的时间线，不是原始源曲秒数。
同一用户、同一 clip_id 同时只能有一个进行中的 Studio 任务（约 20 分钟互斥）。上一个需到 success / failed / timeout 再发下一个。
链式编辑：用上一步导出的新 clip_id 作为下一步输入；不要抢跑进行中的任务。
必须等 status=success 再做下一步 Studio（不要用 stream 中间态 clip），否则可能「同账号归属找不到」。
错误文案为英文，便于前端透出或映射。

可选 `beat`（节拍器导出）

多数 Studio 导出接口支持可选 beat 对象。不传则保持旧行为（无节拍器）。

字段	类型	必填	说明
`enabled`	boolean	是	是否在导出时启用节拍网格 + 可听见的节拍器
`bpm`	number	否	目标 BPM（30~480）。仅 `enabled=true` 时有效；不传则沿用工程/源曲 BPM
`time_signature`	string	否	拍号，如 `"4/4"`（默认）。仅 `enabled=true` 时有效

支持接口：/studio/edit、原子精修快捷接口（crop / removeSection / duplicate / reverse / fadeIn / fadeOut / setSpeed），以及加段提交。不适用于 addSection 阶段一与 /studio/replace。

{
  "clip_id": "SOURCE_CLIP_ID",
  "title": "with-metronome",
  "beat": { "enabled": true, "bpm": 132, "time_signature": "4/4" },
  "ops": [{ "op": "fadeOut", "start_s": 80 }]
}

端点一览

批量编辑（多项精修首选）

端点	积分	说明
批量编辑 `POST /studio/edit`	通常 0	1～20 条 ops；不要把 `addSection` / `replace` 写进 `ops`

支持的 op：crop、removeSection、duplicate、split、reverse、fadeIn、fadeOut、setSpeed。

原子快捷接口

端点	积分
裁剪	免费
删除区间	免费
复制区间	免费
倒放	免费
淡入	免费
淡出	免费
变速	免费

生成类（独立入口）

端点	积分
插入段落	≈ 创作
提交插入段落	通常 0
替换段落	同 `replace_section`

加段（两阶段）

阶段一 — 生成候选

调用插入段落，传入 clip_id 与 insert_at_s。轮询至 success。结果为 { clips, studio }（2 个候选 + commit 上下文）。

阶段二 — 提交

调用提交插入段落，传入选定的 candidate_clip_id（可选再传源曲 clip_id 做校验）。服务端反查阶段一 — 不需要 taskId。

情况	建议
第一次尝试	`duration_s=8~12`，`section_beats=64` 或 `128`
候选过长 / commit 失败	换另一个候选；仍失败 → 加大 `section_beats` 重新跑阶段一
`insert_at_s` 太靠边	往中间挪，或改用 generate extend
`STUDIO_ALIGNMENT_CONTENT_TOO_LONG`	换候选，或加大 gap / 缩短歌词

轮询

status	含义
`ready` / `running`	继续等
`stream`	生成类流式中间态；不要立刻串联 Studio
`success`	完成 — 剪辑类 `data` 多为 clip 数组；addSection 为 `{ clips, studio }`
`failed` / `timeout`	看 `failReason` / `failCode`

建议间隔 3～5 秒。加段阶段一可能数分钟；commit 常见数十秒～两分钟。

常见错误

关键词	处理
`ops` 非法 / 区间不合法	检查字段与顺序；注意 `ops[i]` 下标
把 addSection/replace 写进 ops	改走独立接口
Studio edit already in progress	等待结束；前端互斥
`SAME_ACCOUNT_REQUIRED` / owner not found	等源曲 `success` 入库后再编辑
Alignment 相关错误	换候选，或加大 `section_beats` 重跑阶段一

快速示例 — 批量精修

curl -X POST https://api.mountsea.ai/suno/v2/studio/edit \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "clip_id": "SOURCE_CLIP_ID",
    "title": "edit-demo",
    "ops": [
      { "op": "removeSection", "sections": [{ "start_s": 30, "end_s": 33 }], "close_gap": true },
      { "op": "fadeOut", "start_s": 80 }
    ]
  }'

然后：GET /suno/v2/status?taskId=...

​Studio 能做什么 / 不做什么

​与老接口的关系

​通用约定（重要）

​可选 beat（节拍器导出）

​推荐工作流

​端点一览

​批量编辑（多项精修首选）

​原子快捷接口

​生成类（独立入口）

​加段（两阶段）

​轮询

​常见错误

​快速示例 — 批量精修