Suno API in Python and TypeScript — Recoverable Song Examples

These examples create one Suno-compatible song through OmnAPI, save its task receipt, and wait for a terminal state. They use standard HTTP libraries and require no SDK installation. Keep the API key and job file on your server. Running a new job creates paid work; read the current catalog and your account balance first.

Python

Download suno_song.py. Use Python 3.9 or later.

export OMNAPI_KEY='your-server-side-key'
python3 suno_song.py my-song.json

TypeScript

Download suno-song.ts. Run it with Bun.

export OMNAPI_KEY='your-server-side-key'
bun suno-song.ts my-song.json

Both programs default to mode: "simple" and model: "chirp-hawk". Set OMNAPI_PROMPT before creating a new job to change its prompt. The persisted request is authoritative on subsequent runs; changing the environment does not change a request that may already have been accepted.

What gets saved

Before the first POST, the program creates a private JSON file with a generated idempotency key and the exact request body. It then stores taskId and generationId from the receipt. On completion it stores the task result, including any resource URLs. It never stores your API key in that file.

The files use restrictive permissions on systems that support them. Keep them out of source control, shared directories, analytics, and public web roots. In a deployed application, replace the local file with a durable job record and authorize access against your own application user. Run one process per job file.

Resume without creating another song

Run the same command with the same job filename. If a task ID exists, the program only queries that task. If the original POST response was lost, it reuses the saved idempotency key and body. Do not delete the file after a network error or change the saved body while keeping its key.

Requests have a 30-second HTTP timeout. Polling checks every five seconds and stops after a 45-minute local deadline. The deadline does not cancel the server task. If a request fails, the program stops; inspect the HTTP status and observe Retry-After before resuming. It does not automatically retry paid writes.

COMPLETED, FAILED, and CANCELLED are all terminal. Only COMPLETED exits successfully. Read the task’s error and settled credit state before deciding to create a new paid request.

Playback, exports, and production delivery

These programs wait for the Task. For playback during generation, read the Generation and use a clip with playable: true and a non-null playback.url. An audioUrl can remain null while live audio is playable. See the Suno playback guide.

Select output resources by type rather than assuming the first entry is audio. Review accepted output and copy files into your own storage. MP3, M4A, WAV, and stem exports are separate operations with their own task receipts and prices. Use the Suno quickstart for those request shapes.

For larger applications, use the same durable task pattern with the Producer endpoints and the MV quote and preflight workflow. If you receive webhooks, verify the raw-body signature and process duplicate events idempotently; see Webhook Events.