# Throk API 積分與計費

每次呼叫 API 都會扣積分（credits）。扣了多少積分會出現在回應的 `credits_consumed` 欄位。

## API 方案

API 與 MCP 的積分來自 API 方案，和 [Throk 網頁版](/web/plans/)的積分分開計算。所有 API 金鑰共用同一個帳戶的積分。

| 方案 | 價格 | 每月積分 | Webhook |
| --- | --- | --- | --- |
| API Lite | US$30 / 月 | 15,000 | — |
| API Standard | US$100 / 月 | 100,000 | ✅ |
| API Plus | US$500 / 月 | 1,000,000 | ✅ |
| API Premium | US$2,500 / 月 | 6,000,000 | ✅ |

- 積分自購買日起**有效 1 個月**，未用完不會累積到下個月。
- **加購積分**：API Standard 以上方案可以一次性加購，費率為 Standard US$10、Plus US$5、Premium US$4（每 10,000 積分）。加購的積分只能在本期帳單週期內使用。
- 方案與付款方式可以在開發者平台的**購買 Credits** 頁面管理，詳見下方。

## 常用端點的計費方式

| 端點 | 計費方式 |
| --- | --- |
| `GET /post/search` | 每回傳 1 篇串文 1 積分；`include_details=true` 時每篇 2 積分 |
| `GET /post/keyword-trend` | 3 積分 × 關鍵字數 × 天數；`include_engagement=true` 時為 4 積分 × 關鍵字數 × 天數 |
| `GET /post/hot` | 30 篇 70 積分，每多 1 篇加 2 積分；`sort=impression:desc` 時基本費為 100 積分。依請求的 `size` 計費 |
| `GET /post/semantic-search` | 前 10 篇 30 積分，之後每篇加 2 積分。每次呼叫最低 30 積分，即使沒有結果 |
| [Webhook](/api/webhooks/) | 每送出一則事件 20 積分 |
| `GET /balance`、`GET /balance/history` | 免費 |

其他端點的費用請見 [API 文檔](https://developer.throk.ai/api/docs)。MCP 工具與對應的 REST 端點價格相同，詳見[在 AI 助手中使用（MCP）](/api/mcp/#可用的工具)。

## 範例

- 搜尋 3 個關鍵字、回傳 50 篇串文：50 積分
- 同樣的搜尋加上 `include_details=true`：100 積分
- 查 2 個關鍵字、30 天的趨勢：3 × 2 × 30 = 180 積分
- 同上，加上互動數（`include_engagement=true`）：4 × 2 × 30 = 240 積分

## 積分不足

Throk 會在查詢**之前**先估算費用。積分不夠時會回傳 HTTP 400 與 `Insufficient credits`，不會執行查詢，也不會扣積分。

## 在開發者平台查看餘額與紀錄

登入 [Throk 開發者平台](https://developer.throk.ai/dashboard) 就能看到帳戶的使用狀況，不需要寫程式：

| 頁面 | 可以做什麼 |
| --- | --- |
| **總覽** | 剩餘積分、30 天消耗與呼叫數、Webhook 成功率 |
| **API 金鑰** | 建立與刪除金鑰，查看帳戶積分餘額 |
| **Credits 消耗紀錄** | 每日消耗圖表、依 API 類型的分佈，以及每一筆呼叫的時間、消耗、金鑰與參數 |
| **購買 Credits** | 切換 API 方案、加購積分，以及前往 Stripe 管理付款方式與發票 |
| **端點與規則**、**發送紀錄** | 設定 [Webhook](/api/webhooks/) 並查看發送結果 |

![開發者平台的 Credits 消耗紀錄頁：剩餘積分、30 天消耗、每日消耗圖表與依 API 類型的分佈](../../../assets/screenshots/api/portal-usage.jpg)

![開發者平台的購買 Credits 頁：API Lite、Standard、Plus、Premium 方案](../../../assets/screenshots/api/portal-plans.jpg)

## 用 API 查詢餘額與紀錄

也可以在程式裡查詢，這兩個端點都不扣積分：

```bash
# 剩餘積分
curl 'https://premium-api.throk.ai/balance' \
  -H 'Authorization: Bearer sk-throk-...'

# 消費紀錄（每頁 50 筆）
curl 'https://premium-api.throk.ai/balance/history?page=1' \
  -H 'Authorization: Bearer sk-throk-...'
```

消費紀錄中，透過 MCP 呼叫的項目會加上 `mcp:` 前綴，例如 `mcp:keywords`。