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

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

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

## 驗證

**Authorization** `string` *required*

使用生成 API Key，格式為 `Bearer YOUR_API_KEY`。

## 查詢參數

**model** `string`

精確模型 ID。不傳時回傳所有可用的圖片與影片模型。

**type** `string`

依 `image` 或 `video` 篩選。

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

回傳的模型數量，範圍為 `1` 至 `100`。

**after** `string`

使用上一次回應中的 `next_after` 繼續分頁。

Seedance 地區版本使用不同的模型 ID。例如，透過 `model` 查詢 `seedance-2-5`、`seedance-2-5-cn` 或 `seedance-2-5-global`。介面沒有獨立的地區參數。

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

以上數值僅用來說明回應結構，請以目前 API Key 實際回傳的價格目錄為準。

## 價格欄位

**currency** `string`

價格幣別，目前為 `USD`。

**object** `string`

物件類型，固定為 `list`。

**data** `array`

可用模型清單。每個項目包含精確模型 `id`、模型 `type` 和零個或多個 `prices`。

**has\_more** `boolean`

是否還有下一頁。

**next\_after** `string`

下一次請求使用的游標。`has_more` 為 `false` 時回傳空字串。

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

此價格適用的路由群組。使用自動群組的 API Key 可能收到多個群組。

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

價格成立的條件，包含會影響計價的模型預設值。生成請求應與這些值相符。

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

計費類型：`per_request`、`per_second` 或 `per_token`。

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

計費依據：`request`、`output_seconds`、`total_tokens` 或 `text_input_tokens`。

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

價格單位：`request`、`second` 或 `1m_tokens`。

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

以十進位字串回傳的 USD 生效單價。此價格已包含客戶價格和群組倍率，不要再次乘上群組倍率。

價格也可能包含 `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/tasks/{task_id}`
* 非同步圖片任務查詢 `GET /v1/images/generations/{task_id}`
* 非同步影片任務查詢 `GET /v1/videos/generations/{task_id}`
* 任務 Webhook 的 `data.billing`
* 相容的非串流同步圖片生成或編輯回應頂層 `billing`

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

## 任務用量欄位

圖片和影片任務查詢在頂層 `usage` 回傳已確認的計費量, 成功 Webhook 在 `data.usage` 回傳相同口徑的欄位. 計費量, 模型回報的 token 明細及工具次數可並存, 依可用性分別回傳.

| 欄位 | 型別 | 說明 |
| - | - | - |
| `charge_type` | string | 計費方式: `per_request`, `per_second` 或 `per_token` |
| `requests` | integer | 實際計費次數. 一般圖片請求的 `n` 不會直接乘算次數; Midjourney 影片的有效 `batch_size` 會計入計費次數 |
| `billed_tokens` | integer | 實際用於計價的 token 數. 部分圖片路徑使用設定的預扣 token 基數, 不保證等於上游實際生成量 |
| `output_seconds` | integer | 參與計費的輸出影片時長, 單位為整數秒 |
| `input_seconds` | integer | 參與計費的輸入影片時長, 單位為整數秒 |
| `input_images` | integer | 扣除免費額度後參與計費的輸入圖片數 |
| `input_tokens`, `output_tokens`, `prompt_tokens`, `completion_tokens`, `total_tokens` | integer | 影片模型回報的非負整數 token 明細. 依供應商實際提供的欄位回傳; 已確認的按 token 結算可補齊 `total_tokens` |
| `tool_usage` | object | 工具次數, 可包含 `web_search`, `image_search`, `grounding_queries`; 依實際可用欄位回傳, 與 token 明細獨立 |

計費量來自本次任務儲存的計費記錄. 固定計費使用建立時確認的數量, 後置結算使用最終結算數量; 不按目前價格或金額反推用量. `per_request` 使用 `requests`, `per_second` 使用 `output_seconds`, `per_token` 使用 `billed_tokens`; 輸入影片和圖片附加項依需要回傳, 為零時省略.

歷史任務若只儲存金額, 未儲存可驗證的計費數量, 會省略無法確認的欄位. 未提供的 token 明細不補零. 按 token 結算後, 影片 token 分項只有在已回報總量與最終計費量一致時才保留. `usage` 與 `billing` 的可用性獨立, 缺少用量不代表沒有扣費, 也不會阻止結果回傳. 反之, 回傳 `charge_type` 等計費量時一定同時回傳 `billing.status=settled` 和實際金額. 提交時一次扣清的固定計費任務同樣回傳 `settled`. 任務查詢和 Webhook 使用同一確認條件和欄位取值.

## 錯誤

| 狀態碼 | 錯誤碼 | 含義 |
| - | - | - |
| `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`。


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