Legacy Suno Billing and Migration

Same-key recovery applies to paid or zero-credit tasks.

Legacy Suno overview · Task model

Credits and settlement

OmnAPI deducts the quoted credits atomically when a task is created and records settlement in the task and credit ledger. Eligible failed tasks and cancellations that were safely completed before submission or explicitly confirmed by the Provider are refunded. A post-submit 409 means the task remains active and was not refunded; keep polling it.

Current standard prices are:

Operation	Standard OmnAPI credits
Song generation explicitly using chirp-goose, including Upload + Extend / Cover	25
Song generation with either Pro model, including Vox	28
Vox explicitly using chirp-goose	25
Existing-clip Extend (automatic Concat included) / Cover	25 with chirp-goose or its alias; 28 with either Pro model or its aliases
WAV managed delivery	3
Modern verified public Voice creation	66
Compatibility audio upload	5
Twelve-stem export	140
Named stem extract	56
Compatibility concatenate	5
Lyrics generation	0
Lyrics timeline read	1; 0 for the legacy Suno 55,000 plan

Legacy-customer Suno pricing is universal across every paid Suno operation, including generation, Extend/Cover, WAV, Stems, timeline, and Voice—not only song generation. The legacy Suno 55,000 plan has one explicit exception: timeline reads cost 0 while its other 10/11 pricing remains unchanged. Variable actual settlement and refunds reuse the same frozen customer rate. Treat creditsRequired on the task receipt and creditsCharged/refunded on the terminal task as authoritative. See Credits & Billing.

Error and retry contract

Terminal Cover failures distinguish SUNO_COVER_SOURCE_NOT_PERMITTED from temporary throttling. A disallowed source or SUNO_SOURCE_CLIP_NOT_FOUND requires a corrected or different source, not repeated submissions of the same song. For SUNO_VOICE_VERIFICATION_AUDIO_REJECTED, request a fresh phrase and record new clear audio; no Voice was created. Follow the terminal Task’s retryable and billing fields, as described in Suno recovery.

Compatibility errors use the OmnAPI envelope:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "title must be a string"
  }
}

HTTP	Typical meaning	Retry guidance
400	Valid JSON but an unsupported operation combination	Correct the request
401	Missing, invalid, disabled, or expired OmnAPI key	Replace or enable the key
402	Insufficient OmnAPI credits; no task was created	Add credits, then retry the unchanged request with the same idempotency key
403	API-key scope or IP policy rejected the request	Correct the key scope or IP policy
404	Referenced target does not exist or lacks current-customer creation provenance	Do not blind-retry or probe other customer resources
406	Stems/WAV source exists but is not complete	Wait for the source task to complete, then retry the unchanged request and key
409	Key/body mismatch, concurrent request, or a task was already created	Different body: use a new key. No taskId: back off and retry the same key; if it remains unbound for 15 minutes, contact support rather than changing keys. With taskId: poll that task and do not resubmit
422	Legacy DTO type, length, enum, or required-field failure	Correct the request
429	Request limit reached	Back off using the response headers
502	Task completed without the required compatibility resource	Read task details before deciding to retry
503	Service capacity is temporarily unavailable before execution	Back off with the same host, route, body, and idempotency key; if the error includes a task ID, poll it instead of resubmitting
504	Compatibility wait expired after a task was created	Poll the pollUrl. For a write request, retry only the original host and route with the same key; a same-key replay returns 409 with the original taskId. The timeline GET has no idempotency key and should use its returned task recovery details
5xx	Service failure	Before task creation, retry with backoff and the same key. If details contain taskId, poll it and never switch keys

For the seven write routes, retry the original request with the same key. A response with a task ID means you should poll that task, including when the synchronous wait returns 500, 502, or 504. Without a task ID, use bounded backoff with the same key; contact support if the conflict persists. The service can recover abandoned submissions automatically. Never switch keys to bypass a conflict.

For multi-stage operations, a same-key recovery can identify the latest task for that operation. Keep the original request and all returned receipts.

There is no shared idempotency namespace across the compatibility API and the modern API. After an uncertain write, poll the returned task details or replay the exact original host, path, key, and body. Never fail over an individual in-flight write between surfaces; move only cohorts whose prior writes are known to be settled or absent.

Deliberate differences

These differences are part of the public contract and will not be changed to copy unsafe or incompatible legacy behavior.

Area	Historical client expectation	OmnAPI compatibility behavior
Credential	Retired service key value	OmnAPI key value; either header name is accepted
Authentication errors	Commonly 403	401 for key authentication; 403 only for key scope or IP policy
Insufficient balance	Commonly 403	402
Billing	Package-based deduction after generation	Atomic create-time deduction with terminal settlement and eligible refund
Long-tail status	Frequent legacy feed sync could still leave tasks stale or expire with process-local state	Recoverable task state; keep polling until a confirmed terminal result
Submission acknowledgement loss	A process retry could repeat a non-idempotent Suno write	Automatic replay stops at the durable submission boundary; reconcile the original task or wait through the 48-hour observation window plus 24-hour reconciliation grace instead of creating a replacement
Resource access	Some follow-up operations accepted unrelated internal resource IDs	Raw Suno IDs are resolved against resource permission rules; OmnAPI data remains customer-isolated
History	Historical song records	Only OmnAPI task/resource history is queryable
Old resources	A known old clip or Voice ID could be routed by legacy runtime state	Raw Suno clip and Voice IDs are accepted without a matching OmnAPI row; resource compatibility checks still apply
Query provenance	A clip returned by a lookup could later be reused as a source	Only create/upload and other operations that generate a new owned resource — including generative derive, concatenate, edits/remaster, Voice creation, and stems — establish provenance. Query, timeline, WAV, and other read-only/conversion results do not
Model validation	Malformed mv values could be rewritten to fenix	Supported legacy values normalize as documented; malformed values return 422
Model selection	Legacy clients could request several model names	Defaults to v6-mini; use_requested_model: true preserves a supported requested model
Response mv	Suno clip major_model_version	Same exact major-version value; null when unavailable, with no fallback to the request model
Songs pagination	skip could be validated and then ignored	skip is applied so pages do not repeat the same rows
Timeline shape	Some responses included both aligned lines and words	Returns both aligned_lyrics and aligned_words
Continue position	A negative continue_at could pass the old DTO	Values must be finite and >= 0; normalize legacy data before migration
Legacy identity fields	Identity fields could be populated	identity, uid, openid, and comparable compatibility identifiers are empty or redacted
Lyrics timeout	Could return running without a public recovery route	Returns an error with canonical task recovery details
Timeline failure	Could return HTTP 200 with an empty body	Returns a structured error
WAV failure	Could be surfaced as an empty or unavailable URL	A successful response always contains a URL
/api/legacy/info	Package rows and internal legacy data	OmnAPI credit-account view; package rows and key secrets are not recreated
Error body	Historical error shape	OmnAPI { success, error } envelope

Two-phase migration plan

Phase 1 — validate compatibility calls and historical resources

1. Inventory calls to the exact ten covered paths. Root /v1/* paths are not supported.
2. Use https://api.omnapi.com, an OmnAPI API key, and /api/legacy. Both api-key and x-api-key header names are accepted.
3. Add a unique Idempotency-Key to every write request. Persist mid, omnapiTaskId, and pollUrl; taskId is not a canonical poll key.
4. Historical rows are not copied automatically. Raw Suno clip and Voice IDs can be used without importing old history, subject to resource permission checks. Contact support when historical task lists or ownership records need to be restored.
5. A successful lookup does not establish ownership. Historical imports must preserve the correct customer and original creation operation.
6. Validate status codes, response shapes, clip count, usable media URLs, task settlement, and same-key retries for each operation in use.

Phase 2 — modern API migration

1. Move simple/custom music to /api/v1/suno/songs.
2. Move extend/cover to /api/v1/suno/clips/{clipId}/derive.
3. Move timeline and exports to clip resource endpoints.
4. Replace mids lookup with /api/v1/suno/clips?clipIds=...; replace recent compatibility history with task listing.
5. Let modern Extend perform automatic Concat. Keep independent historical Concat calls on the compatibility route until they can be removed.
6. Replace /api/legacy/info reporting with dashboard balance, usage export, and task settlement fields.
7. Remove dependencies on compatibility-only fields, then switch the header to x-api-key and remove /api/legacy code paths.

Rollout and acceptance checks

Before raising traffic, verify all of the following:

• Both generated clip mid values can be looked up and downloaded.
• omnapiTaskId reaches a terminal state and matches the compatibility result.
• Required credits and final charged/refunded credits reconcile.
• Retries with the same idempotency key do not create duplicate tasks, including zero-credit lyrics tasks.
• ids and mids are not mixed in application storage.
• Historical clip derivatives pass permission checks with the intended source IDs.
• Error handling covers 401, 402, 403, 404, 406, 409, 422, 429, 502, 503, and 504.

If a modern integration needs rollback, pause new requests and settle any in-flight writes first. Use the documented OmnAPI compatibility route for subsequent supported operations; never replay an uncertain write across routes.