Actual cost and task usage
Actual cost semantics for billing and usage fields on generation tasks
The pricing catalog reflects current rates. Actual charges are determined by generation responses, task queries, Webhooks, and usage records.
Model pricing and account usage are two different measures, so do not derive historical charges from current prices.
Actual charge fields
When a charge can be confirmed, generation responses use this object:
{
"billing": {
"status": "settled",
"credits": "100",
"cost_usd": "0.5"
}
}| Field | Meaning |
|---|---|
status | pending, settled, or refunded |
credits | Confirmed ToAPIs Credits consumed, returned as a decimal string |
cost_usd | The same confirmed charge in USD, returned as a decimal string |
pending means the final amount is not available yet, so amount fields are omitted. refunded means the confirmed net charge is zero. A missing billing object means the platform could not confirm a safe public value; it does not mean the request was free.
The object may appear in:
- Unified image and video task queries
GET /v1/tasks/{task_id} - async image task queries at
GET /v1/images/generations/{task_id} - async video task queries at
GET /v1/videos/generations/{task_id}(alsoGET /v1/video/generations/{task_id}andGET /v1/videos/{task_id}) - Task Webhooks as
data.billing - compatible non-streaming synchronous image generation or edit responses as top-level
billing
For asynchronous work, use the task query after completion as the fallback source of the final charge. Streaming image responses, unsupported provider response formats, Playground requests, and deferred batch billing may omit the object.
Task usage fields
Image and video task queries return confirmed billing quantities in top-level usage. Successful Webhooks use the same definitions in data.usage. Billing quantities, reported model tokens, and tool counts can coexist; each is returned when available.
| Field | Type | Description |
|---|---|---|
charge_type | string | Billing mode: per_request, per_second, or per_token |
requests | integer | Billed request units. The ordinary image request parameter n does not directly multiply this count; an effective Midjourney video batch_size is included |
billed_tokens | integer | Token count used for pricing. Some image paths use a configured precharge token basis, which may differ from actual provider generation tokens |
output_seconds | integer | Billed output video duration in integer seconds |
input_seconds | integer | Billed input video duration in integer seconds |
input_images | integer | Billed input images after the free allowance |
input_tokens, output_tokens, prompt_tokens, completion_tokens, total_tokens | integer | Nonnegative integer token details reported by video models. Only available provider fields are returned; confirmed per-token settlement can supply total_tokens |
tool_usage | object | Tool counts, potentially including web_search, image_search, and grounding_queries; available fields are independent of token details |
Billing quantities come from the task’s saved billing records: fixed charges use the quantity confirmed at creation and deferred settlement uses the final settled quantity. Usage is not derived from current prices or amounts.
per_request uses requests, per_second uses output_seconds, and per_token uses billed_tokens. Add-on items such as input video duration and input images are returned when present and omitted when zero.
Historical tasks that saved only amounts without verifiable quantities omit the unconfirmable fields, and missing token details are not filled with zeros. After per-token settlement, video token breakdowns are kept only when the reported total matches the final billed quantity.
usage and billing availability are independent: missing usage does not mean no charge and does not block the result, while any returned billing quantity such as charge_type always comes with billing.status=settled and the actual amount.
Fixed-charge tasks fully deducted at submission also return settled. Task queries and Webhooks use the same confirmation conditions and field values.