Web 获取（Web Fetch）

让任意模型都能从 URL 获取内容

openrouter:web_fetch 服务端工具让任意模型都能从指定 URL 获取内容。当模型需要阅读网页或 PDF 文档时，会带着该 URL 调用此工具。OpenRouter 获取并提取内容，将文本返回给模型，供其在回复中使用。

工作原理

1. 在 tools 数组中加入 { "type": "openrouter:web_fetch" }。
2. 模型根据用户的提示词决定是否需要获取某个 URL，并生成请求。
3. OpenRouter 使用配置的引擎获取该 URL（默认为 auto：若可用则使用模型服务提供商的原生获取，否则回退到 Exa）。
4. 页面内容（文本、标题和 URL）返回给模型。
5. 模型将获取的内容纳入回复。如有需要，它可能在同一次请求中获取多个 URL。

快速开始

const response = await fetch('https://openrouter.ai/api/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <OPENROUTER_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/gpt-5.2',
    messages: [
      {
        role: 'user',
        content: '总结 https://example.com/article 的内容'
      }
    ],
    tools: [
      { type: 'openrouter:web_fetch' }
    ]
  }),
});

const data = await response.json();
console.log(data.choices[0].message.content);

配置

Web 获取工具接受可选的 parameters，用于自定义行为：

{
  "type": "openrouter:web_fetch",
  "parameters": {
    "engine": "exa",
    "max_uses": 10,
    "max_content_tokens": 100000,
    "allowed_domains": ["docs.example.com"],
    "blocked_domains": ["private.example.com"]
  }
}

引擎选择

Web 获取服务端工具支持多种获取引擎：

• auto（默认）：若模型服务提供商支持原生获取则使用原生获取，否则回退到 Exa
• native：强制使用服务提供商内置的网页获取
• exa：使用 Exa 的 Contents API 提取页面内容（支持自带密钥，BYOK）
• openrouter：使用直接 HTTP 获取并提取内容
• firecrawl：使用 Firecrawl 的 scrape API（BYOK）
• parallel：使用 Parallel 的 extract API 进行高质量内容提取

引擎能力

Firecrawl（自带密钥，BYOK）

Firecrawl 使用你自己的 API 密钥。设置步骤：

1. 前往 OpenRouter 插件设置 并配置你的 Firecrawl API 密钥
2. 你的 Firecrawl 账户与 OpenRouter 分开计费

硬性上限

为防止费用失控：

• Exa 引擎：无硬性上限（通过 API 额度计费）
• Parallel 引擎：无硬性上限（通过 API 额度计费）
• Firecrawl 引擎：无硬性上限（消耗你的 Firecrawl 额度）
• OpenRouter/原生引擎：每次请求硬性上限为 50 次获取

域名过滤

使用 allowed_domains 和 blocked_domains 限制可获取的域名：

{
  "type": "openrouter:web_fetch",
  "parameters": {
    "allowed_domains": ["docs.example.com", "api.example.com"],
    "blocked_domains": ["internal.example.com"]
  }
}

设置 allowed_domains 后，只会获取这些域名下的 URL。设置 blocked_domains 后，这些域名下的 URL 会被拒绝。

内容截断

使用 max_content_tokens 限制返回的内容量：

{
  "type": "openrouter:web_fetch",
  "parameters": {
    "max_content_tokens": 50000
  }
}

超出该上限的内容会被截断。在获取大型页面时，这有助于控制上下文窗口占用。

也可用于 Responses API

Web 获取服务端工具也可用于 Responses API：

const response = await fetch('https://openrouter.ai/api/v1/responses', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <OPENROUTER_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/gpt-5.2',
    input: 'https://example.com/docs 上的文档说了什么？',
    tools: [
      { type: 'openrouter:web_fetch', parameters: { max_content_tokens: 50000 } }
    ]
  }),
});

const data = await response.json();
console.log(data);

响应格式

模型调用 Web 获取工具时，会收到类似如下的响应：

{
  "url": "https://example.com/article",
  "title": "文章标题",
  "content": "页面的完整文本内容...",
  "status": "completed",
  "retrieved_at": "2025-07-15T14:30:00.000Z"
}

若获取失败，响应会包含错误信息：

{
  "url": "https://example.com/404",
  "status": "failed",
  "error": "HTTP 404: Page not found"
}

定价

以上费用均叠加在处理所获取内容产生的标准 LLM Token 费用之上。

后续步骤

• 服务端工具概览 — 了解 服务端工具
• Web 搜索（Web Search） — 搜索网络 以获取实时信息
• Datetime — 获取当前 日期和时间
• 工具调用 — 了解用户自定义 工具调用