Legacy Suno compatibility

Supported compatibility API

This guide documents OmnAPI’s ten Suno compatibility endpoints under /api/legacy and the transition to /api/v1/suno. The retired Suno Cloud service is no longer an execution or rollback destination.

Choose a workflow

Compatibility status

All ten covered routes are implemented. Request names, the main success shapes, real clip IDs, and the compatibility contract’s 200/201 success status rules are preserved. Differences that protect account isolation, use OmnAPI credits, or reflect the OmnAPI task model are listed in Deliberate differences.

Method	Compatibility path	Supported purpose	Modern destination
`POST`	`/api/legacy/generate`	Custom, extend, upload-extend, cover, or Voice music	`POST /api/v1/suno/songs` for roots/uploads; `POST /api/v1/suno/clips/{clipId}/derive` for existing-clip Extend/Cover
`POST`	`/api/legacy/generate-gpt`	Simple prompt-to-song generation	`POST /api/v1/suno/songs` with `mode: "simple"`
`POST`	`/api/legacy/generate/lyric`	Lyrics generation	`POST /api/v1/suno/lyrics`
`POST`	`/api/legacy/concatenate`	Concatenate an existing extended clip	No independent modern endpoint; modern Extend includes automatic Concat
`GET`	`/api/legacy/songs`	Compatibility resource lookup and recent results	Clip lookup or task history, depending on the query
`GET`	`/api/legacy/songs/lyric-stamp`	Aligned lyrics timeline	`GET /api/v1/suno/clips/{clipId}/timeline`
`GET`	`/api/legacy/info`	Compatibility credit-account view	Dashboard and usage export
`POST`	`/api/legacy/upload`	Import a remote MP3 or WAV URL	Combine the source URL with `mode: "upload-extend"` or `mode: "upload-cover"` on `POST /api/v1/suno/songs`
`POST`	`/api/legacy/stems`	Twelve or named stem export	`POST /api/v1/suno/clips/{clipId}/export`
`POST`	`/api/legacy/generate-wav`	WAV export	`POST /api/v1/suno/clips/{clipId}/export` with `format: "wav"`

Every unlisted legacy path is outside this compatibility contract. The old root-level /v1/* routes are not mounted on OmnAPI.

Base URL and authentication

https://api.omnapi.com

The canonical compatibility base path is /api/legacy, for example POST /api/legacy/generate. The previously published /v1/suno-legacy/* namespace and old root paths such as /v1/generate return 404.

Both header names are accepted:

api-key: YOUR_OMNAPI_KEY

x-api-key: YOUR_OMNAPI_KEY

Use an OmnAPI API key created in the dashboard; credentials from the retired service are not accepted. Grant these scopes as needed:

Scope	Used by
`task:create`	The seven `POST` endpoints
`task:read`	`/api/legacy/songs` and `/api/legacy/songs/lyric-stamp`
`usage:read`	`/api/legacy/info`

All seven write routes accept Idempotency-Key, including the zero-credit lyrics task. Reuse the same key only when retrying the same logical request with an unchanged body. Deduplication is scoped to the customer and exact compatibility route; it does not span a different /api/legacy route, a modern /api/v1 route.

curl https://api.omnapi.com/api/legacy/info \
  -H "api-key: $OMNAPI_KEY"

Compatibility responses include:

Deprecation: @1784073600
Link: <https://docs.omnapi.com/legacy/suno/>; rel="deprecation"; type="text/html"

The Deprecation value is an RFC 9745 Structured Field Date: it marks the compatibility surface as deprecated from 2026-07-15T00:00:00Z. It is not the retirement date. If a retirement date is scheduled, the response also carries a Sunset header; treat that value as authoritative.

ID dictionary

Do not treat every field containing “id” as interchangeable.

Field	Meaning	Safe use
`id`	Compatibility resource-row ID in the OmnAPI data store	`/api/legacy/songs?ids=...` for resources created through OmnAPI
`mid`	Real Suno clip ID	Follow-up clip operations and `/api/legacy/songs?mids=...`
`taskId`	Legacy generation-operation identifier when available	Preserve only for old client compatibility; do not use it to poll OmnAPI
`omnapiTaskId`	Stable OmnAPI task UUID added to music responses	`GET /api/v1/tasks/{omnapiTaskId}`
`pollUrl`	Ready-to-use canonical task URL	Poll task state and recover after a wait timeout

Generation endpoints wait for a real music resource. They do not fabricate an id or mid from a task UUID. When a real clip cannot be acknowledged within the compatibility wait window, the request returns an error with task recovery details instead of a placeholder song.

Shared music response

Read Legacy Suno Operation Reference for inputs, examples, and recovery.

Managed audio returns a playback url and top-level urlExpiresAt. Use the URL directly for GET, HEAD, or byte-range playback without an API key on the media request. This also covers retained Twelve and named-stem deliveries. Read the song again to replace an older cached download URL; existing deliveries need no migration or new task. Suno download signatures now default to seven days, bounded by retention; always use the returned expiry for the specific URL.

Existing playback links remain usable during the service’s signing-key rotation grace period. A revoked or expired link requires a fresh song read. Customer access, publication status, and retention checks remain in force.

Modern field and response mapping

Legacy operation or mode	Modern request mapping
GPT generation	Suno songs body: `mode: "simple"`; `gpt_description_prompt` → `prompt`; `make_instrumental` → `instrumental`; effective legacy model → `model`
Custom generation	Suno songs body: `mode: "custom"`; legacy `prompt` → `lyrics` (or modern `prompt`); `title`/`tags` keep their names; effective legacy model → `model`
Voice generation	Suno songs body: `mode: "vox"` plus `voiceId`; copy `prompt`, `title`, and `tags`
Extend or cover of an existing clip	`POST /api/v1/suno/clips/{clipId}/derive` with `action: "extend"` or `action: "cover"`
Upload-extend	For a customer-owned audio URL, use Suno songs body `mode: "upload-extend"` with `audio.url`, plus `prompt`, `title`, `tags`, and `continueAt`
Upload-cover	For a customer-owned audio URL, use Suno songs body `mode: "upload-cover"` with `audio.url`, plus `prompt`, `title`, and `tags`
Lyrics	Suno lyrics body uses `prompt`; omit legacy `lyrics_model` for equivalent single-candidate behavior
Managed M4A or MP3	`POST /api/v1/suno/clips/{clipId}/export` with `format: "m4a"` or `format: "mp3"`; poll the returned Task instead of relying on historical direct media URLs
Stems	Path clip ID = `mid`; stems defaults to Twelve and maps `stem_task=extract` plus any of the 98 native Suno `stem_name` values
WAV	`POST /api/v1/suno/clips/{clipId}/export` with `format: "wav"`

“Effective legacy model” is chirp-goose for ordinary generation and chirp-hawk for Vox unless use_requested_model: true explicitly opts into the supplied supported mv. Vox opt-in accepts all three V6 models and the compatible chirp-crow / chirp-fenix aliases, subject to account permission. Modern requests preserve the selected supported model directly. The effective legacy default chirp-goose costs 25 standard credits; other published models cost 28. suno/chirp-v3-5 is retired for new requests.

Modern write routes return HTTP 200 with a CreateTaskResponse task receipt; poll its taskId. The generic sync route returns SyncTaskResponse with HTTP 200 at terminal state or 202 on timeout. Modern clip reads also return the direct Clip or batch Clip object, without creating a Task or charging credits. They do not return the raw legacy music object. The compatibility API permits some empty required strings because the live DTO did; modern simple/custom routes require meaningful generation text. Normalize empty prompts before phase-two migration.