You.com 快速上手：用五个 API 为 AI 应用接入实时网络情报

You.com 面向 AI 应用提供一套实时网络情报工具：你的智能体可以搜索网页、抽取指定 URL 的正文、生成带引用的答案，以及执行多步深度研究。它把能力拆成五个 API——Web Search、Contents、Answer、Research、Finance Research——但共用同一套鉴权、SDK 与控制台，因此可以按需组合成更复杂的智能体工作流。如果你正在为 LLM 应用补上「实时、可引用、结构化」的网页信息层，这套接口值得先跑通一遍。站内也有对应的工具条目可以一并参考：You.com。

本文按「准备 → 分步调用 → 完整示例 → 注意事项」的顺序展开，重点放在真实的请求参数与返回字段上，方便你直接照着改。

准备工作

账号与密钥

调用 You.com 的 API 需要一枚 API Key。请求时把它放在 X-API-Key 请求头里，这是所有接口统一的鉴权方式。密钥在控制台中管理，同一份凭据对五个 API 都有效，不需要为每个接口单独申请。

如果你只是想先试一下，MCP Server 提供了一条免账号、免密钥的路径：把 https://api.you.com/mcp?profile=free 作为 HTTP 传输的 MCP 服务地址接入即可。以 Claude Code 为例，命令形如：

claude mcp add --transport http youdotcom "https://api.you.com/mcp?profile=free"

这条路径适合快速验证效果，正式接入生产环境时仍建议使用带密钥的 API 调用。

SDK 与依赖

官方提供类型化的 Python 客户端，覆盖全部五个 API，同时附带 CLI 与 OpenAPI 规范。安装后即可用上下文管理器的方式发起调用。除 Python 外，官方还列出了与 LangChain、LlamaIndex、crewAI、Vercel AI SDK、n8n、Zapier、Pydantic、Replit 等框架和平台的集成方式，你可以按现有技术栈选择接入点。

先想清楚用哪个 API

五个接口的分工并不重叠，选错会让后续处理变麻烦：

• Web Search API：返回实时、面向 LLM 的网页与新闻结果。适合「把检索结果喂给模型」这类场景。
• Contents API：把你指定的任意 URL 转成干净的 Markdown 或 HTML。适合在搜索之后抓正文。
• Answer API：针对单个查询返回带引用的、经过综合的答案。适合需要直接给用户一段可溯源回答的场景。
• Research API：智能体式的多步研究，输出带引用的综合结论。适合问题本身需要拆解、多轮检索才能回答的场景。
• Finance Research API：同样是智能体式研究，但聚焦于金融与数值类数据。

官方文档里有一页专门做「选哪个 API」的对比，从任务匹配度、延迟和价格三个维度横向比较五个接口。在动手写代码之前先看这一页，比事后重构调用链要省事。

操作步骤

第一步：用 Python SDK 发起一次搜索

最直接的入口是 SDK 的 You 客户端。下面这段代码发起一次查询，并遍历返回的网页结果，打印标题、URL 和第一条摘要：

from youdotcom import You

with You() as you:
    res = you.search(
        query="best practices for scaling microservices architecture in production",
    )

    # Each result contains a title, URL, snippets and more
    if res.results and res.results.web:
        for result in res.results.web:
            print(f"Title: {result.title}")
            print(f"URL: {result.url}")
            if result.snippets:
                print(f"Snippet: {result.snippets[0]}\n")

注意返回结构：结果挂在 results 下，网页结果在 results.web 数组里，每条结果包含 title、url、snippets 等字段。snippets 是一个数组，通常取第一条作为摘要展示即可。

第二步：直接调用 REST 接口

不走 SDK 时，Web Search 的端点是 POST https://ydc-index.io/v1/search。用 cURL 发起请求的写法如下：

curl -X POST https://ydc-index.io/v1/search \
  -H "X-API-Key: <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the latest geopolitical updates from India",
    "count": 10,
    "include_domains": ["timesofindia.indiatimes.com", "ndtv.com", "thehindu.com"]
  }'

这里出现了三个关键参数：

• query：查询语句。这个端点会基于分类机制判断该返回网页结果还是新闻结果，所以像「某地最新动态」这类问句可以直接作为查询传入。
• count：返回结果数量，示例中取 10。
• include_domains：限定来源域名，示例中限定为三家印度新闻站点。这是控制结果质量最有效的手段之一。

第三步：读懂返回结构

一次成功的请求返回 HTTP 200，响应体大致长这样（已省略部分内容）：

{
  "results": {
    "web": [
      {
        "url": "https://timesofindia.indiatimes.com/topic/geopolitics/news",
        "title": "Geopolitics News | Latest News on Geopolitics - Times of India",
        "description": "...",
        "snippets": ["...", "...", "..."],
        "thumbnail_url": "https://static.toiimg.com/photo/47529300.cms",
        "favicon_url": "https://you.com/favicon?domain=timesofindia.indiatimes.com&size=128"
      }
    ],
    "news": [
      {
        "title": "India entering golden era of defence innovation: Rajnath",
        "description": "...",
        "page_age": "2025-11-25T12:31:29",
        "thumbnail_url": "...",
        "url": "https://theprint.in/india/india-entering-golden-era-of-defence-innovation-rajnath/2791865/"
      }
    ]
  },
  "metadata": {
    "search_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "query": "What are the latest geopolitical updates from India",
    "latency": 0.6842031478881836
  }
}

几个值得注意的字段：

• results.web 与 results.news 是两个并列数组。网页结果带 snippets（多条摘要片段），新闻结果带 page_age（发布时间），两者字段并不完全一致，解析时要分别处理。
• 每条结果都带 thumbnail_url 和 favicon_url，可以直接用于前端展示。注意 favicon_url 的查询串里 & 在 JSON 中会被转义。
• metadata 里有 search_uuid、回显的 query 以及 latency（本次请求耗时，单位秒）。排查问题时 search_uuid 是最有用的定位信息。

第四步：按需切换到其他 API

拿到搜索结果之后，常见的下一步是把某个 URL 的正文抓下来。这一步交给 Contents API：传入 URL，返回干净的 Markdown 或 HTML，省去自己写正文抽取规则。相比直接抓页面再清洗，这种方式得到的文本更适合直接拼进提示词。

如果不想自己拼接检索结果与提示词，可以改用 Answer API：一次查询直接返回带引用的综合答案。它的输出已经完成了「检索 + 综合 + 标注来源」，适合问答类界面。

当问题需要多轮拆解——比如「比较某行业几家公司的技术路线差异」——单次搜索往往不够，这时用 Research API。它以智能体方式执行多步研究，最终给出带引用的综合结论。若研究目标集中在财务与数值数据上，则用 Finance Research API，它的研究过程针对这类数据做了聚焦。

第五步：接入智能体框架

除了直接调用，You.com 还提供 MCP Server、Skills 以及面向各类编码智能体的接入方式，覆盖 Claude Code、Cursor、Codex、VS Code、Windsurf、Gemini CLI、JetBrains IDE、Zed、GitHub Copilot CLI 等。MCP 的接入命令在准备工作一节已经给出，把 profile=free 换成带密钥的配置即可用于正式环境。

一个完整示例

下面把「搜索 → 抽取正文」串成一条最小可跑通的链路。假设你已经装好 Python SDK 并配置好 API Key。

第一步，限定来源做一次搜索。用 include_domains 把范围收窄到几个可信站点，避免结果里混入低质量内容：

from youdotcom import You

with You() as you:
    res = you.search(
        query="What are the latest geopolitical updates from India",
        count=10,
        include_domains=[
            "timesofindia.indiatimes.com",
            "ndtv.com",
            "thehindu.com",
        ],
    )

    web_results = res.results.web if res.results else []
    for item in web_results:
        print(item.title)
        print(item.url)

第二步，挑出需要精读的 URL。把上一步打印出的 URL 收集起来，按业务规则筛选，比如只保留前三条，或者只保留域名权重较高的来源。

第三步，用 Contents API 抓取正文。把选中的 URL 交给 Contents API，取回 Markdown 或 HTML。到这一步，你手上就有了「结构化元数据 + 干净正文」两部分材料，可以直接拼进提示词交给模型。

第四步，需要引用时改用 Answer API。如果最终产物是给用户看的回答，而不是喂给模型的原料，那么把同样的查询交给 Answer API，直接拿到带引用的综合答案，省掉自己组织引用格式的工作。

这条链路的顺序不是固定的：也可以先用 Answer API 拿到答案，再针对答案里引用的具体 URL 用 Contents API 取全文做二次核对。

注意事项

关于结果分类

Web Search 端点会根据查询内容做分类，决定返回网页结果还是新闻结果。这意味着同一个端点在不同查询下返回的数组可能不同——有时 results.web 有内容，有时 results.news 有内容。解析响应时两个数组都要判空处理，不要假定只有一个存在。

关于字段差异

网页结果与新闻结果的字段并不一致：网页结果带 snippets 数组，新闻结果带 page_age 时间戳。写解析逻辑时按类型分别取值，不要用同一套字段名硬套。

关于域名限定

include_domains 是提升结果相关性的有效手段，但需要你事先知道目标域名。如果对领域不熟悉，可以先不加限定跑一次，观察返回的来源分布，再决定收窄到哪些域名。

关于密钥与配额

API Key 通过 X-API-Key 请求头传递，不要写死在客户端代码里。控制台提供密钥管理、团队管理、SSO 与 SCIM、零数据留存（Zero Data Retention）等管理能力，团队协作场景下应结合这些功能做权限划分。具体的速率限制与计费标准请以官网当前信息为准，本文不列举具体数字。

关于免费接入路径

MCP 的 profile=free 配置无需账号与密钥即可试用，适合评估阶段。但它与带密钥的正式调用在能力与配额上并不等同，上线前需要切换到正式配置。

关于价格与功能变动

接口的参数、返回字段、可用地区与计费方式都可能调整。动手接入前，请以官网当前公布的文档与价格信息为准。