Threads 語意搜尋 API

GET /post/semantic-search 用「意思」找串文，不是比對字面關鍵字。把想找的主題用一句話描述出來，API 會回傳最近 30 天內語意最接近的串文。

什麼時候用語意搜尋、什麼時候用關鍵字搜尋

假設你要找「上班族抱怨老闆、想離職」的串文。用 /post/search 你得自己列出關鍵字：離職、辭職、慣老闆、遣散……永遠列不完，而且很多串文根本沒用到這些詞。語意搜尋只要一句：

上班族被老闆氣到想離職

結果會同時包含寫「提離職」、「辭職」、「被通知遣散」的串文，甚至完全沒提這些詞、只是在抱怨主管的串文。

反過來說，如果你要找的是明確的詞，例如品牌名、帳號、活動 hashtag、產品型號，請用 /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 積分，之後每筆加 2 積分（例如回傳 30 筆為 70 積分）。超過 10 筆的部分依實際回傳筆數計費，但每次呼叫最低收 30 積分，即使篩選後結果不足 10 筆、甚至 0 筆。

在 MCP 中使用

MCP 工具名稱是 semantic_search_posts，參數相同，但 size 上限為 10。

它和 get_inspiration 的差別：get_inspiration 只搜高互動的精選串文；semantic_search_posts 搜所有近期串文，一般小帳號的串文也找得到。

限制

只搜最近 30 天。 更早的串文請用 /post/search。
只搜主串文，不含回覆，也不包含太短的串文。
無法保證結果包含特定字詞。 需要精確比對時請用 /post/search。
地名限定的查詢（例如「台北美食」）容易混入其他城市的結果，這是目前語意模型的已知弱點。