Skip to content

    API documentation

    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.

    1. Before buying credits, sign in and save the billing name, address, and tax details you want printed. Billing Information.
    2. 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.
    3. 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.

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

    PackageCreditsBase priceBase rate
    Starter3,500$10$0.002857 / credit
    Pro40,000$100$0.002500 / credit
    Enterprise500,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.

    Terminal window
    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.

    Fixed and free operations:

    Product lineOperationEndpoint / optionCredits
    LyricsStructured lyric packagePOST /api/v1/lyrics/generate8 standard; see Lyrics
    Audio EditingAudio renderPOST /api/v1/audio/renders5 standard per started output minute; see Audio Editing
    SubtitlesTiming extractionQuote, then POST /api/v1/subtitles/Dynamic; see Subtitles
    Suno storageLong-term ordinary audioExplicit storage subscription20 credits / GB-month for new subscriptions; existing accepted rates remain; see Storage
    Suno DirectSong generation with chirp-goose/songs with simple, custom, upload-extend, or upload-cover25
    Suno DirectSong generation with chirp-hawk or chirp-hawk-wild/songs with simple, custom, upload-extend, or upload-cover28
    Suno DirectPublic Voice generation/songs with vox25 with chirp-goose; 28 with either Pro model
    Suno DirectExisting-clip Extend or Cover/clips/{clipId}/derive25 with chirp-goose; 28 with either Pro model
    Suno DirectLyrics generation/lyrics, including paired candidates0
    Suno DirectReadsclip detail, batch clips, audio analysis, styles, Voice list/detail0
    Suno DirectAligned lyrics timelineGET /api/v1/suno/clips/:clipId/timeline1 standard; 0 for the legacy Suno 55,000 plan
    Suno DirectExplicit M4A export/clips/{clipId}/export with format=m4a1 standard; 0.9615 for legacy 52,000; 0 for legacy 55,000
    Suno DirectMP3 export/clips/{clipId}/export with format=mp32 standard; 1.9231 for legacy 52,000; 1.8182 for legacy 55,000
    Suno DirectManaged WAV export/clips/{clipId}/export with format=wav3 standard before customer pricing
    Suno DirectTwelve stems / named extractstemsMode=twelve / extract (98 native Suno names)140 / 56
    Suno DirectCreate public Voice from owned clipPOST /api/v1/suno/voices/from-clip5
    Suno DirectCreate verified public Voice from recordingsObtain a verification phrase, then POST /api/v1/suno/voices with both recordings66
    MVQuotePOST /api/v1/mv/quote0
    MVPreflightPOST /api/v1/mv/preflight0
    MV OmnQuotePOST /api/v2/mv/quotes0
    MV OmnVideo at 480p / 768p / 1080p / 1440pPOST /api/v2/mv/videos, or generation.engineVersion="omn-v1" on /api/v1/mv9 / 12 / 20 / 48 credits × effective seconds (10–600), including planning, reference images, captions and upscaling; no customer discounts
    MV OmnEdit quote, timeline, candidates, adoptPOST /api/v2/mv/videos/{id}/edits/quote, GET …/timeline, GET …/candidates, POST …/adopt0
    MV OmnRegenerate edit (new video)POST /api/v2/mv/videos/{id}/edits with action="regenerate", or a prompt scene edit on /api/v1/mvRate of the video’s resolution × seconds the regenerated shots are on screen (rounded up, at least 1) × candidates
    MV OmnRecut edit (new video)POST /api/v2/mv/videos/{id}/edits with action="recut"Rate of the video’s resolution × 10
    MV FastRecompose final after Fast scene editsPOST /api/v1/mv/{mvId}/finalizeDynamic; returned on the task receipt
    MV Studio BetaStoryboard + scene stillsPOST /api/v1/mv with mode="studio"250 + optional Visual Board add-on
    MV Studio BetaRegenerate scene imagePOST /api/v1/mv/{mvId}/scenes/{sceneIndex}/regenerate-image15
    MV Studio BetaFinalize selected scenesPOST /api/v1/mv/{mvId}/finalize50
    ViduQuotePOST /api/v1/vidu/quote0
    ViduVideo, image, audio, motion, template, and film tasksPOST /api/v1/vidu/tasksDynamic; 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.

    ModeResolution / add-onPublic formulaExample
    OneClick540pDynamic per-second pricingUse quote API
    OneClick720pDynamic per-second pricingUse quote API
    OneClick1080pDynamic per-second pricingUse quote API
    OneClickLip-syncDynamic per-second surchargeUse quote API
    Omn480p9 credits × billable seconds60s video: 540
    Omn768p12 credits × billable seconds60s video: 720
    Omn1080p (AI-upscaled)20 credits × billable seconds60s video: 1,200
    Omn1440p / 2K (AI-upscaled)48 credits × billable seconds60s video: 2,880
    OmnRegenerate editResolution rate × regenerated on-screen seconds (at least 1) × candidates768p, one 3.6 s shot, 2 candidates: 96
    OmnRecut editResolution rate × 10768p: 120
    OneClickRecompose final after scene editsDynamic recompose pricingReturned on task receipt
    Studio MVScene renderDynamic by selected render option, model, resolution, fps, and durationUse 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.

    Every task descriptor carries up to three credit fields:

    FieldSet whenMeaning
    creditsRequiredTask creationThe credit amount authorized and deducted to start the task.
    creditsChargedTask reaches a terminal stateThe final billed amount after completion, failure, cancellation, or partial output handling.
    refundedRefund indicatorTrue 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-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, Vidu, and MV tasks today.

    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 }
    END

    If the task fails before producing billable output:

    {
    "taskId": "task_01H...",
    "status": "FAILED",
    "creditsRequired": 28,
    "creditsCharged": 0,
    "refunded": true,
    "errorCode": "PROVIDER_ERROR"
    }
    StatuscodeWhen it happens
    402INSUFFICIENT_CREDITSThe quoted charge exceeds your available balance, or an MV/Vidu/Subtitle/Audio Editing create quote exceeds the maxCredits cap you provided.
    402BALANCE_NOT_INITIALIZEDThe 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.

    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.

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

    Terminal window
    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.

    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:

    Terminal window
    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:

    FieldRequiredMeaning
    startDateOptionalInclusive ISO date/time lower bound. Defaults to 30 days before endDate.
    endDateOptionalInclusive ISO date/time upper bound. Defaults to the current time.
    apiKeyIdOptionalRestrict the export to one API key owned by the authenticated account. An ID not owned by the account returns an empty export.
    formatOptionaljson (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:

    FieldTypeMeaning
    idstringUsage-record identifier.
    apiKeyIdstringAPI key that made the request.
    endpointstringRecorded request endpoint.
    methodstringHTTP method.
    statusCodenumberHTTP response status.
    responseTimeMsnumberRecorded request latency in milliseconds.
    creditsUsednumberCredits attributed to the request.
    ipAddressstring or nullRecorded caller IP address, when available.
    userAgentstring or nullRecorded caller user agent, when available.
    createdAtISO date-timeUsage-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.

    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.

    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.

    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.