Permissions and operation side effects

Scope controls access; it does not determine price. A GET can create a task, and a POST quote can be free. All authenticated requests also enforce the key’s IP policy and can return 403 FORBIDDEN.

Operation matrix

Operation	Required scope	Task / charge behavior
GET /pricing/catalog	None	Public, cacheable, free
GET /account/credits, GET /usage/export	usage:read	Free account reads
POST /tasks, POST /tasks/sync	task:create	Creates a task; model/feature pricing applies
GET /tasks, task detail and stream	task:read	Free status/history reads
Task cancellation	task:cancel	Cancels an existing task; settlement is separate
POST /lyrics/generate	task:create	Paid task; immediate result or 202 with pollUrl
Subtitle quote	task:create	Free estimate, no task
Subtitle create / detail	task:create / task:read	Paid creation / free status read
Vidu quote	task:create	Free estimate, no task
Vidu create / detail / cancel	task:create / task:read / task:cancel	Paid creation / free read / cancel
POST /audio/renders	task:create	One paid Task for crop, reorder, repeat, and fades; use standard Task reads
Suno songs, derive, export, lyrics, Voice creation	task:create	Creates a task; some operations are zero-credit
Suno availability, clips, generations, Voice list	task:read	Free direct reads
Suno timeline GET	task:read	Creates or reuses a task; standard price 1 credit; may return 202
Suno audio-analysis, style recommendation, Voice detail GET	task:read	Creates or reuses a zero-credit task; may return 202
Suno Voice verification-phrase GET	task:create	Creates a preparation task; follow the Voice workflow receipt
MV quote / preflight, upgrade preflight	task:create	Free estimate / validation; no generation task
MV create, render, regenerate, lock-character, finalize, upgrade	task:create	Creates tasks; operation pricing applies. Lock-character currently has no accepted public quote variant.
MV scene PATCH, select-rendering PATCH, MV DELETE	task:create	Mutates existing content; inspect the operation’s billing behavior
MV list, availability, view, final URL, operations ledger	task:read	Free reads
API v1 MV operation cancellation	task:cancel	Cancels an existing operation
API v2 MV operation cancellation	task:create	Uses the v2 write permission; refund settlement remains separate
Suno assets list / download URL	task:read	Asset discovery and URL refresh
Suno storage / storage charges GET	usage:read	Policy, rate, subscription and billing reads
Suno storage PUT	storage:write	Enables or cancels a separately billed storage subscription

Paths above are relative to /api/v1. Use the endpoint directory for exact methods and paths. An unrestricted key has an empty scope list or *.

Task-producing reads and safe recovery

Do not prefetch timeline or preparation URLs as if they were ordinary static files. A request can start work even though its method is GET. Repeated reads may reuse work, but that is not a permanent idempotency or free-cache guarantee. When a read returns 202, save its taskId and pollUrl and query the existing task.

The supported task-creation POSTs expose Idempotency-Key in the API Reference. Use one saved key per logical operation. GET reads and storage PUT are not covered by that POST idempotency contract. See Task recovery.

Budget limits

MV, Vidu, Subtitle, and Audio Editing creates accept maxCredits where specified. Suno reject that unsupported field. A quote does not reserve a price or authorize a task; confirm the final receipt and settled charge. See Credits and Billing.