Suno music task-proxy protocol

Beginner: this is the site task-proxy protocol

/suno/* is the site task-proxy protocol, not an official Suno public API. Suno's official help center documents product features such as text-to-music and audio uploads, but it does not define this site's submit/music, fetch, action names, or response shape. Available actions and models depend on the configured channels, so confirm the model marketplace. An internal billing or mapping label such as suno_music is not an official Suno model ID.

Minimal music job

The music action can use description mode or custom lyrics. This request makes the title, style, and instrumental switch explicit.

Copycreate=$(curl -sS "$BASE_URL/suno/submit/music" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "gpt_description_prompt":"Warm indie folk about coming home after rain",
    "title":"After the Rain",
    "tags":"indie folk, warm acoustic",
    "make_instrumental":false
  }')

task_id=$(printf '%s' "$create" | jq -r '.data')
test -n "$task_id" && test "$task_id" != "null"

A compatible submit response normally looks like {"code":"success","data":"<task_id>"}. data is the site's public task ID, not an audio URL. Do not log full lyrics, voice assets, or upstream credentials; retain a redacted parameter summary, Request-ID, and task ID.

Poll status and read songs

Copycurl "$BASE_URL/suno/fetch/$task_id" \
  -H "Authorization: Bearer $API_KEY"

The canonical retrieval pattern is GET /suno/fetch/{task_id}. The response envelope contains code and data; the task contains task_id, status, progress, fail_reason, timestamps, and result data. Site states are NOT_START, SUBMITTED, QUEUED, IN_PROGRESS, SUCCESS, and FAILURE; only the last two are terminal. Upstream values such as queueing, processing, completed, and failed are normalized, so clients should implement the site values.

Read audio_url, video_url, image_url, title, and metadata from the songs only after SUCCESS. Preserve fail_reason and stop after FAILURE. Use bounded backoff with jitter and a business deadline instead of fixed high-frequency polling.

Actions, continuation, and upload boundaries

Core proxy actions include music, lyrics, concat, and uploads. Lyrics require prompt; continuation can require task_id, continue_clip_id, and continue_at. The site also exposes /suno/api/* and /v1/suno/* compatibility families with more upstream-specific schemas. A new integration should select one contract unless migration tests prove that both response families are distinguished correctly.

Validate audio format, duration, byte size, channels, and rights before upload. URL uploads require SSRF, cloud-metadata, redirect, and response-size controls. Avoid retaining a complete upload, Base64 representation, and transcoded copy in memory at the same time.

Billing, retry, and output lifetime

One generation can return multiple songs. Reconcile action, model mapping, output count, continuation/upload parameters, task ID, and billing log. A submit timeout is not proof of rejection, so use an application idempotency record. Do not retry parameter, moderation, or rights failures; back off on 429, and put transient 5xx errors under a bounded retry budget.

Audio, video, and cover URLs can expire. Stream successful files into controlled storage and record MIME type, size, hash, duration, source task, authorization, and deletion time. Apply least privilege and explicit retention to user voices, draft lyrics, and unreleased songs.

Expert: production quality and rights governance

Maintain evaluations for prompt adherence, structure, audio quality, vocals, lyric accuracy, truncation, silence, and repetition, and canary every model or channel change. Monitor submit success, queue time, P95 completion, songs per task, failure reasons, duplicate rate, retention failure, and cost per accepted output. Voice cloning, uploaded works, and commercial releases need rights confirmation, complaint handling, deletion, and audit procedures.