Python SDK setup

Keep your API key on your server. See SDK timeouts and recovery.

Python

Requires Python 3.9+. Install the source distribution in a virtual environment:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install https://docs.omnapi.com/sdk/omnapi-python-0.5.0.tar.gz

import json
import os
from pathlib import Path
from omnapi import OmnapiClient, OmnapiError

client = OmnapiClient(os.environ["OMNAPI_KEY"], timeout=30)
# Persist this key and the exact body before submitting. Reuse them on retries.
key = os.environ["OMNAPI_REQUEST_KEY"]
if not key:
    raise ValueError("Set and persist OMNAPI_REQUEST_KEY first")
receipt_file = Path("song-receipt.json")
try:
    if receipt_file.exists():
        receipt = json.loads(receipt_file.read_text())
    else:
        receipt = client.generate_suno_song(
            idempotency_key=key,
            mode="simple", prompt="warm indie pop, brushed drums", model="chirp-hawk",
        )
        # Save before waiting. Keep this file private; one process owns this job.
        with os.fdopen(os.open(receipt_file, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600), "w") as saved:
            json.dump(receipt, saved)
    task = client.wait_for_task(str(receipt["taskId"]), timeout_sec=1800)
    if task["status"] != "COMPLETED":
        raise RuntimeError(f"Task ended: {task['status']}")
    for resource in task.get("resources", []):
        if resource.get("type") in ("MUSIC", "AUDIO", "VIDEO", "IMAGE"):
            print(resource.get("url"))
except OmnapiError as error:
    print(error.status_code, error.code, error.request_id)
    raise

Keep media URLs and error details in private application logs. For creation and persisted receipts, start with the Python song program. See MV contracts and the character-lock quote limitation before using MV helpers; the package README carries the same restrictions.