API Permissions and Billable Operations
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
Section titled “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 |
| Producer image, lyrics, compose, modify | task:create | Creates a task; operation pricing applies |
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 |
| 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 | task:create | Free estimate / validation; no generation task |
| MV create, render, regenerate, lock-character, finalize | task:create | Creates tasks; quoted operation pricing applies |
| 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 |
| MV operation cancellation | task:cancel | Cancels an existing operation |
| 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
Section titled “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
Section titled “Budget limits”MV, Vidu, and Subtitle creates accept maxCredits where specified. Suno and
Producer 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.