Suno Song Creation and Derivation

Create songs

Call POST /api/v1/suno/songs when the input is generation text, a reusable public Voice, or caller-owned audio that has not already become a Suno clip. The request creates both a billing/execution Task and a song Generation.

Choose a song mode

Mode	Purpose	Required fields
`simple`	Prompt-only generation	`prompt`
`custom`	Lyrics + style generation	`lyrics` or `prompt`
`vox`	Generate with a reusable public Voice	`voiceId` and generation text
`upload-extend`	Upload customer audio and continue it	`audio.url`; generation fields are optional
`upload-cover`	Upload customer audio and reinterpret it	`audio.url`; generation fields are optional

Standalone audio upload is not part of the public API. The two upload modes perform import and song generation as one billable operation.

Request fields

Field	Type	Applies to	Notes
`mode`	string	all	Required discriminator; unsupported modes are rejected.
`prompt`	string, max 5,000	all	Required by `simple`; can provide generation direction in other modes.
`lyrics`	string, max 5,000	`custom`, `vox`	`custom` requires `lyrics` or `prompt`.
`tags` / `negativeTags`	string, max 1,000	non-simple creative modes	Positive and excluded style hints.
`title`	string, max 100	optional	Output title hint.
`instrumental`	boolean	generation	Do not send string values such as `"false"`.
`model`	enum	all	`chirp-goose`, `chirp-hawk-wild` or `chirp-hawk`; omitted model retains the `chirp-fenix` pricing identity and executes on `chirp-hawk`. Documented legacy aliases remain accepted. Vox uses the current model list and checks the required account permission.
`voiceId`	string	`vox`	Public reusable Voice ID.
`audio.url`	HTTPS URL	upload modes	Must be publicly retrievable and owned/licensed by the caller.
`audio.extensionType`	enum	upload modes	`mp3`, `wav`, `m4a`, `flac`, or `ogg`.
`continueAt`	number ≥ 0	`upload-extend`	Continuation point in seconds.
`continuedAlignedPrompt`	string, max 5,000	`upload-extend`	Optional aligned continuation context.
`config`	object	all	Shared priority, webhook, tags, and metadata. See Task Model.

Generation controls

Field	Type	Notes
`controlSliders.style_weight`	number 0–1	How strongly the style hint biases the model. Higher = stricter adherence to `tags` / `style`.
`controlSliders.audio_weight`	number 0–1	How strongly a supported managed-audio workflow follows the source audio.
`controlSliders.weirdness_constraint`	number 0–1	Diversity dial. Higher = more experimental output.

Values outside the allowed range are rejected with HTTP 400 and VALIDATION_ERROR. error.details.issues[] identifies the nested field, for example body.controlSliders.style_weight.

Requested controls are preserved while OmnAPI waits for compatible generation capacity. If an accepted task is still processing, continue waiting for that task; do not submit duplicates. When a task fails, follow its public retryable field. A temporary capacity failure can be retried later; unsupported control combinations may require different input. Changing an OmnAPI subscription tier is not a remedy for an unsupported generation control.

Examples

For each new logical operation, set and save a fresh REQUEST_KEY once. Reuse it with the exact same route and body only when recovering that operation. Use a different saved key when trying a different example or export format.

export REQUEST_KEY="$(uuidgen)"

    curl -X POST https://api.omnapi.com/api/v1/suno/songs \
      -H "x-api-key: $OMNAPI_KEY" \
      -H "Idempotency-Key: $REQUEST_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "mode": "simple",
        "prompt": "bright city pop about a late train home",
        "instrumental": false
      }'

curl -X POST https://api.omnapi.com/api/v1/suno/songs \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: $REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "custom",
    "lyrics": "[Verse]\nNeon rain on the station floor...",
    "tags": "city pop, warm bass, female vocal",
    "title": "Late Train"
  }'

curl -X POST https://api.omnapi.com/api/v1/suno/songs \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: $REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "upload-extend",
    "audio": {
      "url": "https://example.com/source.wav",
      "extensionType": "wav"
    },
    "continueAt": 60,
    "prompt": "continue into a larger final chorus",
    "title": "Extended Demo"
  }'

curl -X POST https://api.omnapi.com/api/v1/suno/songs \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: $REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "upload-cover",
    "audio": {
      "url": "https://example.com/source.mp3",
      "extensionType": "mp3"
    },
    "prompt": "reinterpret this as warm acoustic pop",
    "tags": "acoustic pop, intimate vocal"
  }'

Generation receipt

Expand the complete JSON example

{
  "taskId": "task_01J...",
  "generationId": "task_01J...",
  "status": "PROCESSING",
  "creditsRequired": 28,
  "estimatedCompletionTime": "2026-07-30T12:03:00.000Z",
  "requestId": "req_01J...",
  "links": {
    "task": "/api/v1/tasks/task_01J...",
    "resource": "/api/v1/suno/generations/task_01J...",
    "final": null
  },
  "pricing": {
    "baseCredits": 28,
    "calculatedCredits": 28,
    "chargedCredits": 28,
    "adjustmentCredits": 0,
    "settlementRoundingCredits": 0,
    "settlementPolicyVersion": "whole-credit-v1",
    "billingIncrementCredits": 1,
    "source": "standard",
    "quoteVersion": 2
  },
  "product": {
    "type": "suno",
    "providerCode": "suno",
    "modelCode": "chirp-hawk",
    "featureCode": "text-to-music-simple",
    "resourceId": "task_01J...",
    "deliveryStatus": "submitted",
    "autoFinalize": false
  },
  "warningCodes": [],
  "clipIds": [
    "clip_a",
    "clip_b"
  ],
  "deliveryStatus": "submitted",
  "pollUrl": "/api/v1/tasks/task_01J...",
  "viewUrl": "/api/v1/suno/generations/task_01J...",
  "finalUrl": null,
  "autoFinalize": false
}

The receipt intentionally has no stream link. Before acknowledgement, clipIds can be empty and deliveryStatus can be null; the Generation ID and both polling URLs remain stable. Replaying the same request with the same Idempotency-Key returns this same product identity and never creates a second paid generation.

Field	Meaning
`taskId`	Execution, billing, cancellation, and webhook identity
`generationId`	Stable song-product identity; currently equal to `taskId`
`clipIds`	External Suno candidate IDs already acknowledged when available
`pollUrl`	Canonical Task read for execution and settlement
`viewUrl`	Canonical Generation read for candidate and playback state
`deliveryStatus`	Aggregate candidate state; nullable before provider acknowledgement
`pricing`	Frozen standard or customer-adjusted quote used for this task; see customer pricing and settlement rounding
`product`	Normalized product descriptor used across OmnAPI create responses
`warningCodes`	Non-fatal delivery or intent warnings; empty when none
`estimatedCompletionTime`	Best-effort RFC 3339 estimate, not a delivery guarantee

Choose root creation or derivation

POST /api/v1/suno/songs creates a new root song. It also owns the managed upload composites because the caller supplies audio rather than an existing Suno clip.

POST /api/v1/suno/clips/{clipId}/derive creates a derivative whose identity and access depend on an existing clip. Keeping that relationship in the path makes ownership checks, idempotency scope, audit records, and SDK types unambiguous.

Derive an existing clip

Call POST /api/v1/suno/clips/{clipId}/derive when the source is already a concrete Suno clip. The path expresses the source relationship; the body selects what to create from it.

Supported actions

Only two existing-clip actions are public:

`action`	Result	Standard credits
`extend`	Continuation candidates plus an automatically concatenated complete song	28
`cover`	A reinterpretation of the source clip	28

curl -X POST https://api.omnapi.com/api/v1/suno/clips/clip_123/derive \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: $REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "extend",
    "continueAt": 58.5,
    "prompt": "build into a final chorus"
  }'

Extend and Concat are one public operation, one task, and one charge. When the task completes, prefer the resource with role: "final"; the continuation alternatives retain role: "candidate". There is no public standalone Concat endpoint.

Request rules

The path parameter must identify a concrete source clip/result, not an OmnAPI task ID. Unknown fields and actions other than extend / cover are rejected. The optional controlSliders object contains the three bounded weights listed below.

Field	Type	Applies to	Limits and meaning
`action`	`"extend"` \| `"cover"`	both	Required operation discriminator.
`prompt`	string	both	Optional creative instruction; max 5000 chars.
`tags`	string	both	Optional style tags; max 1000 chars.
`negativeTags`	string	both	Optional exclusions; max 1000 chars.
`title`	string	both	Optional title; max 100 chars.
`isInstrumental`	boolean	both	Optional instrumental intent.
`isRemix`	boolean	both	Optional remix intent.
`continueAt`	number	Extend	Continuation timestamp in seconds, minimum `0`. Values beyond the source duration continue from the clip end.
`continuedAlignedPrompt`	string	Extend	Optional aligned continuation prompt; max 5000 chars.
`controlSliders.style_weight`	number	both	Optional style weight from `0` to `1`.
`controlSliders.audio_weight`	number	both	Optional source-audio weight from `0` to `1`.
`controlSliders.weirdness_constraint`	number	both	Optional creative-variation constraint from `0` to `1`.
`model`	enum	both	One of the six values in Supported generation models.
`config`	object	both	Standard task config: `priority`, `tags`, `metadata`, `webhookUrl`.

Response and automatic finalization

The response is the same Generation receipt returned by song creation. autoFinalize is true for Extend because the required Concat is part of the same product. Cover returns candidates without a separate finalization request.