Suno API Final / Pure HTTP Rewrite

This build keeps the validated HTTP runtime, the production pure-HTTP stems routes, and the fixed direct-HTTP Studio adapters from report §25.10. Chrome/CDP is not part of their normal execution path.

Available endpoints

• GET /api/get_limit — read credits / quota
• GET /api/workspaces — list workspaces (?show_trashed=true|1 supported)
• POST /api/create_precheck — run /api/c/check and, when challenge is required, solve Turnstile before create
• POST /api/generate — prompt-mode create
• POST /api/custom_generate — custom-mode create + wait; clients handle MP3/WAV download separately
• POST /api/cover_generate — cover-mode create from an existing clip
• POST /api/extend_audio — Remix / extend from an existing clip
• POST /api/mashup_generate — combine exactly two existing clips through Suno Mashup
• POST /api/song_auto_stems_download — locate a song by clip ID, extract Auto split stems, and download a verified ZIP
• POST /api/studio_multitrack — resolve a studio_export clip ID to the exact Studio project and download a verified Multitrack WAV ZIP
• POST /api/studio/multitrack — render captured Studio state, reuse by request fingerprint, and atomically validate a Multitrack WAV ZIP
• POST /api/studio/export — Full Song or Selected Time Range render to a Suno Library Clip
• POST /api/studio/generate — paid Instrument/Cover create with three gates, durable idempotency, credit ledger, and poll-only recovery
• GET|POST /api/studio/projects — Studio project list/create/read/save and version routes
• GET|POST /api/studio/media/:clipId — read-only waveform, downbeats, MIDI, aligned lyrics, novelty, stems, and project association
• GET /api/studio/unverified_actions — list P2 writes that remain disabled or catalog-only
• POST /api/concat — build a Studio timeline from ordered clip ids and render a merged full-length clip
• GET /api/get?ids=a,b,c — fetch clips by ids
• POST /api/feed_by_ids — fetch clips by ids with JSON body
• GET|POST /api/archive_account — archive the authenticated account library; GET returns read-only persisted status for one output directory

Studio concat payload

{
  "title": "My merged song",
  "wait_audio": true,
  "clips": [
    { "clip_id": "clip-id-1", "duration": 6, "order": 0 },
    { "clip_id": "clip-id-2", "duration": 6, "order": 1 },
    { "clip_id": "clip-id-3", "duration": 6, "order": 2 }
  ]
}

If duration is omitted, the server will fetch each clip and try to infer it from upstream metadata before building the Studio timeline.

Current verified behavior

• Create currently posts upstream to https://studio-api-prod.suno.com/api/generate/v2-web/
• Polling / clip reads currently use /api/feed/v3
• This runtime now treats /api/c/check as the explicit first step of create: precheck first, then branch by required
• If required: false, runtime proceeds directly to upstream POST /api/generate/v2-web/
• If required: true, runtime enters the captcha branch first, solves Turnstile through 2Captcha, and only then continues create
• For this runtime, required: true should be interpreted as a challenge branch, not automatically as cookie invalidation or a broken create endpoint
• Default hot-song output roots are repository-local output/hot-songs and output/hot-songs-fallback; override them with SUNO_HOT_SONG_OUTPUT_DIR and SUNO_HOT_SONG_OUTPUT_FALLBACK_DIR
• Default output timestamp timezone is Asia/Shanghai unless SUNO_OUTPUT_TIMEZONE is overridden
• custom_generate and generate use a longer route timeout to stay aligned with the internal wait/poll path
• Current OpenCLI/browser probe confirms the V6 model family: chirp-hawk (V6), chirp-hawk-wild (V6 Wild), and chirp-goose (V6 Mini)
• Legacy V5 identifiers (v5, v5.5, chirp-crow, chirp-fenix) normalize to chirp-hawk before submission
• Recent browser evidence suggests a short captcha trust window inside the same browser session: after one successful manual image-captcha solve, later creates could still succeed with token = null, including after page refresh and a new create window
• /api/custom_generate now stops after create + wait and returns clip metadata; download/落盘 failures should be handled by the caller instead of aborting the create request
• /api/cover_generate accepts cover_clip_id plus optional persona / workspace arguments and maps the Suno Cover path into the current HTTP runtime
• /api/extend_audio accepts audio_id and continue_at and maps the Suno Remix/extend path into the current HTTP runtime
• /api/mashup_generate accepts exactly two IDs in mashup_clip_ids and maps the browser-verified task=mashup_condition contract into the current HTTP runtime
• /api/song_auto_stems_download accepts clip_id and stem_format (wav or mp3); it discovers or creates a stem bank, renders through HTTP, validates the ZIP, repairs the manifest when needed, and reuses a verified archive keyed only by clip ID and format
• /api/studio_multitrack accepts a completed studio_export clip ID, resolves studio_project_id, reads the exact project state and renders through HTTP, validates every WAV header, records SHA256, and reuses the archive by clip ID
• /api/studio/multitrack is the direct state-based path: it derives bounds, locks by request fingerprint, reuses verified output, and otherwise runs SHA-256, unzip -tq, WAV counting, and representative-WAV ffprobe
• /api/studio/export returns a Library Clip ID and polls /api/feed/v3; Full Song and Selected Time Range do not directly download a local file
• /api/studio/generate is off by default and requires the paid server gate, request confirmation, and a matching Studio token; retries never recreate an ambiguous or already submitted job
• Workspace Project IDs and Studio Project IDs are separate public fields; the save-project adapter forces the URL Studio ID into Suno's wire field named project_id
• Revision clone and archive/unarchive/bookmark/metadata writes are disabled unless the separate unverified-write gate is explicitly enabled; editor P2 writes are not forwarded
• Keep a stems ZIP after first download: Auto split was observed to cost 50 credits, while verified local reuse does not click Extract again
• Same-clip requests use a filesystem lock; unrelated Song/Studio clips, Create, polling, and ordinary downloads can run concurrently
• If a long --via-local-api account archive loses its caller connection, the CLI monitors the same output directory's persisted run status and returns that run's final result without resubmitting
• Detailed Studio references: docs/SUNO_STUDIO_FEATURE_GUIDE_2026-08-08.md and docs/SUNO_STUDIO_OPERATIONS_RUNBOOK_2026-08-08.md