Credits & Billing

OmnAPI bills in credits. You purchase credit packages from the dashboard; each task spends a model-specific number of credits. Failures refund automatically. Credits never expire within two years of purchase.

The three numbers

Every task descriptor carries up to three credit fields:

Field	Set when	Meaning
creditsRequired	Task creation	The maximum amount reserved from your balance. Locked until the task settles.
creditsCharged	Task reaches COMPLETED or FAILED	The actual amount debited. May be <= creditsRequired.
unitPrice, currency	Same	The applied rate at settlement (USD by default).
refunded	If FAILED or partial	true if any reserved credits were returned.

Lifecycle by example

POST  /producer/generate/music/compose
  ─► Response: { id, status: "PENDING", creditsRequired: 80 }
     │
     │  → balance shows: total=1000, reserved=80, available=920
     │
GET   /tasks/{id}                       ─► status: "PROCESSING"
GET   /tasks/{id}                       ─► status: "COMPLETED"
                                          { creditsRequired: 80, creditsCharged: 78 }
     │
     │  → balance shows: total=1000-78=922, reserved=0, available=922
     │     (2 credits returned because final asset was shorter than budget)
     │
END

If the task had failed:

GET /tasks/{id} ─► status: "FAILED",
                   creditsRequired: 80,
                   creditsCharged: 0,
                   refunded: true,
                   errorCode: "PROVIDER_ERROR"

When you get charged something on FAILED

Most failures are upstream provider errors or validation errors — in both cases creditsCharged: 0 and refunded: true. The exception is partial output scenarios: if the provider returned usable bytes but the postprocessor failed afterward, you may see creditsCharged > 0 on a FAILED task. The descriptor’s errorMessage and resources fields tell you what was salvageable.

Reading the balance

The dashboard surfaces:

• Total purchased — sum of all packages bought
• Reserved — sum of creditsRequired across PENDING + PROCESSING tasks
• Available — what new requests can spend
• Recent activity — task-level audit trail

A future endpoint will expose balance via the public API — track Changelog.

Idempotency

We do not currently support an Idempotency-Key header. Retry logic on the client must use status polling — never re-POST a task because the network call timed out. The submission may have succeeded silently; polling will tell you. If you don’t have an id, treat the request as un-submitted and retry safely.

Credit cost transparency

You always see creditsRequired before the task runs. The dashboard publishes the per-feature credit cost table — image vs lyrics vs short-music vs long-music differ substantially. The gateway never charges more than what creditsRequired reserved.

What’s coming

• Pay-as-you-go invoicing for high-volume customers
• Public balance/usage API
• Idempotency-Key header
• Granular cost report per task

See the Changelog for delivery dates.