Dipper 文档

Dipper 是给 AI agent 用的网页搜索和网页抓取 API。所有用户共用一份缓存，命中缓存的调用比回源便宜。

你可以直接调 REST 接口，也可以把它作为 MCP 服务器接进 agent。两种方式扣的是同一个预充值余额，价格也一样。

快速开始

1. 在 /login/ 用 GitHub 登录。
2. 在控制台 /app/ 创建 API 密钥。密钥只显示一次，关掉对话框之前记得复制。密钥以 dk- 开头。不用的密钥可以随时在控制台吊销，一分钟内失效。
3. 把密钥放进环境变量，跑一次搜索。

export DIPPER_API_KEY=dk-...

curl -i https://dipper-search.com/v1/search \
  -H "Authorization: Bearer $DIPPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "rust async runtime comparison lang:en", "max_results": 5}'

-i 会打印响应头。如果最近没人搜过这个查询，Dipper 会实时去搜，按未命中的价格计费：

x-dipper-cache: MISS
x-dipper-cost-usd: 0.000800

同样的请求再发一次，就是从缓存返回了：

x-dipper-cache: HIT
x-dipper-cost-usd: 0.000160

认证

Base URL 是 https://dipper-search.com。请求体和响应体都是 JSON。每个请求都要带上密钥：

Authorization: Bearer dk-...

也可以用 x-api-key: dk-... 请求头。没带密钥、格式不对或者密钥不存在，返回 401；账号被停用，返回 403。

密钥只放在服务端。谁拿到密钥，谁就能花你的余额。

搜索

POST /v1/search 执行一次网页搜索。

不认识的字段会被忽略。

搜索语法

语法直接写在 query 里，算在 128 个字符之内，可以组合使用。

示例

{
  "query": "cloudflare r2 pricing",
  "max_results": 10,
  "include_content": false,
  "refresh": false
}

响应（200）：

{
  "query": "cloudflare r2 pricing",
  "results": [
    {
      "title": "Pricing · Cloudflare R2 docs",
      "url": "https://developers.cloudflare.com/r2/pricing/",
      "snippet": "R2 charges based on the total volume of data stored, along with two classes of operations...",
      "site_name": "Cloudflare Docs",
      "published_at": "2026-09-30T16:00:00+00:00",
      "score": 2.76,
      "authority": 3,
      "favicon": "https://developers.cloudflare.com/favicon.png"
    }
  ]
}

query 原样返回你发送的查询。

results 是空数组也算成功响应，不收费。

抓取

POST /v1/fetch 把网页正文转成 Markdown 返回。

curl https://dipper-search.com/v1/fetch \
  -H "Authorization: Bearer $DIPPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://developers.cloudflare.com/r2/pricing/"}'

响应（200）：

{
  "url": "https://developers.cloudflare.com/r2/pricing/",
  "title": "Pricing · Cloudflare R2 docs",
  "content": "# Pricing\n\nR2 charges..."
}

url 返回实际抓取的地址（规范化之后）。content 是 Markdown 格式的网页正文。提取不到正文的页面不收费。

响应头

搜索和抓取的响应都带下面三个响应头。

还没进入搜索或抓取就被拒绝的请求，不带这些响应头。比如密钥无效、触发限流、请求体不是 JSON。

账户

GET /v1/account/balance

curl https://dipper-search.com/v1/account/balance \
  -H "Authorization: Bearer $DIPPER_API_KEY"

{ "balance_micros": 4825350, "balance_usd": "4.825350" }

balance_micros 是整数，单位是百万分之一美元，1 美元等于 1,000,000。

GET /v1/account/usage?days=N

days 是 1 到 90 的整数，默认 7。统计范围是今天（UTC）加上之前的 days - 1 天。每天、每个工具、每种缓存状态各占一行。强制刷新的调用记为 miss。

{
  "days": 7,
  "since": "2026-10-20",
  "usage": [
    { "day": "2026-10-25", "tool": "search", "cache": "hit", "calls": 120, "amount_micros": 18000, "amount_usd": "0.018000" },
    { "day": "2026-10-25", "tool": "search", "cache": "miss", "calls": 40, "amount_micros": 30000, "amount_usd": "0.030000" }
  ],
  "total_calls": 160,
  "total_micros": 48000,
  "total_usd": "0.048000"
}

缓存规则

缓存由所有 Dipper 用户共享。只要有人搜过某个查询或者抓过某个页面，结果就会存下来。之后任何账号发来相同的请求，都直接从缓存返回，按命中价格计费。

缓存有多新

缓存里存的是第一个人请求时拿到的结果，可能比实时搜索旧。我们不承诺一条缓存保留多久。在意时效的话，设 refresh: true，或者在查询里加上 after: 日期。响应头 x-dipper-cache 会告诉你这次拿到的是不是缓存。

怎样算相同的请求

• 只有大小写或空白不同的查询，共用一条缓存。
• max_results 不影响缓存。一条缓存可以满足 50 以内的任意 max_results。
• include_content: true 的结果单独缓存。同一个查询的 include_content: false 请求也能用这条缓存。

搜索结果不会按调用方所在地区做本地化。需要指定语言的话，在查询里用 lang:。

强制刷新

在搜索或抓取请求里设 refresh: true，就会跳过缓存。Dipper 会立即请求上游，按未命中计费，返回 x-dipper-cache: REFRESH。你拿到的结果会替换共享缓存里的旧版本，之后谁再发相同的请求，都按命中价格拿到这份新结果。

• 带 include_content: true 刷新搜索时，同一查询的 include_content: false 缓存也会一起替换。带 include_content: false 刷新，只更新那一条。
• 其他边缘节点会在 10 分钟内拿到新结果。
• 刷新回来是空结果的话，不收费，旧缓存保留。
• 如果这时正好有一个相同的请求在执行，你会直接拿到它的结果，按命中价格计费。

MCP 服务器

同样的搜索和抓取工具也以远程 MCP 服务器的形式提供。缓存、价格和计费都和 REST 完全一样。

Claude Code

claude mcp add --transport http dipper https://dipper-search.com/mcp \
  --header "Authorization: Bearer $DIPPER_API_KEY"

加上 --scope user 就能在所有项目里用。用 claude mcp list 或者在会话里输入 /mcp 检查连接。

其他客户端

支持远程服务器的客户端，大多接受类似下面的 JSON 配置。配置文件放在哪、怎么引用环境变量，每个客户端不一样。

{
  "mcpServers": {
    "dipper": {
      "type": "http",
      "url": "https://dipper-search.com/mcp",
      "headers": { "Authorization": "Bearer ${DIPPER_API_KEY}" }
    }
  }
}

别把直接写了密钥的配置文件提交到代码库。只支持 stdio 的客户端，可以通过 mcp-remote 桥接。

免费 MCP 端点

注册之前想先试试，可以把客户端指向 https://dipper-search.com/mcp/free。不需要密钥，工具和付费端点一样。

claude mcp add --transport http dipper-free https://dipper-search.com/mcp/free

它靠一小笔所有人共用的额度运行：所有用户加起来每小时大约 100 次未命中缓存的请求，命中缓存的结果算 0.2 次。单个客户端最多用掉每小时额度的五分之一，每分钟大约能发 20 个请求。额度在每个整点（UTC）重置。用完之后，工具调用会返回一条错误，告诉你几点重置。

免费端点不支持 refresh。需要它，或者不想和别人共用额度，就创建一个 API 密钥，改用 /mcp。

工具

web_search 以文本形式返回带编号的结果。web_fetch 返回网页标题和 Markdown 格式的正文。两者都会在 structuredContent 里附上和 REST 响应相同的 JSON。每次返回的最后一行类似 [dipper: cache HIT, cost $0.000160]。在免费端点上，这一行末尾是 free endpoint，不显示费用。

调用失败时，工具结果会带上 isError: true 和一句简短说明，模型能看到出了什么问题。失败的调用不收费。

价格

按成功调用计费，搜索和抓取价格相同。

首发优惠到 2026 年 12 月 31 日 23:59（新加坡时间，UTC+8）结束。设了 refresh: true 的调用按未命中计费。max_results 和 include_content 不影响价格。价格在请求到达时确定，实际扣了多少看 x-dipper-cost-usd。

预充值，没有订阅，最低充值 $10。充值请发邮件到 hello@dipper-search.com，银行卡支付还在接入中。余额不够付一次调用时，会返回 402 insufficient_balance。

免费额度

用 GitHub 登录就送免费额度，不用绑卡：GitHub 账号注册满 30 天送 1000 次请求，不满 30 天送 300 次。每个 GitHub 账号只能领一次。不满 30 天的账号，满 30 天后再登录一次，会补足到 1000 次。

免费额度以美元记入余额，按未命中价格折算：300 次是 $0.24，1000 次是 $0.80。命中缓存花得更少。首发优惠期间，一次命中只用掉 0.2 次请求的额度，优惠结束后是 0.4 次。

错误

错误响应采用 OpenAI 风格的结构：

{ "error": { "message": "Insufficient balance. Top up to continue.", "type": "insufficient_balance" } }

也可能出现 500、502 和 504，都可以放心重试。出错的调用一律不收费。

速率限制

每个密钥大约每 10 秒最多 50 个请求。所有需要认证的请求都算在内，包括 MCP 调用和账户接口。超过之后返回 429 rate_limit_error，等几秒再试。

免费 MCP 端点有自己的限制：每个客户端每分钟大约 20 个请求，外加上面说的每小时共用额度。