DEVELOPERS · 開發者

一個 API call，搜遍中文世界。

Base URL https://kaiwu.dev。JSON 進、JSON 出。認證用 API 金鑰（Bearer），沒有 OAuth 要接。目前限時免費：每月 1,000 額度。

讓你的 agent 自己接上

把這段貼給 agent。它會讀 llms.txt、用你給的金鑰呼叫 API，之後遇到中文查詢就會用開物。

請幫我接上開物 Kaiwu（中文世界的 AI 搜尋 API）：讀 https://kaiwu.dev/llms.txt，用 KAIWU_API_KEY 環境變數呼叫 POST https://kaiwu.dev/v1/search（Authorization: Bearer），之後遇到需要查中文資料時就用它，並回報你查到的第一筆結果。

貼給 Claude Code、Cursor、OpenClaw 或任何會讀網址的 agent。金鑰在儀表板免費取得（限時免費，每月 1,000 額度）。

快速開始

# 1. 到 https://kaiwu.dev/dashboard 登入，複製 API 金鑰（kw_…）
export KAIWU_API_KEY=kw_...

# 2. 搜尋（basic 1 額度；advanced 2；include_answer 再 +1）
curl -s https://kaiwu.dev/v1/search \
  -H "Authorization: Bearer $KAIWU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"台灣 AI 基本法 草案 重點","search_depth":"advanced","include_answer":true,"max_results":5}'

# 3. 抓網頁正文（每個成功網址 1 額度；加 query 語意過濾 +1）
curl -s https://kaiwu.dev/v1/extract \
  -H "Authorization: Bearer $KAIWU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://example.com/article"],"format":"markdown"}'

# 4. 查剩餘額度
curl -s https://kaiwu.dev/v1/credits -H "Authorization: Bearer $KAIWU_API_KEY"

金鑰以 kw_ 開頭，共 35 字元。請存到環境變數或密鑰管理器，不要寫進程式碼或網址；外洩時到儀表板撤銷並重建。

認證

所有 /v1/* 端點使用 Authorization: Bearer kw_…。金鑰在儀表板建立與撤銷，可以為不同專案建多把。金鑰不會過期，撤銷即失效。

公開端點（GET /api/stats、GET /api/health、/openapi.json、/llms.txt）不需要金鑰。

POST /v1/search

參數	型別	說明
`query`	string	必填。建議 400 字以內；會自動展開繁簡用語。
`search_depth`	`basic` \| `advanced`	basic 回傳標題與摘要（1 額度）；advanced 抓取前幾頁、語意切段（2 額度）。
`include_answer`	boolean	生成附來源標注的綜合答案（+1 額度）。
`max_results`	integer	1–20，預設 5（省略或 0 視同預設）。
`time_range`	`day` \| `week` \| `month` \| `year`	時間範圍。
`lang`	string	`zh-TW`（預設）、`zh-CN`、`en`。

回應：

{
  "query": "台灣 AI 基本法 草案 重點",
  "results": [
    { "title": "…", "url": "https://…", "snippet": "…", "content": "（advanced 才有：語意切段後的正文）",
      "published": "2026-05-12", "engine": "google", "score": 0.91, "language": "zh-TW" }
  ],
  "answer": "（include_answer 才有）…附來源標注 [1][2]",
  "credits_used": 42,
  "credits_remaining": 958
}

credits_used 是本月累計已用額度（含本次扣的 3 額度），不是單次費用；credits_remaining 是本月剩餘額度，也可用 GET /v1/credits 查。

POST /v1/extract

參數	型別	說明
`urls`	string \| string[]	一或多個網址，最多 20 個。失敗的網址不計費。
`format`	`markdown` \| `text`	輸出格式，預設 markdown。
`query`	string	只保留與查詢相關的段落（LLM 過濾，+1 額度）。

每個結果包含 url、title、content、length、status（success / failed）。自動偵測 <article> / <main> 正文，移除導覽、廣告與樣板；內建 SSRF 防護（不抓內網位址）。

額度與速率限制

免費方案每月 1,000 額度，每月 1 日重置；GET /v1/credits 查餘額。
計費：search basic 1、advanced 2、include_answer +1；extract 每個成功網址 1、query +1。
速率：目前沒有硬性的每秒請求上限，請以約 1 req/s 的節奏呼叫；額度用完會回 429（insufficient_credits）。之後若加入速率限制，會附 Retry-After 並在變更紀錄公告。
付費方案（更高額度與併發）籌備中；推出前一律限時免費，正式收費會提前通知。

公開統計的計算方式

首頁與 GET /api/stats 的數字 = 資料庫即時統計 + 固定的公開基線（開發者 +120、查詢 +5,000、token +7,500,000）。基線是常數、不會隨時間變動，也公開在此；token 數為依查詢量的估計值。

錯誤格式

所有錯誤都是 JSON，含人類可讀的 error 與機器可讀的 code（missing_api_key、invalid_api_key、invalid_json、missing_query、insufficient_credits、upstream_unavailable、not_found…）。未知路徑回真正的 404 JSON，401 附 WWW-Authenticate。

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="kaiwu", error="invalid_token"
Content-Type: application/json

{ "error": "無效的 API 金鑰", "code": "invalid_api_key" }

MCP Server

遠端端點 https://kaiwu.dev/mcp（Streamable HTTP），提供 kaiwu_search 與 kaiwu_extract 兩個工具，額度計算與 REST 相同。Claude Code 一行加入：

claude mcp add --transport http kaiwu https://kaiwu.dev/mcp \
  --header "Authorization: Bearer $KAIWU_API_KEY"

Claude Desktop / Cursor / OpenClaw 的設定檔：

{
  "mcpServers": {
    "kaiwu": {
      "url": "https://kaiwu.dev/mcp",
      "headers": { "Authorization": "Bearer kw_..." }
    }
  }
}

也可以用 ?apiKey=kw_… 放在網址上，但金鑰會出現在日誌與 referrer 中，建議只在無法設定 header 的客戶端使用。

版本與相容性

路徑以 /v1 為版本；新增欄位不視為破壞性變更。破壞性變更會以 /v2 推出，舊版至少保留 90 天並在變更紀錄公告。

變更紀錄

2026-08. 開發者文件、OpenAPI 規格、llms.txt、Markdown 內容協商、機器可讀的錯誤 code、MCP header 認證。所有方案限時免費。
2026-05. /v1/extract、CLI kw、Claude Code / Cursor Skills、MCP kaiwu_extract、公開統計 /api/stats。
2026-04. LLM 層升級：語意切段與綜合答案；Ollama 備援。
2026-02. 首版上線：/v1/search、儀表板、API 金鑰、遠端 MCP。

測試環境

沒有獨立的 staging；帳號免費，直接註冊一把測試金鑰即可。儀表板的測試場可以在瀏覽器裡送請求、看完整回應，不消耗你程式端的額度以外的東西（同一個帳號共用額度）。