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 website accounts start with zero credits. Eligible accounts can claim a one-time 100-credit trial after verifying their email, subject to trial availability. Signing in alone does not grant credits. Existing accounts and purchased-credit allowances retain their previous behavior. Trial-only accounts have a limited feature set and separate task limits.

Credit value

Published top-up packages (base price before checkout fees):

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

Checkout can add a platform fee. The displayed checkout total is the amount payable; the base rates above exclude that fee. For a cost comparison, divide the actual amount paid by the credits purchased. See current packages and checkout pricing.

Product pricing is published in OmnAPI credits. Suno song generation with chirp-goose costs 25 OmnAPI credits; chirp-hawk and chirp-hawk-wild generation requests cost 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 Vidu, and Subtitle 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. Its mvOmnV1 section is the Omn V1 Music Video price card: credits per output second for each render tier and delivery resolution, the minimum billed seconds, the economy schedule and the shot-edit, upgrade and recomposition rules. See Read the price card for its fields. updatedAt is the catalog’s effective date, and version changes whenever the catalog content changes.

Current price table

Fixed and free operations:

Product line	Operation	Endpoint / option	Credits
Lyrics	Structured lyric package	POST /api/v1/lyrics/generate	8 standard; see Lyrics
Subtitles	Timing extraction	Quote, then POST /api/v1/subtitles/	Dynamic; see Subtitles
Suno storage	Long-term ordinary audio	Explicit storage subscription	Published rate when available; see Storage
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-goose	/songs with simple, custom, upload-extend, or upload-cover	25
Suno Direct	Song generation with chirp-hawk or chirp-hawk-wild	/songs with simple, custom, upload-extend, or upload-cover	28
Suno Direct	Public Voice generation	/songs with vox	25 with chirp-goose; 28 with either Pro model
Suno Direct	Existing-clip Extend or Cover	/clips/{clipId}/derive	25 with chirp-goose; 28 with either Pro model
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	Explicit M4A export	/clips/{clipId}/export with format=m4a	1 standard; 0.9615 for legacy 52,000; 0 for legacy 55,000
Suno Direct	MP3 export	/clips/{clipId}/export with format=mp3	2 standard; 1.9231 for legacy 52,000; 1.8182 for legacy 55,000
Suno Direct	Managed WAV export	/clips/{clipId}/export with format=wav	3 standard before customer pricing
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 OneClick V2	perform create	managedVersion="premium-v2", performanceMode="perform"	Standard public rate: 42 OmnAPI credits / second
MV OneClick V2	sing, sing_perform, or dance create	Explicit OneClick V2 mode at 720p	Standard public rate: 48 OmnAPI credits / second
MV Omn V1 (pilot)	Fast create by render tier	generation.engineVersion="omn-v1"	6–68 credits / output second by tier and resolution, 10-second minimum; read mvOmnV1 in the catalog
MV Omn V1 (pilot)	Shot edit / render-tier upgrade	POST /api/v1/mv/{mvId}/scenes/{sceneIndex}/render / POST /api/v1/mv/{mvId}/upgrade	Tier price × billed seconds; see Omn V1 edits and upgrades
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
OneClick V2	perform, fixed 720p	21 Vidu credits/second × 2 OmnAPI credits/Vidu credit	60s standard example: 2,520
OneClick 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.

OneClick 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/Subtitle 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, Vidu, and Subtitles, 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 by payment review or payment reversal debt, even if the numeric balance is positive. The endpoint requires usage:read for a restricted API key and returns Cache-Control: no-store.

Payment review and billing holds

A card authorization or pending payment does not by itself make credits available. Where card payments are offered, use the confirmed balance and billing status after processing completes. Pending refunds, disputes, and reconciliation of a payment can keep an account on hold while the payment is reviewed. A restored balance does not necessarily mean that the review has ended.

While billingStatus is ON_HOLD, stop creating paid tasks and follow the payment status in the dashboard or contact support. Paid creation returns 403 FORBIDDEN. For compatibility, details.reason may be PAYMENT_REVERSAL_DEBT even when paymentDebtCredits is 0; use the billing status rather than interpreting that reason as proof of a positive debt. Do not repeatedly retry the same blocked payment.

Task refunds and payment refunds are different: task refunds adjust credits; payment refunds follow the payment’s status. Check the completed account update before assuming either restored spending capacity.

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	Optional	Inclusive ISO date/time lower bound. Defaults to 30 days before endDate.
endDate	Optional	Inclusive ISO date/time upper bound. Defaults to the current time.
apiKeyId	Optional	Restrict the export to one API key owned by the authenticated account. An ID not owned by the account returns an empty export.
format	Optional	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. Poll a returned taskId. Without a receipt, the outcome is unknown: recover with the original route, body, and saved key. Never infer that no task was created merely because no task ID reached you.

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, Vidu, and Subtitle operations that support a budget guard, use maxCredits; Suno and Producer return the fixed operation price in the receipt and reject the unsupported field.

Monthly resource storage

Optional long-term resource storage combines final files across products into one monthly credit charge based on actual size and storage time after included retention. An administrator must explicitly enroll the account; existing users are disabled by default. Read the accepted rate and bills from /api/v1/storage and /api/v1/storage/charges. Generation charges remain separate.