Suno Asset Storage and Downloads

Save the asset ID and your task receipt, not just a download URL. A URL can expire while the asset is still retained. Refreshing a URL does not extend the asset’s retention period.

Check availability and retention

curl https://api.omnapi.com/api/v1/suno/storage \
  -H "x-api-key: $OMNAPI_KEY"

This request requires usage:read. Check available before offering paid storage in your application. An unavailable policy is not an active subscription; do not infer activation from these documentation pages alone.

For assets delivered under this policy:

Asset	Included retention	Paid extension
Ordinary audio, including M4A and MP3	14 days from delivery	Optional long-term storage
WAV	180 days from delivery	Fixed retention
Timestamp lyrics snapshot	180 days from delivery	Fixed retention

Use the asset’s returned retainedUntil, status, and policy as the authority for that delivery. Historical permanent assets keep their existing access paths and rights for the same customer. Their absence from the new asset list does not mean those rights have been removed. A copy delivered to a different customer has its own access and retention policy.

Find and download assets

The asset list is independent of Task history. Both requests require task:read.

curl 'https://api.omnapi.com/api/v1/suno/assets?limit=20' \
  -H "x-api-key: $OMNAPI_KEY"

The response contains items and nextCursor. Supply cursor=nextCursor to continue; stop when it is null. limit accepts 1–100. Each asset includes id, clipId, format, byteLength, deliveredAt, retainedUntil, status, and policy. Byte lengths are decimal strings; avoid lossy floating-point parsing.

curl "https://api.omnapi.com/api/v1/suno/assets/$ASSET_ID/download" \
  -H "x-api-key: $OMNAPI_KEY"

The download response adds url and urlExpiresAt. Open the returned URL without an API key. It lasts at most one hour and never beyond retainedUntil. Do not construct the URL, change its query string, or send your API key to the media host. Timestamp-lyrics downloads are gzip-compressed JSON snapshots; decompress them with your HTTP client or gzip library before parsing JSON.

Response	Action
404	Check the asset ID and customer account; other customers’ assets are not disclosed
410	The delivery has expired; refreshing the URL cannot restore it
503	Download is temporarily unavailable; use bounded backoff
Expired media URL, asset still retained	Obtain a new URL from the download endpoint

Enable long-term ordinary audio storage

Read publishedRateUnitsPerGbMonth from the storage response and show it to the person authorizing the subscription. Amounts are integer credit units represented as strings; 1 credit = 10,000 units. The billing unit is a decimal GB (1,000,000,000 bytes) over 30 days. Usage after the initial 14 days is metered and settled daily; do not hard-code a rate from an example.

Enabling requires storage:write. Set ACCEPTED_RATE_UNITS to the exact current published rate after reviewing it:

curl -X PUT https://api.omnapi.com/api/v1/suno/storage \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"enabled\":true,\"acceptedRateUnits\":\"$ACCEPTED_RATE_UNITS\"}"

The subscription covers currently live ordinary audio and future deliveries. It does not extend WAV or timestamp-lyrics retention and cannot revive expired assets. Inspect subscription, billableBytes, and unpaidUnits on subsequent storage reads. Resolve unpaid charges before relying on continued retention.

Cancel and reconcile charges

curl -X PUT https://api.omnapi.com/api/v1/suno/storage \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'

Cancellation stops new storage accrual and provides a seven-day download grace period. Inspect the returned graceUntil, copy needed files before expiry, and settle existing unpaid charges. A new subscription does not recover expired media.

curl 'https://api.omnapi.com/api/v1/suno/storage/charges?limit=20' \
  -H "x-api-key: $OMNAPI_KEY"

Charge history requires usage:read and uses the same cursor pagination. Each entry identifies its time range, amountUnits, captured rateUnitsPerGbMonth, exact byteMilliseconds usage, and settlement status. Keep the integer strings intact when reconciling them with your credit usage.

See Credits, Task resources, and the API Reference for complete response schemas.