> ## 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.
</Note>

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

<ParamField header="Authorization" type="string" required>
  A generation API key in the form `Bearer YOUR_API_KEY`.
</ParamField>

## Query parameters

<ParamField query="model" type="string">
  Exact model ID. Omit it to list all available image and video models.
</ParamField>

<ParamField query="type" type="string">
  Filter by `image` or `video`.
</ParamField>

<ParamField query="limit" type="integer" default="100">
  Number of models to return. The allowed range is `1` to `100`.
</ParamField>

<ParamField query="after" type="string">
  Pagination cursor from `next_after` in the previous response.
</ParamField>

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.

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

<ResponseExample>
  ```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": ""
  }
  ```
</ResponseExample>

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

## Price fields

<ResponseField name="currency" type="string">
  Price currency. Currently `USD`.
</ResponseField>

<ResponseField name="object" type="string">
  Object type. Always `list`.
</ResponseField>

<ResponseField name="data" type="array">
  Available model entries. Each entry contains the exact model `id`, its `type`, and zero or more `prices`.
</ResponseField>

<ResponseField name="has_more" type="boolean">
  Whether another page is available.
</ResponseField>

<ResponseField name="next_after" type="string">
  Cursor for the next request. Empty when `has_more` is `false`.
</ResponseField>

<ResponseField name="prices[].group" type="string">
  The routing group for which the price applies. An API key configured for automatic group selection may receive more than one group.
</ResponseField>

<ResponseField name="prices[].conditions" type="object">
  Conditions under which the price applies, including model defaults when they affect pricing. Match these values to the generation request.
</ResponseField>

<ResponseField name="prices[].charge_type" type="string">
  `per_request`, `per_second`, or `per_token`.
</ResponseField>

<ResponseField name="prices[].price_basis" type="string">
  Billing basis: `request`, `output_seconds`, `total_tokens`, or `text_input_tokens`.
</ResponseField>

<ResponseField name="prices[].unit" type="string">
  Price unit: `request`, `second`, or `1m_tokens`.
</ResponseField>

<ResponseField name="prices[].unit_price" type="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.
</ResponseField>

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:

* 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.

## 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`.