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

# 料金と実際の請求額

> API Keyで利用できる料金と、生成レスポンスで確定した請求額を確認します

<Note>
  中国本土から利用する場合は、Base URLに `https://toapis.cn` を使用してください。以下の例の `https://toapis.com` を `https://toapis.cn` に置き換えます。
</Note>

`GET /v1/pricing` は、現在のAPI Keyで利用できる画像・動画モデルの料金を返します。顧客別の固定価格または割引と、有効なグループ価格はすでに反映されています。

このエンドポイントが返すのは料金カタログです。1 回の生成に対する見積もりではありません。価格の予約や固定、生成パラメータからの合計金額の計算は行いません。

## 認証

<ParamField header="Authorization" type="string" required>
  生成API Keyを `Bearer YOUR_API_KEY` の形式で指定します。
</ParamField>

## クエリパラメータ

<ParamField query="model" type="string">
  完全一致のモデルID。省略すると、利用可能な画像・動画モデルをすべて返します。
</ParamField>

<ParamField query="type" type="string">
  `image` または `video` で絞り込みます。
</ParamField>

<ParamField query="limit" type="integer" default="100">
  返すモデル数。`1` から `100` まで指定できます。
</ParamField>

<ParamField query="after" type="string">
  前回のレスポンスの `next_after` をページネーションカーソルとして指定します。
</ParamField>

Seedanceの地域別バリアントには個別のモデルIDがあります。たとえば `model` に `seedance-2-5`、`seedance-2-5-cn`、`seedance-2-5-global` を指定します。地域専用のクエリパラメータはありません。

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

上記の金額はレスポンス形式の例です。現在のAPI Keyに対して返された値を利用してください。

## 料金フィールド

<ResponseField name="currency" type="string">
  料金の通貨。現在は `USD` です。
</ResponseField>

<ResponseField name="object" type="string">
  オブジェクトの種類。常に `list` です。
</ResponseField>

<ResponseField name="data" type="array">
  利用可能なモデル。各項目には完全一致のモデル `id`、`type`、0 件以上の `prices` が含まれます。
</ResponseField>

<ResponseField name="has_more" type="boolean">
  次のページがあるかどうかを示します。
</ResponseField>

<ResponseField name="next_after" type="string">
  次のリクエストで使うカーソル。`has_more` が `false` の場合は空文字列です。
</ResponseField>

<ResponseField name="prices[].group" type="string">
  料金が適用されるルーティンググループ。API Keyが自動グループ選択を使用する場合、複数のグループが返ることがあります。
</ResponseField>

<ResponseField name="prices[].conditions" type="object">
  料金が成立する条件。料金に影響するモデルの既定値も含まれます。生成リクエストをこの値に合わせてください。
</ResponseField>

<ResponseField name="prices[].charge_type" type="string">
  `per_request`、`per_second`、または `per_token`。
</ResponseField>

<ResponseField name="prices[].price_basis" type="string">
  課金基準。`request`、`output_seconds`、`total_tokens`、または `text_input_tokens`。
</ResponseField>

<ResponseField name="prices[].unit" type="string">
  料金単位。`request`、`second`、または `1m_tokens`。
</ResponseField>

<ResponseField name="prices[].unit_price" type="string">
  USD建ての有効な単価を10進文字列で返します。顧客別料金とグループ倍率は反映済みです。グループ倍率を再度掛けないでください。
</ResponseField>

料金には `input_unit_price`、`input_image_unit_price`、`free_input_image_count`、`minimum_charge_usd`、`image_token_prices` が含まれる場合があります。時間帯別料金では `pricing_period`、`pricing_timezone`、`pricing_schedule_version`、`pricing_peak_windows` が含まれる場合があります。

画像トークン料金の `image_token_prices` には、`text_input`、`cached_text_input`、`image_input`、`cached_image_input`、`image_output` が含まれます。各金額の単位は100万トークンあたりのUSDです。

記載された条件と互換性がある有効な候補チャネルが1つ以上存在する料金だけを返します。この確認ではルートを予約せず、チャネルのリアルタイムな正常性も検査しません。安全に完全な料金を公開できない場合、モデルの `prices` は空になることがあります。空の配列や料金項目の欠落は、無料であることを意味しません。

## 実際の請求額

請求額を確認できる場合、生成レスポンスには次のオブジェクトが含まれます。

```json theme={null}
{
  "billing": {
    "status": "settled",
    "credits": "100",
    "cost_usd": "0.5"
  }
}
```

| フィールド      | 意味                                 |
| ---------- | ---------------------------------- |
| `status`   | `pending`、`settled`、または `refunded` |
| `credits`  | 確定したToAPIs Creditsの消費量。10進文字列      |
| `cost_usd` | 同じ確定済み請求のUSD金額。10進文字列              |

`pending` は最終金額が未確定であることを示し、金額フィールドは省略されます。`refunded` は確定した純請求額がゼロであることを示します。`billing` 全体がない場合は、安全に公開できる値を確認できなかったことを示します。無料という意味ではありません。

このオブジェクトは次の場所に含まれる場合があります。

* 非同期画像タスク照会 `GET /v1/images/generations/{task_id}`
* 非同期動画タスク照会 `GET /v1/videos/generations/{task_id}`
* Task Webhookの `data.billing`
* 対応する非ストリーミング同期画像生成・編集レスポンスのトップレベル `billing`

非同期処理では、完了後のタスク照会を最終請求額のフォールバックとして使用してください。ストリーミング画像レスポンス、未対応のプロバイダーレスポンス形式、Playground、遅延バッチ課金では省略される場合があります。

## エラー

| ステータス         | コード                     | 意味                                           |
| ------------- | ----------------------- | -------------------------------------------- |
| `400`         | `invalid_request_error` | 未対応のクエリパラメータ、または無効な `type` / `limit`         |
| `401` / `403` | 状況により異なる                | API Keyが無効、期限切れ、制限対象、または対象のアカウント・グループを利用できない |
| `404`         | `model_not_found`       | 完全一致のモデルIDをこのAPI Keyで利用できない                  |
| `503`         | `pricing_unavailable`   | 顧客別料金を安全に取得できない。公開価格へのフォールバックは行わない           |

レスポンスには `Cache-Control: private, no-store` が設定されます。