Make your first API request
Start with one song task. The same create → receipt → result pattern applies to music and video. For a complete program with persisted recovery state, use the Python and TypeScript examples.
Run the complete saved-receipt workflow
Section titled “Run the complete saved-receipt workflow”The downloadable Python program saves the key and exact body before submission, saves the returned IDs, and polls for up to 45 minutes. It uses the Python standard library. Run it again with the same job file to recover or resume; a local timeout does not cancel the server Task. Do not run two processes against the same job file.
curl --fail https://docs.omnapi.com/examples/suno_song.py -o suno_song.pypython3 suno_song.py song-job.jsonKeep the resulting job file private. The sections below explain the same operations individually; do not also run their create command for a job you already submitted.
1. Prepare a key and one request
Section titled “1. Prepare a key and one request”Create an API key in Dashboard → API Keys.
Use a key with task:create and task:read. This song request costs 28 standard
credits; check your balance and current price first.
export OMNAPI_KEY="your-server-side-key"# Generate once for this logical job. Save it; retries must use this same value.export IDEMPOTENCY_KEY="$(uuidgen)"Keep the API key on your server. If the network fails, retain this request’s key and body; generating another key would identify a new paid operation.
2. Create the task
Section titled “2. Create the task”curl --fail-with-body -X POST https://api.omnapi.com/api/v1/suno/songs \ -H "x-api-key: $OMNAPI_KEY" \ -H "Idempotency-Key: $IDEMPOTENCY_KEY" \ -H "Content-Type: application/json" \ -d '{"mode":"simple","prompt":"bright synthwave, warm bass, retro drums","model":"chirp-hawk"}'Save taskId from the response. This HTTP 200 receipt excerpt confirms acceptance:
{ "taskId": "task_123", "status": "PENDING"}The full Suno receipt also includes
song candidate IDs and creditsRequired. Keep the actual taskId for polling.
3. Read the result
Section titled “3. Read the result”Set TASK_ID to the actual receipt value, then query with capped backoff:
export TASK_ID="task_123"curl --fail-with-body "https://api.omnapi.com/api/v1/tasks/$TASK_ID" \ -H "x-api-key: $OMNAPI_KEY"| Status | Next step |
|---|---|
| PENDING / PROCESSING | Wait and poll again; respect Retry-After |
| COMPLETED | Read the selected resource’s URL or content |
| FAILED / CANCELLED | Stop polling; inspect errorCode, retryable, refunded and creditsCharged |
HTTP 200 · completed Task response excerpt:
{ "status": "COMPLETED", "resources": [ { "id": "clip_123", "type": "MUSIC", "url": "https://media.example.com/song.mp3" } ]}Read the URL of a MUSIC resource. Download it without sending your API key
to the media host, and keep a copy before the retention deadline.
Use the bounded polling helper in an application. For a missing receipt after a timeout, recover the original request with the same route, body and idempotency key. A 4xx/5xx response can include an already created task ID; inspect it before retrying.
Choose your next workflow
Section titled “Choose your next workflow”- Suno song — follow candidates and play audio during generation.
- Music video — quote, validate, create and download.
- SDK setup — install the provided TypeScript or Python client.