OmnAPI Credits and Billing

OmnAPI bills in credits. You purchase credit packages from the dashboard; each paid task deducts its quoted credit amount when the task is created. If the task fails or is cancelled before producing billable output, eligible credits are refunded automatically.

New accounts receive 100 welcome credits automatically on first successful sign-in, enough to try several Producer or Suno operations before topping up.

Credit value

Published top-up packages:

Package	Credits	Price	Effective rate
Starter	3,500	$10	$0.002857 / credit
Pro	40,000	$100	$0.002500 / credit
Enterprise	500,000	$1000	$0.002000 / credit

Product pricing is published in OmnAPI credits. Suno song generation with chirp-auk-turbo costs 25 OmnAPI credits; other published models and generative-derive requests remain 28 credits. suno/chirp-v3-5 is no longer available for new requests.

Use the published tables below, or read the runtime catalog from GET /api/v1/pricing/catalog, for fixed-price operations. Use POST /api/v1/mv/quote for dynamic MV quotes before creating the task. MV quote is an estimate; use POST /api/v1/mv/preflight when you also need remote resource validation and a reusable create-time estimate. Use POST /api/v1/vidu/quote for Vidu operations. maxCredits is available on MV and Vidu creates; Suno and Producer do not expose it.

curl https://api.omnapi.com/api/v1/pricing/catalog

/api/v1/pricing/catalog is public and cacheable. It returns the customer-facing credit catalog generated from the same runtime pricing functions used during task credit deduction.

Current price table

Fixed and free operations:

Product line	Operation	Endpoint / option	Credits
Producer	Generate image	POST /api/v1/producer/generate/image	8
Producer	Generate lyrics	POST /api/v1/producer/generate/lyrics	1
Producer	Compose music	POST /api/v1/producer/generate/music/compose	28
Producer	Modify music	POST /api/v1/producer/generate/music/modify	28
Suno Direct	Song generation with chirp-auk-turbo	/songs with simple, custom, upload-extend, or upload-cover	25
Suno Direct	Song generation with the other five public models	/songs with simple, custom, upload-extend, or upload-cover	28
Suno Direct	Public Voice generation	/songs with vox and chirp-crow or chirp-fenix	28
Suno Direct	Existing-clip Extend or Cover	/clips/{clipId}/derive	28
Suno Direct	Lyrics generation	/lyrics, including paired candidates	0
Suno Direct	Reads	clip detail, batch clips, audio analysis, styles, Voice list/detail	0
Suno Direct	Aligned lyrics timeline	GET /api/v1/suno/clips/:clipId/timeline	1 standard; 0 for the legacy Suno 55,000 plan
Suno Direct	Twelve stems / named extract	stemsMode=twelve / extract (98 native Suno names)	140 / 56
Suno Direct	Create public Voice from owned clip	POST /api/v1/suno/voices/from-clip	5
Suno Direct	Create verified public Voice from recordings	Obtain a verification phrase, then POST /api/v1/suno/voices with both recordings	66
MV	Quote	POST /api/v1/mv/quote	0
MV	Preflight	POST /api/v1/mv/preflight	0
MV Premium V2	perform create	managedVersion="premium-v2", performanceMode="perform"	Standard public rate: 42 OmnAPI credits / second
MV Premium V2	sing, sing_perform, or dance create	Explicit Premium V2 mode at 720p	Standard public rate: 48 OmnAPI credits / second
MV Fast	Recompose final after Fast scene edits	POST /api/v1/mv/{mvId}/finalize	Dynamic; returned on the task receipt
MV Studio Beta	Storyboard + scene stills	POST /api/v1/mv with mode="studio"	250 + optional Visual Board add-on
MV Studio Beta	Regenerate scene image	POST /api/v1/mv/{mvId}/scenes/{sceneIndex}/regenerate-image	15
MV Studio Beta	Finalize selected scenes	POST /api/v1/mv/{mvId}/finalize	50
Vidu	Quote	POST /api/v1/vidu/quote	0
Vidu	Video, image, audio, motion, template, and film tasks	POST /api/v1/vidu/tasks	Dynamic; 2 OmnAPI credits × Vidu credits

Dynamic MV pricing depends on managed version, performance mode, duration, resolution, add-ons, Fast recompose pricing, and selected Studio rendering options. Always call POST /api/v1/mv/quote before creating or rendering an MV when the operation supports quotes; otherwise rely on the creditsRequired value returned on the task receipt.

Vidu quotes vary by operation, model, resolution, duration, and off-peak selection. For media tools that price by the length of a supplied URL, include pricingContext.durationSec. See the Vidu API guide.

Mode	Resolution / add-on	Public formula	Example
Fast MV	540p	Dynamic per-second pricing	Use quote API
Fast MV	720p	Dynamic per-second pricing	Use quote API
Fast MV	1080p	Dynamic per-second pricing	Use quote API
Fast MV	Lip-sync	Dynamic per-second surcharge	Use quote API
Premium MV V2	perform, fixed 720p	21 Vidu credits/second × 2 OmnAPI credits/Vidu credit	60s standard example: 2,520
Premium MV V2	sing, sing_perform, or dance, fixed 720p	24 Vidu credits/second × 2 OmnAPI credits/Vidu credit	60s standard example: 2,880
Fast MV	Recompose final after Fast scene edits	Dynamic recompose pricing	Returned on task receipt
Studio MV	Scene render	Dynamic by selected render option, model, resolution, fps, and duration	Use quote API

MV quote and preflight responses return credits as the final estimate and breakdown as the customer-facing pricing summary. breakdown.duration is billable duration in seconds, not a credit amount. The charged amount for a paid create is the creditsRequired value returned on the task receipt.

Premium V2 scene edit and compose do not inherit the OneClick V1 price. They remain unavailable until the deployment separately enables those capabilities with approved rates. Read MVView.capabilities before exposing either action.

The task credit fields

Every task descriptor carries up to three credit fields:

Field	Set when	Meaning
creditsRequired	Task creation	The credit amount authorized and deducted to start the task.
creditsCharged	Task reaches a terminal state	The final billed amount after completion, failure, cancellation, or partial output handling.
refunded	If credits are returned	true when OmnAPI returned credits for this task.

Most successful tasks have creditsCharged === creditsRequired. Failed or cancelled tasks usually have creditsCharged: 0 and refunded: true. Partial output scenarios may keep a smaller final charge when usable assets were generated before a later packaging failure.

Customer pricing and settlement rounding

Customer-specific pricing is calculated at 1/10,000-credit precision, then settled once for the complete order. Ordinary quoteVersion: 2 receipts use the versioned whole-credit-v1 policy and report billingIncrementCredits: 1:

chargedCredits =
  ceil(calculatedCredits / billingIncrementCredits)
  * billingIncrementCredits

Commercial prices that explicitly preserve decimals use quoteVersion: 3 with credit-unit-exact-v1. For example, a 28-credit operation under the exact 10/11 contract ratio charges 25.4545 credits:

{
  "baseCredits": 28,
  "calculatedCredits": 25.4545,
  "chargedCredits": 25.4545,
  "adjustmentCredits": -2.5455,
  "settlementRoundingCredits": 0,
  "settlementPolicyVersion": "credit-unit-exact-v1",
  "billingIncrementCredits": 0.0001,
  "quoteVersion": 3
}

The selected settlement policy is deliberate and frozen with the Task. Under whole-credit-v1, 2.7273 calculated credits still settle at 3; under credit-unit-exact-v1, they charge 2.7273. Always use chargedCredits or the create receipt’s creditsRequired; do not derive the debit from baseCredits or quoteVersion alone.

Persist settlementPolicyVersion and billingIncrementCredits with the quote when forecasting costs. The meaning of a named policy is stable for tasks that use it, but clients should not assume every future policy will use a one-credit increment. A future settlement rule must identify itself in the receipt, and a task’s frozen quote is not repriced after creation.

Historical quoteVersion: 1 tasks used fractional-legacy-v1. Reads such as a Task or Suno Generation may therefore return a fractional chargedCredits for those existing tasks. This preserves their original ledger amount; it does not change the whole-credit rule for new creates.

Cancellation refunds are evidence-based. A task cancelled before Provider submission is refunded immediately. After submission, OmnAPI writes CANCELLED/REFUNDED only when the Provider explicitly confirms remote cancellation. A 409 cancellation response means the task is still active and no refund occurred; keep polling it. This applies to submitted direct Suno, Producer, Vidu, and MV tasks today.

Lifecycle by example

POST  /producer/generate/music/compose
  -> Response: { taskId, status: "PENDING", creditsRequired: 28 }
     Balance immediately decreases by 28 credits.

GET   /tasks/{taskId} -> status: "PROCESSING"
GET   /tasks/{taskId} -> status: "COMPLETED"
                          { creditsRequired: 28, creditsCharged: 28 }
END

If the task fails before producing billable output:

{
  "taskId": "task_01H...",
  "status": "FAILED",
  "creditsRequired": 28,
  "creditsCharged": 0,
  "refunded": true,
  "errorCode": "PROVIDER_ERROR"
}

Insufficient / uninitialized balance

Status	code	When it happens
402	INSUFFICIENT_CREDITS	The quoted charge exceeds your available balance, or an MV/Vidu create quote exceeds the maxCredits cap you provided.
402	BALANCE_NOT_INITIALIZED	The account balance is not ready yet. Open the dashboard once, then retry.

For MV and Vidu, a maxCredits rejection happens before task creation and before any credit deduction. The error details include the final creditsRequired and the submitted maxCredits value.

When you get charged something on FAILED

Most failures are generation errors or validation errors. In those cases the task reports creditsCharged: 0 and refunded: true. The exception is partial output: if usable assets were generated but a later packaging step failed, the final task descriptor may show creditsCharged > 0. The descriptor’s errorMessage and resources fields indicate what, if anything, can still be used.

Reading balance and usage

For low-balance monitors and scheduled alerts, read the exact current balance:

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

{
  "balanceCredits": 42.5,
  "balanceUnits": "425000",
  "tier": "PREMIUM",
  "billingStatus": "ACTIVE",
  "updatedAt": "2026-08-05T08:00:00.000Z"
}

balanceUnits is the exact billing value represented as a string; one credit equals 10,000 units. billingStatus: "ON_HOLD" means paid task creation is blocked even if the numeric balance is positive. The endpoint requires usage:read for a restricted API key and returns Cache-Control: no-store.

The dashboard surfaces:

• Total purchased — sum of all packages bought
• Available balance — credits available for new requests
• Used credits — final charged credits across completed or partially billed tasks
• Refunded credits — credits returned after failures or cancellations
• Recent activity — task-level billing and usage history

For automated reporting, use GET /api/v1/usage/export with an API key that has usage-read access:

curl "https://api.omnapi.com/api/v1/usage/export?startDate=2026-07-01&endDate=2026-07-31&format=csv" \
  -H "x-api-key: $OMNAPI_KEY"

Query parameters:

Field	Required	Meaning
startDate	No	Inclusive ISO date/time lower bound. Defaults to 30 days before endDate.
endDate	No	Inclusive ISO date/time upper bound. Defaults to the current time.
apiKeyId	No	Restrict the export to one API key owned by the authenticated account. An ID not owned by the account returns an empty export.
format	No	json (default) or csv; takes precedence over the Accept header.

The default export format is JSON. Send format=csv or Accept: text/csv for a CSV stream. The date range defaults to the last 30 days when omitted and may span at most 366 days. Large exports are streamed, so clients should read the response incrementally.

JSON returns {"items":[...]}. CSV uses the same fields in the following fixed column order:

Field	Type	Meaning
id	string	Usage-record identifier.
apiKeyId	string	API key that made the request.
endpoint	string	Recorded request endpoint.
method	string	HTTP method.
statusCode	number	HTTP response status.
responseTimeMs	number	Recorded request latency in milliseconds.
creditsUsed	number	Credits attributed to the request.
ipAddress	string or null	Recorded caller IP address, when available.
userAgent	string or null	Recorded caller user agent, when available.
createdAt	ISO date-time	Usage-record creation time.

The CSV header is exactly id,apiKeyId,endpoint,method,statusCode,responseTimeMs,creditsUsed,ipAddress,userAgent,createdAt.

Use /api/v1/account/credits for automated balance alerts, the dashboard for interactive account review, and the usage export endpoint for reconciliation, invoices, and tenant-level back-office reporting.

Idempotency

Send an Idempotency-Key header on any paid create POST and a retried request replays the original response instead of charging twice — see The Task Model → Idempotency. Either way, never blindly re-POST after a network timeout without a key: the submission may have succeeded silently, so poll if you have a taskId, and only treat the request as un-submitted when you do not.

Credit cost transparency

You always see creditsRequired before the task runs. The dashboard and pricing catalog publish per-feature credit costs, and MV exposes quote and preflight endpoints for dynamic estimates. OmnAPI will not charge more than the create-time creditsRequired amount for a task. For MV and Vidu operations that support a budget guard, use maxCredits; Suno and Producer return the fixed operation price in the receipt and reject the unsupported field.