第1章 You.com Web Search API 教程
Web Search API 概述：获取面向大语言模型优化的结构化网页和新闻搜索结果。
通过 MCP 将 You.com 接入你的智能体或 IDE——连接地址为 https://api.you.com/mcp。你可以尝试在 https://api.you.com/mcp?profile=free 上进行无需注册的搜索体验（使用 you-search 和 you-discover 工具）。研究和金融场景可使用 /mcp/research 和 /mcp/finance，或在 /mcp 后附加 ?tools= 参数。MCP 服务器指南 →
安装 Docs MCP 服务器：Docs MCP 服务器允许你的智能体搜索整套文档，且完全免费。安装地址为 https://you.com/docs/_mcp/server。请参阅 Docs MCP 服务器指南以了解更多详情。
什么是 You.com Web Search API You.com Web Search API 提供高质量的结构化网页和新闻结果，专为 AI 应用程序的编程访问而优化。该 API 旨在服务于构建 RAG 系统、AI 智能体、知识库及数据驱动应用的开发者，返回包含丰富元数据、相关片段和完整页面内容的干净结构化数据。
如果任务目标是获取带引用的答案而非原始结果，或者你已经有现成的 URL，请通过“选择合适的 API”将任务映射到 Answer API、Research API、Contents API 或 Finance Research API。
端点 每个 API 都有独立的端点。每次请求都需通过 X-API-Key 请求头发送你的 API 密钥。
API | 端点 | 指南 | API 参考 Web Search API | POST https://ydc-index.io/v1/search（也支持 GET） | 概述 | /v1/search Contents API | POST https://ydc-index.io/v1/contents | 概述 | /v1/contents Answer API | POST https://api.you.com/v1/answer | 概述 | /v1/answer Research API | POST https://api.you.com/v1/research | 概述 | /v1/research Finance Research API | POST https://api.you.com/v1/finance_research | 概述 | /v1/finance_research
Answer、Research 和 Finance Research API 仅在 api.you.com 上运行。向 ydc-index.io 发送这些路径会返回 403 错误，响应体为 {"message": "Missing Authentication Token"}，即使密钥有效也是如此。
工作原理 Web Search API 处理你的查询，并在单次请求中返回来自网页和新闻源的统一结果。每个结果都包含核心信息（URL、标题和描述）以及丰富的元数据，如发布日期、缩略图和站点图标。
每个结果返回的文本内容取决于 extraction 参数：
请求方式 | 每个结果返回的文本 无 extraction 参数 | snippets——简短的、以关键词为中心的片段 extraction_mode: "full_page" | snippets，以及包含整个页面内容的 contents.markdown 或 contents.html extraction_mode: "highlights" | contents.highlights——针对你的查询的相关段落。不包含 snippets
我们的分类系统根据查询意图决定何时包含新闻结果。设置 knowledge: "core" 可同时在 results.knowledge 中请求授权数据结果。
返回内容 每次搜索都返回结构化 JSON，主要包含两种结果类型，如果你请求了知识结果，还会包含知识结果：
网页结果 * 来自互联网的无关网页 * 每个结果包含多个文本片段以提供上下文（如果你请求了 highlights，则会被替换） * 发布日期 * 用于 UI 显示的缩略图片和站点图标
新闻结果（当相关时） * 来自权威来源的最新新闻文章 * 文章摘要和标题 * 发布时间戳以反映新鲜度 * 相关图片和元数据 * 通过全文提取获取的完整文章内容（HTML 或 Markdown）
知识结果（当 knowledge: "core" 且查询匹配时） * 带有提供者归属信息的授权数据答案 * 如果没有相关内容，则不会出现在响应中
示例响应结构： { "results": { "web": [ { "url": "https://example.com/article", "title": "Article Title", "description": "Brief description of the content", "snippets": [ "Relevant excerpt from the page", "Another relevant passage" ], "thumbnail_url": "https://example.com/image.jpg", "page_age": "2025-11-15T10:30:00", "favicon_url": "https://example.com/favicon.ico" } ], "news": [ { "title": "Breaking News Article", "description": "News article summary", "url": "https://news.com/article", "page_age": "2025-11-15T14:00:00", "thumbnail_url": "https://news.com/image.jpg" } ] }, "metadata": { "search_uuid": "942ccbdd-7705-4d9c-9d37-4ef386658e90", "query": "your search query", "latency": 0.342 }}
所有结果均以干净的结构化 JSON 格式返回，无需进行 HTML 解析或后处理。
功能特性 每个结果可携带三个层级的文本。选择哪一级取决于阅读者是人是模型。
特性 | 片段 (Snippets) | 高亮 (Highlights) | 全文 (Full page) 返回条件 | 默认，无 extraction | extraction_mode: "highlights" | extraction_mode: "full_page" 响应字段 | snippets | contents.highlights | contents.markdown / contents.html 选择依据 | 关键词匹配 | 与你的查询相关度 | 整个页面 适用场景 | 渲染结果 UI | 为智能体或 RAG 提示词提供依据 | 归档、全文档分析
请参阅“获取页面内容”以了解 highlights 与 full page 的区别、extraction_source、爬取超时设置以及与 Contents API 的对比。
功能 | 作用 知识 | results.knowledge 中的授权数据结果 获取页面内容 | 每个结果的高亮片段或全文 Markdown/HTML 新闻结果 | 当查询具有新闻意图时的新闻文章 请求控制 | 新鲜度、国家、语言、域名、分页、安全搜索 搜索运算符 | 查询中支持的 site:, filetype:, AND, OR, NOT, + 和 -
如果你已经有 URL 且不需要先进行搜索，请使用 Contents API。
参数
参数 | 类型 | 描述 query | string | 你的搜索查询（支持搜索运算符） count | integer | 每个部分的最大结果数（默认值因情况而异，最大 100） freshness | string | day, week, month, year 或日期范围 country | string | 国家代码（例如 US, GB, FR） language | string | BCP 47 语言代码（例如 EN, JA, DE） offset | integer | 用于分页（0-9） safesearch | string | off, moderate (默认), strict knowledge | string | core。请求知识结果。仅限 POST extraction | object | 每个结果提取的内容。extraction_mode 为 full_page 或 highlights。仅限 POST extraction.extraction_source | string | 全文内容来源：blend (默认), cache 或 fetch extraction.full_page.extraction_formats | array | html, markdown 或两者。默认为 ["markdown"] crawl_timeout | integer | 最大爬取超时时间（秒，1-60，默认 10）。仅适用于 extraction_mode 为 full_page 时 include_domains | string (GET) / array (POST) | 将结果限制在这些域名。GET：逗号分隔字符串。POST：JSON 数组。支持最多 500 个域名 exclude_domains | string (GET) / array (POST) | 排除这些域名的结果。GET：逗号分隔字符串。POST：JSON 数组。支持最多 5000 个域名 boost_domains | string (GET) / array (POST) | 提升这些域名的结果，不排除其他域名。GET：逗号分隔字符串。POST：JSON 数组。支持最多 500 个域名。不能与 include_domains 一起使用
查看完整 API 参考
通过 POST /v1/search 发送 JSON 正文来传递参数。数组字段使用纯 JSON 数组。
GET /v1/search 仍然可用，现有集成可继续运行，但不会收到新功能更新。新功能仅添加到 POST 方法中，且 extraction 和 knowledge 仅在那里可用。在 GET 请求中，域名过滤器必须符合单个逗号分隔的查询字符串值的格式，并受 URL 长度限制。
常见用例
RAG (检索增强生成) 使用搜索片段为 LLM 提供上下文，避免幻觉。结构化片段可直接输入提示词。对于令牌敏感的流程，请请求 highlights 代替。 深度搜索模板：查看一个使用多轮查询扩展以呈现更相关结果的应用程序。
代码示例： from youdotcom import You you = You()
def get_context(query): res = you.search(query=query, count=5) snippets = [] if res.results and res.results.web: for result in res.results.web: if result.snippets: snippets.extend(result.snippets) return "\n".join(snippets)
user_question = "What is the current state of quantum computing?" context = get_context(user_question) prompt = f"Based on this information:\n{context}\n\nAnswer: {user_question}"
AI 智能体知识检索 让 AI 智能体访问实时网页信息——包括最新事实、新闻或特定领域知识。 简单搜索模板：查看一个执行网页搜索并返回主要结果的应用程序。
新闻监控与警报 跟踪突发新闻、竞争对手提及或行业趋势。分类功能会在相关时包含新闻结果。请参阅新闻结果。
内容研究与分析 为内容创作、竞争情报或市场研究从多个来源收集信息。
知识库构建 使用全文提取构建包含干净 Markdown 格式完整页面内容的知识库。
最佳实践
1. 为 RAG 使用 highlights 请求 extraction_mode: "highlights" 并读取 contents.highlights。你将获得与查询最相关的段落，其大小已适配提示词，无需支付爬取和处理整个页面的费用。当为人类渲染结果而非为模型提供依据时，可回退使用 snippets 数组。
2. 实现缓存 缓存频繁查询以减少 API 调用并提高响应时间。大多数用例建议设置 5-15 分钟的 TTL。
3. 处理空结果 在处理前，始终检查 results.web 或 results.news 数组是否为空： if res.results and res.results.web: for result in res.results.web: process(result) else: handle_no_results()
4. 使用合适的 count 值 * 对于 RAG：count=5-10 通常足够 * 对于 UI 显示：count=20-50 用于分页 * 对于数据收集：count=100 (最大) 用于全面覆盖
5. 使用搜索运算符和查询参数 使用搜索运算符和请求控制来减少噪音，获取更相关的结果。
定价 每 1,000 次调用 $5.00（每次调用最多 100 个结果） 请参阅账单页面了解完整定价详情。 智能体也可以按调用付费而无需账户。GET /v1/search 和 /v1/agents/search 的两种动词均支持机器支付，每请求使用 USDC 从已充值的钱包结算，而不是扣除信用额度。
包含内容： * 在单一统一请求中返回网页和新闻结果 * 每次调用最多 100 个结果 * 新闻结果无额外费用 * 授权数据提供者的知识结果无额外费用 * 带有丰富元数据的 LLM 就绪片段 * 国家、语言、时效性、域名等定向过滤器
全文提取附加项——每 1,000 个实时抓取页面 $1.00 通过 extraction_mode: "full_page" 获取的全文内容（HTML、Markdown 或两者）独立于基础 Web Search API 费率单独计费。仅对实时爬取的页面计费，因此费用取决于 extraction_source：fetch 爬取每个结果，blend (默认) 仅对无法从缓存提供的页面收费，而 cache 不收取任何提取费用。 示例：单次调用 count=10 且 extraction_mode: "full_page" 返回 10 个网页结果和 10 个新闻结果，共 20 页。此调用未设置 extraction_source，因此运行 blend。假设 20 页中有 2 页已缓存，其余 18 页为实时爬取。
项目 | 计算 | 成本 Web Search API 调用 | 1 次调用 × $5.00 / 1,000 | $0.005 全文提取，实时爬取 | 18 页 × $1.00 / 1,000 | $0.018 全文提取，来自缓存 | 2 页 × $0.00 | $0.000 总计 | | $0.023
缓存覆盖率因查询而异，因此应将此拆分视为一种结果而非预算费率。如果所有 20 页均为实时爬取，此调用成本为 $0.025；如果使用 extraction_source: "cache"，成本为 $0.005。请参阅账单页面了解完整分解。
如需批量折扣、年度定价或企业功能，请访问 you.com/pricing 或联系 api@you.com。
数据保留 受严格隐私、合规或安全指令约束的组织可以在企业协议中添加零数据保留 (ZDR)。ZDR 限制账户范围内 Web Search API 请求和响应内容的保留，且无需更改集成配置。请参阅零数据保留了解其覆盖范围及启用方法。
常见问题 我可以在使用 You.com 的同时使用其他网页索引吗？ 可以。在已使用的索引旁边调用 Web Search API，并在应用程序中结合或路由结果。没有独家索引要求。 我可以在不使用 LLM 的情况下使用 API 吗？ 可以。Web Search API 和 Contents API 返回结构化 JSON——包括 URL、标题、片段和可选页面文本——因此你可以驱动搜索 UI 或检索管道，而无需调用模型。
后续步骤 快速入门：发起第一个 Web Search API 请求 API 参考：探索包含所有参数和响应模式的完整 API 文档 获取页面内容：每个结果的高亮与全文内容 评估方法：基准测试检索质量、延迟和新鲜度
