Suno Asset Storage and Downloads
A download URL and the file behind it expire separately. Save the asset ID and your Task receipt, not only a URL: a URL can expire while the file is still kept, and a new URL does not extend how long the file is kept. Default URL lifetimes and retention are summarized in the Suno songs API.
Check availability and retention
Section titled “Check availability and retention”curl https://api.omnapi.com/api/v1/suno/storage \ -H "x-api-key: $OMNAPI_KEY"This requires usage:read. Offer paid storage only when available is true;
an available policy is not an active subscription.
Without account-wide monthly storage, Suno files are kept as follows:
| Asset | Included retention | Paid extension |
|---|---|---|
| Ordinary audio, including M4A and MP3 | 14 days from delivery | Optional long-term storage |
| WAV | 180 days from delivery | None |
| Timestamp lyrics snapshot | 180 days from delivery | None |
Each asset’s retainedUntil, status and policy are the deadline for that
file. Files delivered earlier with permanent rights keep their access for the
same customer even if they are missing from the new asset list. A copy delivered
to a different customer has its own policy.
Find and download assets
Section titled “Find and download assets”Both requests require task:read and work even after Task history is gone.
curl 'https://api.omnapi.com/api/v1/suno/assets?limit=20' \ -H "x-api-key: $OMNAPI_KEY"The response has items and nextCursor; pass cursor=nextCursor until it is
null. limit is 1–100. Each asset has id, clipId, format, byteLength,
deliveredAt, retainedUntil, status and policy. byteLength is a decimal
string; do not parse it as a float.
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. URLs last 7 days
(604800 seconds) by default, never past retainedUntil; earlier URLs keep their
original expiry. Open the URL without an API key and do not edit it. Any origin
can read the media, but the URL gives no access to the asset API. Timestamp
lyrics are gzip-compressed JSON; decompress before parsing.
| Response | What to do |
|---|---|
| 404 | Check the asset ID and account; other customers’ assets are not disclosed |
| 410 | The file has expired and cannot be restored |
| 503 | Temporary; retry with bounded backoff |
| Media URL expired, asset still kept | Request a new URL |
Enable long-term ordinary audio storage
Section titled “Enable long-term ordinary audio storage”This is the original Suno-only subscription. It extends ordinary audio only, not
WAV or timestamp lyrics, and cannot revive expired files. Accounts upgraded to
monthly resource storage are managed
by their administrator; changing this subscription then returns 409. Existing
subscriptions are not upgraded automatically.
New subscriptions cost 20 credits per GB-month; existing subscriptions keep
their accepted rate, including after cancelling and re-enrolling. Show the user
subscription.rateUnitsPerGbMonth if a subscription exists, otherwise
publishedRateUnitsPerGbMonth. Amounts are integer strings in credit units
(1 credit = 10,000 units), billed per decimal GB (1,000,000,000 bytes) per 30
days. Usage after the first 14 days is metered and settled daily.
Enabling requires storage:write. Set ACCEPTED_RATE_UNITS to the rate you
showed, for example 200000 for a new 20-credit subscription:
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 ordinary audio that is still kept and all future
deliveries. Later storage reads show subscription, billableBytes and
unpaidUnits; pay unpaid charges to keep files retained.
Cancel and reconcile charges
Section titled “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}'Cancelling stops new charges and leaves a seven-day download window ending at
graceUntil. Copy what you need before then and settle unpaid charges.
Re-subscribing does not recover expired files.
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 has its time range, amountUnits, captured rateUnitsPerGbMonth,
byteMilliseconds and status. Keep the integer strings intact when
reconciling. See Credits and
Task resources.
Monthly storage for all final resources
Section titled “Monthly storage for all final resources”An account administrator can extend storage to every delivered final file: Suno WAV, audio and timestamp lyrics, MV final videos and subtitles, audio editing outputs and others. It is disabled by default and is not turned on by a plan change or credit purchase. Included retention and earlier permanent rights do not change.
| Subscription | Price per decimal GB-month (30 days) |
|---|---|
| New subscription | 20 credits (200,000 credit units) |
| Existing subscription | Original accepted rate |
| Existing subscription re-enabled after stopping | Original accepted rate |
| Suno-only subscription upgraded to monthly resource storage | Original accepted rate |
rateUnitsPerGbMonth is your account’s rate; without a subscription it quotes
the new-subscription price. A published price change does not reprice existing
subscriptions or earlier bills. For example, a subscription at 1 credit per
GB-month stays at 1 credit.
A file appears as READY once it is archived; pending copies are not billed.
Inputs, intermediate scenes and compute caches are outside this service, so
keeping an MV final does not keep everything needed to edit it later. Enabling storage does not restore expired files.
curl https://api.omnapi.com/api/v1/storage \ -H "x-api-key: $OMNAPI_KEY"This requires usage:read. enabled is your subscription; available only says
whether new enrollment is open. Ask your administrator to change it.
totalBytes includes verified files still in their free window, billableBytes
those past it, and pendingAssets files awaiting verification.
Billing is actual bytes × time after each file’s free window, starting no earlier
than verification. All products share one monthly bill that closes at midnight
on the first of the next month, Asia/Shanghai time. The unit is decimal GB
per 30 days, so 1 GB kept all 31 days of a month costs 31/30 of the rate.
rateUnitsPerGbMonth and amountUnits are integer strings (10,000 units = 1
credit); fractional remainders carry forward.
List and download with task:read, even after the original Task expires:
curl 'https://api.omnapi.com/api/v1/storage/assets?limit=20' \ -H "x-api-key: $OMNAPI_KEY"curl "https://api.omnapi.com/api/v1/storage/assets/$ASSET_ID/download" \ -H "x-api-key: $OMNAPI_KEY"Each item has providerCode, resourceId, format, byteLength, status and
its original freeUntil. retainedUntil: null means an active subscription
protects the copy, not that the URL never expires; refresh url after
urlExpiresAt. The Suno asset list still describes the original delivery.
curl 'https://api.omnapi.com/api/v1/storage/charges?limit=20' \ -H "x-api-key: $OMNAPI_KEY"Each bill (usage:read) has its time range, byte-milliseconds, captured rate,
amount, status and a per-product breakdown. A retried settlement never debits the
same bill twice.
Disabling storage, or running out of credits, stops further charges. Files stay downloadable until the later of their original free expiry and seven days after stopping. Usage already accrued stays on the bill, and paying it does not re-enable storage.
DELETE /api/v1/storage/assets/$ASSET_ID (storage:write) removes a stored copy,
stops its charges and blocks new downloads. It does not delete the original
delivery. Deleting an MV also removes its stored copies. Links already issued
may work until they expire. Re-enrolling does not bring deleted copies back.
Account storage operation reference
Section titled “Account storage operation reference”| Operation | Scope | Effect |
|---|---|---|
GET /api/v1/storage | usage:read | Read the account-wide subscription; free |
GET /api/v1/storage/assets | task:read | List retained resources; free |
GET /api/v1/storage/assets/{id}/download | task:read | Get a current download URL; free |
DELETE /api/v1/storage/assets/{id} | storage:write | Delete the stored copy and stop future charges |
GET /api/v1/storage/charges | usage:read | List monthly bills; free |
GET /api/v1/storage/charges/{id} | usage:read | Read one bill; free |
Full schemas: storage endpoints.