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

> 開物中文搜尋 API 的快速開始、認證、/v1/search 與 /v1/extract 參數、額度與速率限制、錯誤格式、MCP Server 設定、CLI 與 Claude Code / Cursor Skills、OpenAPI 規格。

來源 Source: https://kaiwu.dev/developers · 標題 Title: 開物 Kaiwu 開發者文件 — API、MCP、CLI、Skills · 本文件為 `Accept: text/markdown` 的 Markdown 版本

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

## 讓你的 agent 自己接上

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

### 複製 prompt

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

貼給 Claude Code、Cursor、OpenClaw 或任何會讀網址的 agent。金鑰在 [儀表板](https://kaiwu.dev/dashboard) 免費取得（限時免費，每月 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_…`。金鑰在 [儀表板](https://kaiwu.dev/dashboard) 建立與撤銷，可以為不同專案建多把。金鑰不會過期，撤銷即失效。

公開端點（`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` \| `all` | 時間範圍。省略則依查詢推斷；明確指定優先。 |
| `category` | `general` \| `news` \| `auto` | 搜尋分類。省略或 `auto` 則時事走新聞；明確指定優先。 |
| `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" }
  ],
  "planned": { "queries": ["台灣 AI 基本法 草案 重點", "人工智慧基本法"], "category": "news", "time_range": "year", "source": "inferred" },
  "answer": "（include_answer 且有結果才有）…附來源標注 [1][2]",
  "credits_used": 42,
  "credits_remaining": 958
}
```

時事查詢會自動加時間範圍與新聞分類，並展開繁簡／官方名稱；你在請求裡明確指定的 `time_range` / `category` 優先。重試後仍無結果時回 `warning`，不生成答案。

`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 天並在 [變更紀錄](https://kaiwu.dev/developers#changelog) 公告。

### 變更紀錄

- **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；帳號免費，直接註冊一把測試金鑰即可。儀表板的[測試場](https://kaiwu.dev/dashboard/playground)可以在瀏覽器裡送請求、看完整回應，不消耗你程式端的額度以外的東西（同一個帳號共用額度）。

- [給 agent 的 prompt](https://kaiwu.dev/developers#agent-prompt)
- [快速開始](https://kaiwu.dev/developers#quickstart)
- [認證](https://kaiwu.dev/developers#authentication)
- [/v1/search](https://kaiwu.dev/developers#search)
- [/v1/extract](https://kaiwu.dev/developers#extract)
- [額度與速率](https://kaiwu.dev/developers#credits)
- [錯誤格式](https://kaiwu.dev/developers#errors)
- [MCP Server](https://kaiwu.dev/developers#mcp)
- [版本與變更](https://kaiwu.dev/developers#versioning)
- [測試環境](https://kaiwu.dev/developers#sandbox)

- [OpenAPI 3.1 規格](https://kaiwu.dev/openapi.json) — 每個操作都有 operationId、型別化的請求與回應、共用的 Error schema。可直接餵給 client 產生器或 function calling。
- [llms.txt](https://kaiwu.dev/llms.txt) — 給語言模型看的精簡摘要：開物是什麼、什麼時候該用、怎麼呼叫。完整版在 /llms-full.txt。
- [CLI & Agent Skills](https://kaiwu.dev/cli) — kw search / extract / credits；Claude Code 與 Cursor 的 kaiwu-* skills。
- [@kaiwu/cli on npm](https://www.npmjs.com/package/@kaiwu/cli) — npm i -g @kaiwu/cli，零依賴、Node 18+。
- [GitHub](https://github.com/dAAAb/Kaiwu-Dev) — 原始碼、issues、skills 與 plugin marketplace 清單。
- [測試場（需登入）](https://kaiwu.dev/dashboard/playground) — 在瀏覽器直接送 search / extract 請求、看原始回應。