Skip to content

    API documentation

    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.

    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.

    Terminal window
    curl --fail https://docs.omnapi.com/examples/suno_song.py -o suno_song.py
    python3 suno_song.py song-job.json

    Keep 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.

    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.

    Terminal window
    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.

    Terminal window
    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.

    Set TASK_ID to the actual receipt value, then query with capped backoff:

    Terminal window
    export TASK_ID="task_123"
    curl --fail-with-body "https://api.omnapi.com/api/v1/tasks/$TASK_ID" \
    -H "x-api-key: $OMNAPI_KEY"
    StatusNext step
    PENDING / PROCESSINGWait and poll again; respect Retry-After
    COMPLETEDRead the selected resource’s URL or content
    FAILED / CANCELLEDStop 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.

    • 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.