Threads 시맨틱 검색 API

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

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

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

上班族被老闆氣到想離職

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

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

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

빠른 시작

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

응답(일부):

{
  "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 이상을 받을 수 있습니다.

쿼리 작성법

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

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

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

매개변수

매개변수	설명	기본값
`query`	찾고 싶은 내용을 한 문장으로 설명, 2–200자	필수
`size`	반환 건수, 10–3000	10
`language`	시장. 지역과 언어 참고	`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개 이상을 받은 체지방 감량 관련 게시물 찾기

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를 사용하세요.
지명을 한정한 쿼리(예: 「台北美食」(타이베이 맛집))는 다른 도시의 결과가 섞이기 쉽습니다. 현재 시맨틱 모델의 알려진 약점입니다.