# Threads 시맨틱 검색 API

`GET /post/semantic-search`는 글자 그대로의 키워드가 아니라 「의미」로 게시물을 찾습니다. 찾고 싶은 주제를 한 문장으로 설명하면 최근 30일 안에서 의미가 가장 가까운 게시물을 반환합니다.

## 시맨틱 검색과 키워드 검색, 언제 무엇을 쓸까

예를 들어 「직장인이 상사 때문에 화가 나서 퇴사하고 싶어 하는」 게시물을 찾는다고 해 봅시다. `/post/search`를 쓰면 離職(퇴사), 辭職(사직), 慣老闆(갑질 상사), 遣散(해고)…처럼 키워드를 직접 나열해야 합니다. 아무리 나열해도 끝이 없고, 이런 단어를 아예 쓰지 않은 게시물도 많습니다. 시맨틱 검색은 한 문장이면 됩니다.

> 上班族被老闆氣到想離職

결과에는 「提離職」(퇴사 의사 전달), 「辭職」(사직), 「被通知遣散」(해고 통보)라고 쓴 게시물은 물론, 이런 단어 없이 상사에 대한 불만만 이야기한 게시물까지 함께 나옵니다.

반대로 브랜드명, 계정, 이벤트 해시태그, 제품 모델명처럼 **명확한 단어**를 찾는다면 `/post/search`를 사용하세요. 시맨틱 검색은 한두 글자짜리 키워드에서 성능이 매우 떨어집니다(아래 점수 설명 참고).

| 상황 | 추천 |
| --- | --- |
| 주제는 알지만 키워드를 빠짐없이 나열할 수 없을 때 | 시맨틱 검색 |
| 특정 상황이나 감정을 담은 게시물을 찾을 때 | 시맨틱 검색 |
| 브랜드명, 계정, 특정 단어를 모니터링할 때 | `/post/search` |
| 30일보다 오래된 데이터가 필요할 때 | `/post/search` |
| 답글도 포함해야 할 때 | `/post/search` |

## 빠른 시작

```bash
curl -G 'https://premium-api.throk.ai/post/semantic-search' \
  -H 'Authorization: Bearer sk-throk-...' \
  --data-urlencode 'query=新手第一次去健身房不知道要練什麼' \
  --data-urlencode 'size=10'
```

응답(일부):

```json
{
  "results": [
    {
      "post": {
        "url": "https://threads.com/post/DaXXXXXX",
        "caption": "健身新手要怎麼練 怎麼吃 那麼多器械要怎麼選 求大佬指教",
        "like_count": 12,
        "reply_count": 3,
        "post_timestamp": 1784402170
      },
      "user": { "username": "...", "full_name": "..." },
      "score": 0.990
    }
  ],
  "credits_consumed": 30
}
```

결과는 관련도순으로 정렬되며, 각 항목에는 게시물과 작성자의 전체 정보가 포함됩니다.

## 점수 읽는 법

각 결과의 `score`는 쿼리와 게시물의 의미 유사도이며, 범위는 0–1입니다.

- **0.98 이상**: 관련성이 높아 그대로 사용할 수 있습니다
- **0.95–0.98**: 대체로 관련 있지만, 「주제는 비슷한데 대상이 다른」 결과가 섞일 수 있습니다(예: 아이가 잠을 못 자는 고민을 검색했는데 반려동물(毛小孩)이 잠을 못 자는 게시물이 섞임)
- **0.95 미만**: 노이즈로 간주합니다

의미가 불완전한 단편적인 키워드(예: 「蛋白」(단백)만 입력)는 최고 점수가 0.92–0.94에 그치고, 같은 점수대에 관련 없는 게시물도 똑같이 높은 점수로 섞여 있어 걸러낼 수 없습니다. 「台南美食」(타이난 맛집)처럼 그 자체로 완결된 주제를 나타내는 단어는 문제없이 0.98 이상을 받을 수 있습니다.

:::tip
반환된 최고 점수가 0.96보다 낮다면 이 쿼리는 시맨틱 검색에 적합하지 않다는 뜻입니다. `/post/search` 키워드 매칭이 더 정확합니다.
:::

## 쿼리 작성법

「台南美食」(타이난 맛집)으로 실제 테스트한 결과, 세 가지 작성 방식은 결과의 경향이 서로 달랐습니다.

- **같은 주제의 키워드 묶음**: `台南美食 台南小吃 台南餐廳推薦`. 같은 주제의 단어를 여러 개 넣으면 주제가 더 뚜렷해지며, 가장 안정적인 방식입니다. 두세 개면 충분합니다. 반드시 **하나의** 주제여야 하며, 관련 없는 주제는 따로 조회하세요.
- **완전한 문장**: `去台南玩有什麼在地美食推薦`. 결과가 문장의 맥락에 가깝게 나옵니다. 이 문장은 질문형이라 결과도 대부분 추천을 묻는 게시물입니다. 맛집 후기를 찾으려면 내용을 서술형으로 설명하세요.
- **단일 주제어**: `台南美食`. 사용할 수는 있지만 아주 짧은 게시물이나 인근 도시의 결과가 섞이기 쉽습니다.

참여도가 높은 게시물을 원하면 쿼리를 고칠 필요 없이 `min_like_count`를 함께 쓰면 됩니다.

## 매개변수

| 매개변수 | 설명 | 기본값 |
| --- | --- | --- |
| `query` | 찾고 싶은 내용을 한 문장으로 설명, 2–200자 | 필수 |
| `size` | 반환 건수, 10–3000 | 10 |
| `language` | 시장. [지역과 언어](/ko/api/guides/regions/) 참고 | `zh` |
| `exclude_hk` | 광둥어와 홍콩식 중국어 게시물 제외. `language=zh`에서만 적용 | `false` |
| `from_timestamp` | 시작 시각(UNIX 초), 최대 30일 전까지 | 30일 전 |
| `to_timestamp` | 종료 시각(UNIX 초) | 현재 |
| `min_like_count` | 좋아요 수가 기준 이상인 게시물만 남김 | 필터링 안 함 |
| `min_reply_count` | 답글 수가 기준 이상인 게시물만 남김 | 필터링 안 함 |

`min_like_count`와 `min_reply_count`는 의미 순위 상위 후보 게시물 안에서 필터링하므로, 기준을 설정하면 반환 건수가 `size`보다 적을 수 있습니다. 기준을 너무 높게 잡으면(예: 좋아요 1000개) 주목도가 낮은 주제는 결과가 하나도 남지 않을 수 있습니다.

예시: 최근 일주일 동안 좋아요 100개 이상을 받은 체지방 감량 관련 게시물 찾기

```bash
curl -G 'https://premium-api.throk.ai/post/semantic-search' \
  -H 'Authorization: Bearer sk-throk-...' \
  --data-urlencode 'query=減脂期到底可以吃什麼' \
  --data-urlencode "from_timestamp=$(date -v-7d +%s)" \
  --data-urlencode 'min_like_count=100'
```

## 요금

처음 10건까지 30크레딧, 이후 1건당 2크레딧이 추가됩니다(예: 30건 반환 시 70크레딧). 10건을 넘는 부분은 실제 반환 건수 기준으로 과금되지만, 필터링 후 결과가 10건 미만이거나 0건이어도 호출당 최소 30크레딧이 부과됩니다.

## MCP에서 사용하기

MCP 도구 이름은 `semantic_search_posts`이며, 매개변수는 같지만 `size` 상한이 10입니다.

`get_inspiration`과의 차이: `get_inspiration`은 고참여 엄선 게시물만 검색하고, `semantic_search_posts`는 최근 게시물 전체를 검색하므로 일반 소규모 계정의 게시물도 찾을 수 있습니다.

## 제한 사항

- **최근 30일만 검색합니다.** 더 오래된 게시물은 `/post/search`를 사용하세요.
- **원글만 검색하며 답글은 포함하지 않습니다.** 너무 짧은 게시물도 제외됩니다.
- **결과에 특정 단어가 포함된다고 보장할 수 없습니다.** 정확한 매칭이 필요하면 `/post/search`를 사용하세요.
- **지명을 한정한 쿼리**(예: 「台北美食」(타이베이 맛집))는 다른 도시의 결과가 섞이기 쉽습니다. 현재 시맨틱 모델의 알려진 약점입니다.