# Threads API 教學：Throk API 快速開始

## 1. 取得 API 金鑰

到 [Throk 開發者平台](https://developer.throk.ai/dashboard) 登入，在 **API 金鑰** 頁面按 **建立金鑰**。金鑰以 `sk-throk-` 開頭，本文件的範例一律寫成 `sk-throk-...`，使用時請換成你自己的金鑰。

![開發者平台的 API 金鑰頁：建立金鑰、帳戶積分餘額與金鑰列表](../../../assets/screenshots/api/portal-api-keys.jpg)

呼叫 API 需要有效的 [API 方案](/api/credits/#api-方案)；所有金鑰共用帳戶的積分。

:::caution
API 金鑰等同你的帳號積分。不要把它放進前端程式碼、公開的 repo 或截圖裡。
:::

## 2. 發出第一個請求

所有請求都送到 `https://premium-api.throk.ai`，並在標頭帶上 `Authorization: Bearer <你的金鑰>`。

下面這個請求會搜尋最近 24 小時內提到「減脂」的中文串文，依讚數由高到低排序，取前 10 筆：

```bash
curl -G 'https://premium-api.throk.ai/post/search' \
  -H 'Authorization: Bearer sk-throk-...' \
  --data-urlencode 'keywords=減脂' \
  --data-urlencode 'max_age_hours=24' \
  --data-urlencode 'sort=like:desc' \
  --data-urlencode 'size=10'
```

回應（節錄）：

```json
{
  "content": [
    {
      "post": {
        "url": "https://threads.com/post/DaXXXXXX",
        "code": "DaXXXXXX",
        "caption": "減脂期間我都這樣吃……",
        "like_count": 1520,
        "reply_count": 48,
        "post_timestamp": 1790000000
      },
      "user": null
    }
  ],
  "metadata": {
    "total_count": 356,
    "current_page": 1,
    "page_size": 10,
    "total_pages": 35,
    "credits_consumed": 10
  }
}
```

:::tip[預設只搜最近 3 小時]
`/post/search` 沒有指定時間時，只會搜尋**最近 3 小時**的串文。要看更長的時間，請加上 `max_age_hours`（最多 2160，也就是 90 天）或 `from_timestamp`。詳見[搜尋規則](/api/guides/search-rules/#搜尋的時間範圍)。
:::

## 3. 查看剩餘積分

在開發者平台的**總覽**或 **Credits 消耗紀錄**頁面可以直接看到餘額與每一筆消耗。也可以用 API 查詢，不扣積分：

```bash
curl 'https://premium-api.throk.ai/balance' \
  -H 'Authorization: Bearer sk-throk-...'
```

```json
{ "credits": 48210 }
```

每次呼叫扣了多少積分，都會出現在回應的 `credits_consumed` 欄位。消費紀錄可以用 `GET /balance/history` 查詢。

## 常見錯誤

| HTTP 狀態 | 訊息 | 原因 |
| --- | --- | --- |
| 401 | `Invalid API key` | 金鑰打錯、已刪除，或標頭少了 `Bearer` 前綴 |
| 400 | `Insufficient credits` | 積分不足。系統會在查詢前先估算費用，積分不夠就不會執行 |
| 400 | 其他訊息 | 參數超出範圍，例如時間超過允許的回溯天數 |

## 下一步

- 先讀[搜尋規則](/api/guides/search-rules/)，了解關鍵字怎麼比對，可以少走很多冤枉路。
- 想在 Claude 或 Cursor 裡直接查資料，請看[在 AI 助手中使用（MCP）](/api/mcp/)。