> ## 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>
  中國大陸使用者請使用 `https://toapis.cn` 作為 Base URL，並將下方範例中的 `https://toapis.com` 替換為 `https://toapis.cn`。
</Note>

使用 `GET /v1/pricing` 查詢目前 API Key 可用的圖片與影片費率。回應已包含客戶固定價格或折扣，以及生效的群組價格。

此介面回傳價格目錄，不是單次生成請求的報價。它不會預留或鎖定價格，也不會根據生成參數估算總費用。

## 驗證

<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` 和零個或多個 `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 生效單價。此價格已包含客戶價格和群組倍率，不要再次乘上群組倍率。
</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`。

圖片 token 計價中的 `image_token_prices` 可包含 `text_input`、`cached_text_input`、`image_input`、`cached_image_input` 和 `image_output`。每項金額單位均為每 100 萬 tokens 的 USD 價格。

目錄只回傳至少有一個已啟用候選渠道與所列條件相容的價格。此檢查不會預留路由，也不會探測渠道即時健康狀態。服務無法安全確認完整費率時，模型仍可能回傳，但 `prices` 為空。空陣列或缺少某項價格不代表模型免費。

## 實際費用欄位

費用可以確認時，生成回應使用以下物件：

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

| 欄位         | 含義                               |
| ---------- | -------------------------------- |
| `status`   | `pending`、`settled` 或 `refunded` |
| `credits`  | 已確認消耗的 ToAPIs Credits，以十進位字串回傳   |
| `cost_usd` | 同一筆已確認費用的 USD 金額，以十進位字串回傳        |

`pending` 表示最終金額尚未確認，因此不回傳金額欄位。`refunded` 表示已確認淨費用為零。缺少整個 `billing` 物件表示平台無法確認安全的公開值，不代表該請求免費。

此物件可能出現在：

* 非同步圖片任務查詢 `GET /v1/images/generations/{task_id}`
* 非同步影片任務查詢 `GET /v1/videos/generations/{task_id}`
* 任務 Webhook 的 `data.billing`
* 相容的非串流同步圖片生成或編輯回應頂層 `billing`

對於非同步任務，任務完成後可將任務查詢介面作為取得最終費用的後備方式。串流圖片回應、不支援的供應商回應格式、Playground 請求和延遲批次計費可能不回傳此物件。

## 錯誤

| 狀態碼           | 錯誤碼                     | 含義                            |
| ------------- | ----------------------- | ----------------------------- |
| `400`         | `invalid_request_error` | 查詢參數不受支援，或 `type`、`limit` 無效  |
| `401` / `403` | 依情況而定                   | API Key 無效、過期、受限，或無權使用對應帳戶或群組 |
| `404`         | `model_not_found`       | 目前 API Key 無法使用此精確模型 ID       |
| `503`         | `pricing_unavailable`   | 無法安全載入客戶價格，不會降級回傳公開價格         |

回應使用 `Cache-Control: private, no-store`。