TypeScript and Python SDK Setup

The client packages distributed with these docs are version 0.3.0. Install the explicit download below; do not assume a similarly named registry package is this distribution. Package checksums identify the files. If you prefer no SDK dependency, use the complete HTTP examples.

TypeScript

Requires Node.js 20+ or Bun. The archive includes compiled JavaScript, types, client source, README, and license.

npm install https://docs.omnapi.com/sdk/omnapi-typescript-0.3.0.tgz

import { OmnapiClient, OmnapiError } from "@omnapi/sdk";

const client = new OmnapiClient({
  apiKey: process.env.OMNAPI_KEY!,
  fetch: (url, init) => fetch(url, {
    ...init,
    signal: init?.signal ?? AbortSignal.timeout(30_000),
  }),
});

// Load this key and body from your durable job record on retries.
const idempotencyKey = process.env.OMNAPI_REQUEST_KEY!;
if (!idempotencyKey) throw new Error("Set and persist OMNAPI_REQUEST_KEY first");
try {
  const receipt = await client.composeProducerMusic(
    { soundPrompt: "warm indie pop, brushed drums", model: "Lyria 3.5", length: 120 },
    { idempotencyKey },
  );
  // Persist receipt.taskId before waiting. On restart, call getTask with that ID.
  const task = await client.waitForTask(receipt.taskId, { timeoutMs: 30 * 60_000 });
  if (task.status !== "COMPLETED") throw new Error(`Task ended: ${task.status}`);
  const song = task.resources?.find(resource => resource.type === "MUSIC");
  console.log(song?.url);
} catch (error) {
  if (error instanceof OmnapiError) {
    console.error(error.status, error.code, error.requestId);
    // Inspect details for taskId, and rateLimit.retryAfter for backoff.
  }
  throw error;
}

This excerpt assumes a durable job store. The downloadable HTTP programs show the persistence step in full. Do not regenerate a key after an uncertain POST.

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.3.0.tar.gz

import os
from omnapi import OmnapiClient, OmnapiError

client = OmnapiClient(os.environ["OMNAPI_KEY"], timeout=30)
try:
    # Resume an accepted job using its saved ID; this does not create new work.
    task = client.wait_for_task(os.environ["OMNAPI_TASK_ID"], 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.

Timeouts, errors, and cancellation

• HTTP timeouts and local wait deadlines do not cancel the server task. Save its ID and resume reading it later. No helper should create a replacement for you.
• The TypeScript client accepts a custom fetch; set a per-request timeout as above. Raw request also accepts an AbortSignal. Python uses its client timeout for each HTTP call. A wait deadline is checked between requests.
• waitForTask / wait_for_task return all terminal states, including FAILED and CANCELLED. Inspect the status and settled credits before consuming output.
• HTTP errors surface as OmnapiError; 429 uses OmnapiRateLimitError. Honor Retry-After and use capped retries of reads. Retain the same key and body for recovery of an uncertain write. Never automatically retry unchanged content after CONTENT_POLICY_REJECTED.
• Use cancelTask / cancel_task for an explicit server-side cancellation request, then poll to confirm its outcome. Stopping a local waiter is separate.

Storage helpers and upgrades

TypeScript	Python
listSunoAssets	list_suno_assets
getSunoAssetDownload	get_suno_asset_download
getSunoStorage	get_suno_storage
setSunoStorage	set_suno_storage
listSunoStorageCharges	list_suno_storage_charges

Check storage availability and explicitly accept the published rate before enrollment; see Suno storage. Keep byte sizes and integer credit-unit strings intact.

Pin the downloaded package version in your lockfile. On upgrade, review the model compatibility guide and validate result handling. Accept additive response fields, check resource types rather than array position, and keep unknown enum values from crashing a status display. SDK installation does not activate account-specific API capabilities.