SDK setup and recovery

The client packages distributed with these docs are version 0.5.0. Install the explicit download on your language setup page; 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.

Choose your language

TypeScript SDK — Install, configure, and create a Suno task.
Python SDK — Install, create, save a receipt, and resume a task.

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 in the TypeScript setup. 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.

createMvAndWait / create_mv_and_wait return the receipt only after their wait and subsequent reads finish. They do not persist it for you. For durable jobs, call createMv / create_mv, save the receipt, then wait separately. If the combined helper throws before returning and you have no receipt, recover it with the create method using the exact saved body and idempotency key, then resume reads. Do not rerun preflight or replace quote IDs in that recovery body. Respect the idempotency retention boundary.

Normal terminal transitions settle charges and eligible refunds together. refunded: true includes successful partial refunds; use the amounts to distinguish a partial refund from a free order. Reconcile any older or recovery record still reporting settlementStatus: "PENDING". Credit fields.

MV contracts and current quote limitation

MV create receipts contain a stable mvId alias; later views may expose the canonical project/storyboard ID. Use returned IDs and URLs. Fast managed-create Tasks have a readable initialization view before the video is ready. Creation behavior.

The Omn helpers target /api/v2/mv at the default server https://api.omnapi.com. Use an API key, check capabilities and preflight the actual media before purchasing. Existing MV helpers retain their original routes. API availability.

Do not call quoteMvStudioLockCharacter or quote_mv_studio_lock_character: the current public quote endpoint rejects step: "lock-character". The character write exists, but integrations requiring quote confirmation should leave this action disabled. Current limitation.

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.