> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toapis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pricing and Actual Charges

> List the prices available to an API key and read confirmed charges from generation responses

> [!NOTE]
>
> **Note for users in mainland China:** Use `https://toapis.cn` as the Base URL. Replace `https://toapis.com` with `https://toapis.cn` in the examples below.

Use `GET /v1/pricing` to list the image and video rates currently available to your API key. The response includes customer-specific fixed prices or discounts and the effective group price.

This endpoint returns a rate catalog, not a quote for one generation. It does not reserve or lock a price, and it does not estimate the total charge from a generation request.

## Authorization

**Authorization** `string` *required*

A generation API key in the form `Bearer YOUR_API_KEY`.

## Query parameters

**model** `string`

Exact model ID. Omit it to list all available image and video models.

**type** `string`

Filter by `image` or `video`.

**limit** `integer` (default: 100)

Number of models to return. The allowed range is `1` to `100`.

**after** `string`

Pagination cursor from `next_after` in the previous response.

Seedance regional variants use separate model IDs. For example, query `seedance-2-5`, `seedance-2-5-cn`, or `seedance-2-5-global` with `model`. There is no separate region query parameter.

```bash cURL theme={null}
curl --request GET \
  --url 'https://toapis.com/v1/pricing?model=seedance-2-5' \
  --header 'Authorization: Bearer <token>'
```

```json 200 theme={null}
{
  "object": "list",
  "currency": "USD",
  "data": [
    {
      "id": "seedance-2-5",
      "type": "video",
      "prices": [
        {
          "group": "default",
          "conditions": {
            "resolution": "720p",
            "has_video_input": false
          },
          "charge_type": "per_token",
          "price_basis": "total_tokens",
          "unit": "1m_tokens",
          "unit_price": "4"
        }
      ]
    }
  ],
  "has_more": false,
  "next_after": ""
}
```

The values above illustrate the response shape. Use the values returned for your API key as the applicable catalog.

## Price fields

**currency** `string`

Price currency. Currently `USD`.

**object** `string`

Object type. Always `list`.

**data** `array`

Available model entries. Each entry contains the exact model `id`, its `type`, and zero or more `prices`.

**has\_more** `boolean`

Whether another page is available.

**next\_after** `string`

Cursor for the next request. Empty when `has_more` is `false`.

**prices\[].group** `string`

The routing group for which the price applies. An API key configured for automatic group selection may receive more than one group.

**prices\[].conditions** `object`

Conditions under which the price applies, including model defaults when they affect pricing. Match these values to the generation request.

**prices\[].charge\_type** `string`

`per_request`, `per_second`, or `per_token`.

**prices\[].price\_basis** `string`

Billing basis: `request`, `output_seconds`, `total_tokens`, or `text_input_tokens`.

**prices\[].unit** `string`

Price unit: `request`, `second`, or `1m_tokens`.

**prices\[].unit\_price** `string`

Effective unit price in USD as a decimal string. Customer pricing and the group ratio are already included; do not multiply the group ratio again.

A price may also include `input_unit_price`, `input_image_unit_price`, `free_input_image_count`, `minimum_charge_usd`, or `image_token_prices`. Time-based pricing may include `pricing_period`, `pricing_timezone`, `pricing_schedule_version`, and `pricing_peak_windows`.

For image token pricing, `image_token_prices` can contain `text_input`, `cached_text_input`, `image_input`, `cached_image_input`, and `image_output`. Every amount is USD per 1 million tokens.

Only prices backed by at least one enabled channel candidate compatible with the listed conditions are returned. This check does not reserve a route or test live channel health. A model can still be returned with an empty `prices` array when the service cannot publish a complete rate safely. An empty array or a missing entry does not mean the model is free.

## Actual charge fields

When a charge can be confirmed, generation responses use this object:

```json theme={null}
{
  "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}`
* 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 saved billing records for this task. Fixed charges use quantities confirmed at creation; deferred settlement uses final settled quantities. Usage is not inferred from current prices or amounts. `per_request` uses `requests`, `per_second` uses `output_seconds`, and `per_token` uses `billed_tokens`. Billable input video and image extras are included when needed and omitted when zero.

Historical tasks that saved only amounts without verifiable quantities omit the unconfirmed fields. Missing token details are not filled with zeros. After per-token settlement, video token breakdowns are retained only when the reported total matches the final billed count. `usage` and `billing` are independently available: missing usage does not mean no charge and does not prevent results from being returned. Conversely, whenever billing quantities such as `charge_type` are returned, `billing.status=settled` and the actual amount are returned as well. Fixed-charge tasks charged once at submission also return `settled`. Task queries and Webhooks use the same confirmation rules and field values.

## Errors

| Status | Code | Meaning |
| - | - | - |
| `400` | `invalid_request_error` | Unsupported query parameter or invalid `type` or `limit` |
| `401` / `403` | varies | The API key is invalid, expired, restricted, or not allowed to use the requested account or group |
| `404` | `model_not_found` | The exact model is not available to this API key |
| `503` | `pricing_unavailable` | Customer pricing cannot be loaded safely; no public-price fallback is used |

Responses use `Cache-Control: private, no-store`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.