Get model pricing | ToAPIs Documentation

GET

/api/v1/pricing

Note for users in mainland China: Please use https://api.toapis.cn as the API endpoint (Base URL). Replace https://api.toapis.com with https://api.toapis.cn in the examples in this document.

Behavior

Returns the model pricing catalog available to the current account, including each model's billing mode and unit price. Pass api_key_id to view the catalog from a specific key's perspective.

It shares the same catalog computation as the legacy GET /v1/pricing, but authentication, parameters, and response structure differ. The catalog reflects current rates — it is not a quote for a generation request and cannot be used to estimate totals or lock prices.

Actual charges are documented in actual cost and task usage.

The pricing region comes from the account. region, group, after, and generation parameters are not accepted, and if the account currently has no effective pricing region it returns 503, and that empty result is not saved as the account’s pricing-region configuration.

The account view uses the account’s effective base group. api_key_id additionally applies the target key’s group and model restrictions. A target key that is deleted, owned by someone else, or scoped returns 404, and an unavailable group returns 403 (code=13003).

meta.key_status only reports the target key’s configured state, not its current usability.

The full catalog skips models without confirmed prices, and a missing price does not mean free.

When querying a specific model: outside the visible catalog returns 404 (code=16008), visible but without confirmed pricing returns 503 (code=18029), and catalog dependency failures return 503 (code=18028).

Configuration changes can invalidate cursors, and a single pagination pass does not guarantee a consistent price snapshot.

Authentication

Authorizationstringheaderrequired

Use Bearer YOUR_SYSTEM_ACCESS_TOKEN. Model keys are not accepted and X-User-Id is not required. See access rules.

Request parameters

api_key_idstringquery

Optional owned, undeleted ordinary key context. Omission uses account configuration. Disabled, expired, or exhausted keys can expose configuration pricing without being callable.

modelstringquery

Exact model ID, at most 255 bytes.

typestringquery

Model type: image, video, or audio.

limitintegerquerydefault: 100

Page size, default 100, range 1-100.

cursorstringquery

Previous next_cursor, at most 2048 bytes. Restart after changing filters or pricing context.

Request examples

requestExample

curl --request GET \
  --url 'https://api.toapis.com/api/v1/pricing?type=image&limit=20' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'

import requests

response = requests.get(
    "https://api.toapis.com/api/v1/pricing",
    headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
    params={"type": "image", "limit": "20"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.toapis.com/api/v1/pricing?type=image&limit=20", {
  method: "GET",
  headers: { Authorization: "Bearer YOUR_SYSTEM_ACCESS_TOKEN" },
  signal: AbortSignal.timeout(30_000),
});
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.json());

Response fields

Examples use fictitious data. See Access for response envelopes and errors.

data.itemsarray

Model items containing id, type, and prices.

data.meta.currencystring

Currency, always USD.

data.meta.contextstring

Pricing context: account or api_key.

data.meta.api_key_idstring | null

Target key ID, null for account context.

data.meta.key_statusstring | null

Target key status, null for account context.

data.meta.regionstring

Effective account region: cn or global.

data.has_moreboolean

Whether another page exists.

data.next_cursorstring | null

Next cursor, null on the final page.

prices[].groupstring

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

prices[].conditionsobject

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

prices[].charge_typestring

per_request, per_second, or per_token.

prices[].price_basisstring

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

prices[].unitstring

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

prices[].unit_pricestring

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.

Response examples

responseExample

{
  "code": 0,
  "message": "",
  "data": {
    "items": [
      {
        "id": "example-image-model",
        "type": "image",
        "prices": [
          {
            "charge_type": "per_request",
            "unit": "request",
            "unit_price": "0.05",
            "price_basis": "request",
            "group": "default",
            "conditions": {
              "size": "1024x1024"
            }
          }
        ]
      }
    ],
    "has_more": false,
    "next_cursor": null,
    "meta": {
      "currency": "USD",
      "context": "account",
      "api_key_id": null,
      "key_status": null,
      "region": "global"
    }
  }
}