# 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 요금제](/ko/api/credits/#api-요금제)가 필요합니다. 모든 키는 계정의 크레딧을 공유합니다.

:::caution
API 키는 곧 계정의 크레딧입니다. 프런트엔드 코드, 공개 저장소, 스크린샷에 절대 넣지 마세요.
:::

## 2. 첫 요청 보내기

모든 요청은 `https://premium-api.throk.ai`로 보내며, 헤더에 `Authorization: Bearer <API 키>`를 포함합니다.

아래 요청은 최근 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`를 추가하세요. 자세한 내용은 [검색 규칙](/ko/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 | 기타 메시지 | 매개변수가 허용 범위를 벗어남. 예: 허용된 조회 기간을 초과한 시간 |

## 다음 단계

- 먼저 [검색 규칙](/ko/api/guides/search-rules/)을 읽고 키워드 매칭 방식을 이해하면 시행착오를 크게 줄일 수 있습니다.
- Claude나 Cursor에서 바로 데이터를 조회하려면 [AI 어시스턴트에서 사용하기(MCP)](/ko/api/mcp/)를 참고하세요.