Overview - MountSea API

Use the Studio (Song Editor) APIs to edit a single clip and export a new song.

Base path: POST /suno/v2/studio/*
Async: every call returns { "taskId": "..." } — poll Get Task Status until status=success, then read the new clip from data
Account: pass the source clip_id only (same-account ownership). Do not pass the original song taskId for routing

What Studio does / does not do

Use Studio for	Prefer elsewhere
Multi-op trims (crop, delete, duplicate, reverse, fades, speed…) via `/studio/edit`	Mixer, EQ, plugins, MIDI, multi-track DAW
Single-action shortcuts (`/studio/crop`, `fadeIn`, …)
Insert a generated section (`addSection` → commit)	Extend song ends → use `/generate` extend
Replace a range (`/studio/replace`)

Studio exports one new clip from one source clip. Build timeline / mixer UI on the client.

vs legacy `/audio/*` endpoints

Capability	Studio	Legacy
Crop / fade / reverse	`/studio/*` (`edit_v3_export`)	`/suno/v2/audio/crop\|fade\|reverse`
Speed	`/studio/setSpeed`	`/suno/v2/adjustSpeed`
Generate / extend	—	`/suno/v2/generate`

Both can coexist. Prefer Studio for Song Editor UX and chained edits.

Critical conventions

Time unit is seconds, relative to the current timeline.
In /studio/edit, ops run in order. Seconds for op N are after ops 1…N−1 have already changed the timeline — not original source seconds.
One in-flight Studio task per user + clip_id (~20 minutes). Wait until success / failed / timeout before the next call.
Chain edits with the previous export’s new clip_id. Never race an unfinished task.
Wait for status=success before the next Studio call (do not use stream clips for Studio — ownership may not be ready).
Error messages are English — show or map them in the product UI.

Optional `beat` (metronome export)

Most Studio export endpoints accept an optional beat object. Omit it for legacy behavior (no metronome).

Field	Type	Required	Description
`enabled`	boolean	Yes	Enable beat grid + audible metronome on export
`bpm`	number	No	Target BPM (30~480). Only when `enabled=true`; omit to keep project/source BPM
`time_signature`	string	No	e.g. `"4/4"` (default). Only when `enabled=true`

Supported on: /studio/edit, atomic trim shortcuts (crop, removeSection, duplicate, reverse, fadeIn, fadeOut, setSpeed), and Add Section Commit. Not used by addSection phase-1 or /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 }]
}

Recommended workflow

generate / existing clip
    │
    ├─ trim / speed / fade ──► POST /studio/edit (or atomic APIs) ──► poll ──► new clip
    │
    ├─ insert generated section ──► addSection ──► preview 2 candidates ──► addSectionCommit
    │
    └─ replace a range ──► /studio/replace (billed like replace_section)

Product tips:

Batch panel “Apply” into one /studio/edit to reduce exports and lock conflicts.
Separate edit vs generate (add section / replace) buttons and show credit cost.
After add-section commit, continue polish using the new clip.

Endpoints

Batch edit (preferred for multiple trims)

Endpoint	Credits	Notes
Batch Edit `POST /studio/edit`	Usually 0	1–20 ops; no `addSection` / `replace` in `ops`

Supported op values: crop, removeSection, duplicate, split, reverse, fadeIn, fadeOut, setSpeed.

Atomic shortcuts

Endpoint	Credits
Crop	Free
Remove Section	Free
Duplicate	Free
Reverse	Free
Fade In	Free
Fade Out	Free
Set Speed	Free

Generate-class (separate)

Endpoint	Credits
Add Section	≈ create
Add Section Commit	Usually 0
Replace	Same as `replace_section`

Add Section (two phases)

Phase 1 — generate candidates

Call Add Section with clip_id + insert_at_s. Poll until success. Result is { clips, studio } (two candidates + commit context).

Phase 2 — commit

Call Add Section Commit with the chosen candidate_clip_id (optional source clip_id for validation). The server reverse-looks up phase 1 — no taskId needed.

Situation	Suggestion
First try	`duration_s=8~12`, `section_beats=64` or `128`
Candidate too long / commit fails	Pick the other candidate; still failing → raise `section_beats` and re-run phase 1
`insert_at_s` too close to edges	Move inward, or use generate extend instead of addSection
`STUDIO_ALIGNMENT_CONTENT_TOO_LONG`	Switch candidate or enlarge gap / shorten lyrics

Polling

status	Meaning
`ready` / `running`	Keep waiting
`stream`	Streaming mid-state for generate-class; do not chain Studio yet
`success`	Done — edit exports are usually clip arrays; addSection is `{ clips, studio }`
`failed` / `timeout`	Read `failReason` / `failCode`

Poll every 3–5s. Phase-1 addSection may take minutes; commit often tens of seconds to ~2 minutes.

Common errors

Keyword	What to do
Invalid `ops` / bad ranges	Check fields and order; note `ops[i]` index
addSection/replace inside `ops`	Use dedicated endpoints
Studio edit already in progress	Wait; debounce UI
`SAME_ACCOUNT_REQUIRED` / owner not found	Wait until source generation is `success`
Alignment errors	Switch candidate or re-run phase 1 with larger `section_beats`

Quick example — batch edit

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 }
    ]
  }'

Then: GET /suno/v2/status?taskId=...

​What Studio does / does not do

​vs legacy /audio/* endpoints

​Critical conventions

​Optional beat (metronome export)

​Recommended workflow

​Endpoints

​Batch edit (preferred for multiple trims)

​Atomic shortcuts

​Generate-class (separate)

​Add Section (two phases)

​Polling

​Common errors

​Quick example — batch edit