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 60-credit trial in Account access and trial. Verified Gmail accounts normally qualify without a manual review. Other verified accounts can also claim a trial; some may need an additional verification or a review. Your existing trial grant keeps its original amount.
Trial credits cover eligible song generation, lyrics, and subtitle tasks. Check your remaining trial credits on the trial page. Purchased credits can fund other features and follow the ordinary task limits.
Invoices and receipts
Section titled “Invoices and receipts”- Before buying credits, sign in and save the billing name, address, and tax details you want printed. Billing Information.
- After a Stripe payment is captured, open Invoices & Receipts and select Download PDF. Manually issued invoices and receipts appear in the same list. When a document has a supporting file, use Attachment to download it. Open billing documents.
- To correct an issued document, send its document number (or record ID for an older document) and the fields to change to OmnAPI support. Updating your billing profile applies to future documents. After support confirms a correction, download the current PDF again.
The amount and payment status describe the billing document. For credits spent on individual jobs, use the balance and usage report.
Credit value
Section titled “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.
Suno remaster-music costs 28 standard credits across supported models.
Customer contract ratios still apply; already purchased Tasks keep their saved
price. Check the current catalog before authorizing a new remaster.
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, Subtitle, and Audio Editing creates; Suno does 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 Music Video price
card: credits per output second for each delivery resolution you can buy
(grouped under renderTiers for compatibility) and the minimum billed seconds.
Its centerEdit price card gives the regenerate minimum billed seconds, default
attribute-edit candidate count, maximum candidates and recut billed seconds.
Use POST /api/v2/mv/videos/{id}/edits/quote for the price and availability of a
specific edit. Its economySchedule, sceneEdit, upgrade and recomposition fields apply only
to Omn MVs bought before November 12, 2026. See
Music Video pricing. updatedAt is the catalog’s effective date, and version
changes whenever the catalog content changes.
Current price table
Section titled “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 |
| Audio Editing | Audio render | POST /api/v1/audio/renders | 5 standard per started output minute; see Audio Editing |
| Subtitles | Timing extraction | Quote, then POST /api/v1/subtitles/ | Dynamic; see Subtitles |
| Suno storage | Long-term ordinary audio | Explicit storage subscription | 20 credits / GB-month for new subscriptions; existing accepted rates remain; see Storage |
| 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 Omn | Quote | POST /api/v2/mv/quotes | 0 |
| MV Omn | Video at 480p / 768p / 1080p / 1440p | POST /api/v2/mv/videos, or generation.engineVersion="omn-v1" on /api/v1/mv | 9 / 12 / 20 / 48 credits × effective seconds (10–600), including planning, reference images, captions and upscaling; no customer discounts |
| MV Omn | Edit quote, timeline, candidates, adopt | POST /api/v2/mv/videos/{id}/edits/quote, GET …/timeline, GET …/candidates, POST …/adopt | 0 |
| MV Omn | Regenerate edit (new video) | POST /api/v2/mv/videos/{id}/edits with action="regenerate", or a prompt scene edit on /api/v1/mv | Rate of the video’s resolution × seconds the regenerated shots are on screen (rounded up, at least 1) × candidates |
| MV Omn | Recut edit (new video) | POST /api/v2/mv/videos/{id}/edits with action="recut" | Rate of the video’s resolution × 10 |
| 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 |
Music Video models: Omn uses /api/v2/mv (or /api/v1/mv with
generation.engineVersion="omn-v1"); OneClick uses /api/v1/mv. OneClick Turbo is
retired and no longer sells. See Music Video pricing.
Dynamic OneClick pricing depends on duration, resolution, quality, lip-sync,
add-ons, recompose pricing, and selected Studio rendering options; call
POST /api/v1/mv/quote (or preflight) before creating or rendering. Omn orders
have no per-request add-ons; their price depends only on the delivery resolution
and effective duration, and POST /api/v2/mv/quotes returns the exact amount.
An Omn edit is a separate purchase of a new video, quoted by
POST /api/v2/mv/videos/{id}/edits/quote; a failed or cancelled edit is refunded
in full and the original video’s charge does not change. See
Edit an Omn video.
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 |
|---|---|---|---|
| OneClick | 540p | Dynamic per-second pricing | Use quote API |
| OneClick | 720p | Dynamic per-second pricing | Use quote API |
| OneClick | 1080p | Dynamic per-second pricing | Use quote API |
| OneClick | Lip-sync | Dynamic per-second surcharge | Use quote API |
| Omn | 480p | 9 credits × billable seconds | 60s video: 540 |
| Omn | 768p | 12 credits × billable seconds | 60s video: 720 |
| Omn | 1080p (AI-upscaled) | 20 credits × billable seconds | 60s video: 1,200 |
| Omn | 1440p / 2K (AI-upscaled) | 48 credits × billable seconds | 60s video: 2,880 |
| Omn | Regenerate edit | Resolution rate × regenerated on-screen seconds (at least 1) × candidates | 768p, one 3.6 s shot, 2 candidates: 96 |
| Omn | Recut edit | Resolution rate × 10 | 768p: 120 |
| OneClick | Recompose final after 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 Turbo no longer accepts purchases (422 MV_ENGINE_UNSUPPORTED,
turbo_retired). Turbo videos bought earlier keep their recorded charges and
refunds.
The task credit fields
Section titled “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 | Refund indicator | True for full-refund settlement or a settled reduction from the original charge, including a successful Task with a partial refund. It does not distinguish full from partial refund; use settled amounts for accounting. |
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. A historical Omn order with a
separately purchased subtitle component can receive a subtitle-only refund
while remaining COMPLETED and reporting refunded: true. New bundle orders
have no separate subtitle charge to refund. Check the operation
settlementStatus, refundedCredits and netCredits on the video’s charges
(GET /api/v2/mv/videos/{id}/charges, or GET /api/v1/mv/{mvId}/operations);
example.
Normal terminal transitions settle the charge and any eligible refund together.
For an older or recovery record still reporting settlementStatus: "PENDING",
do not infer a completed refund from execution status alone. Continue bounded
settlement checks and retain the receipt for reconciliation.
Customer pricing and settlement rounding
Section titled “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) * billingIncrementCreditsCommercial 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,
Vidu, and MV tasks today.
Lifecycle by example
Section titled “Lifecycle by example”POST /suno/songs -> 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 }ENDIf the task fails before producing billable output:
{ "taskId": "task_01H...", "status": "FAILED", "creditsRequired": 28, "creditsCharged": 0, "refunded": true, "errorCode": "PROVIDER_ERROR"}Insufficient / uninitialized balance
Section titled “Insufficient / uninitialized balance”| Status | code | When it happens |
|---|---|---|
402 | INSUFFICIENT_CREDITS | The quoted charge exceeds your available balance, or an MV/Vidu/Subtitle/Audio Editing 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, Subtitles, and Audio Editing, a maxCredits rejection happens before task creation and
before any credit deduction. The error details include the final
creditsRequired and the submitted maxCredits value; MV rejections also
report reason: "MAX_CREDITS_EXCEEDED". MV creates sent through
POST /api/v1/tasks or /tasks/sync enforce an optional MV quoteId and
maxCredits like POST /api/v1/mv; see MV charge authorization.
When you get charged something on FAILED
Section titled “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
Section titled “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
Section titled “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 to reconcile API activity by tenant.
Idempotency
Section titled “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
Section titled “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 return the fixed
operation price in the receipt and reject the unsupported field.
Monthly resource storage
Section titled “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. New subscriptions cost 20 credits per decimal GB-month (30 days). Existing subscriptions keep their accepted rate, including after re-enabling or upgrading from Suno-only storage. Read your account’s applicable rate and bills from /api/v1/storage and /api/v1/storage/charges. Generation charges remain separate.