Suno API integration in Python and TypeScript: generation, playback, and exports

OmnAPI exposes Suno-compatible song creation at POST /api/v1/suno/songs. Use the Generation view to decide when a clip can play and the Task view for execution and billing. These views answer different questions: one candidate may be playable while the overall task is still processing.

This is an integration guide for OmnAPI's public service, not a claim of an official relationship with Suno. The fields below were checked against the Suno API guide on September 18, 2026.

Start with one recoverable song request

Create a key in your OmnAPI account and store it on your application server. Use your frontend only to submit an authorized request to that server. Before the first paid call, read the current catalog.

export REQUEST_ID="$(uuidgen)"
curl --fail-with-body https://api.omnapi.com/api/v1/suno/songs \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: $REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "mode":"simple",
    "prompt":"upbeat city pop, bright guitars, summer night drive",
    "model":"chirp-hawk"
  }'

Persist the request ID and exact body together. On an uncertain network response, reuse that pair; do not create a new idempotency key merely because your HTTP client timed out. Save taskId and generationId from the receipt. Prefer: respond-async is available when your client should not wait for the brief initial acknowledgement.

The standard price for chirp-hawk is 28 credits at review time. chirp-goose is 25. Your account pricing and the receipt's creditsRequired determine the charge. A generation request is the billing unit; avoid advertising a fixed price per finished, approved song without accounting for retries and selection.

Python and TypeScript examples

The integration examples provide downloadable server-side Python and TypeScript programs. Each accepts a persisted request ID, records the receipt, resumes polling from a task ID, and stops on COMPLETED, FAILED, or CANCELLED.

Use a durable job record in a deployed application. A command-line output file illustrates recovery but does not replace a database, user authorization, or concurrent job coordination. If polling reaches its deadline, retain the task ID and resume it. The server-side generation may still be running.

Play a candidate before the whole task finishes

Query GET /api/v1/suno/generations/{generationId} on your server. Select the desired clip from clips[] and require both playable: true and a non-null playback.url.

Resolve a relative playback URL against https://api.omnapi.com. The media request does not need your API key. Pass the temporary URL only to the authorized player, not into analytics or public logs. Refresh the Generation after expiresAt or a playback error; avoid resetting an actively playing audio source on every poll.

No SSE subscription or separate playback-session request is needed for this flow. Respect playback.retryAfterMs, request limits, and user-initiated browser playback requirements. A generated audio candidate still needs listening and content review before publishing.

Export a completed clip in the format you need

The export endpoint is POST /api/v1/suno/clips/{clipId}/export. Send format: "mp3", "m4a", or "wav"; it returns a separate task receipt. Reuse the same idempotency key only when retrying that exact export request.

At review time, standard export prices are 2 credits for MP3, 1 for M4A, and 3 for WAV. Exports, stem separation, and other operations are separate from song creation. Read the catalog before you construct a budget. Do not infer permanent file availability from a delivery URL; copy approved outputs to storage you control.

Handle failures without multiplying charges

A 401 calls for checking the server key. A validation error calls for correcting the payload. A 429 calls for waiting according to Retry-After. An ambiguous timeout calls for recovering the original operation with its existing idempotency key. A terminal failed task calls for reviewing the public error and settlement before authorizing another creation.

Keep clip IDs, task IDs, Generation IDs, and your own user IDs distinct in storage. Authorize every lookup against your application user. Webhooks must be verified using the documented raw-body signature and processed idempotently.

Continue with the Suno Songs product page, full quickstart, operation guide, or credit pricing.