# 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 プラン](/ja/api/credits/#api-プラン)が必要です。すべてのキーで、アカウントのクレジットを共有します。

:::caution
API キーはアカウントのクレジットそのものです。フロントエンドのコード、公開リポジトリ、スクリーンショットには絶対に含めないでください。
:::

## 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` を指定してください。詳しくは[検索ルール](/ja/api/guides/search-rules/#検索の対象期間)をご覧ください。
:::

## 3. 残りのクレジットを確認する

開発者プラットフォームの**概要**または **Credits 使用履歴** ページで、残高と消費の明細を 1 件ずつ確認できます。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 | その他のメッセージ | パラメータが範囲外。例：期間が遡れる日数の上限を超えている |

## 次のステップ

- まず[検索ルール](/ja/api/guides/search-rules/)を読んで、キーワードの照合方法を理解しておくと、無駄な試行錯誤を大きく減らせます。
- Claude や Cursor から直接データを調べたい場合は、[AI アシスタントで使う（MCP）](/ja/api/mcp/)をご覧ください。