第2章 You.com Contents API

API / Contents API / Contents API 概述：按需从任意网页提取干净的 HTML 或 Markdown 内容。|以 Markdown 查看|在 Claude 中打开|通过 MCP 将 You.com 接入你的 Agent 或 IDE——连接地址为 https://api.you.com/mcp。无需注册即可在 https://api.you.com/mcp?profile=free 试用搜索功能（you-search 和 you-discover）。研究和金融场景请使用 /mcp/research 和 /mcp/finance，或在 /mcp 后加 ?tools= 参数。MCP Server 指南 →

安装 Docs MCP Server：Docs MCP Server 可以让你的 Agent 检索全部文档，免费使用。安装地址：https://you.com/docs/_mcp/server。详情请参阅 Docs MCP Server 指南。

What Is the Contents API?

Contents API 用于从给定 URL 提取干净的 HTML 或 Markdown 内容。传入一组 URL，即可获得每个页面的完整内容，直接可供 LLM 使用——无需解析、没有 HTML 噪音，也不需要浏览器自动化。

Endpoints

每个 API 都有独立的 endpoint。所有请求都需要在 X-API-Key 请求头中携带你的 API key。

| API | Endpoint | 指南 | 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 访问。即使 key 有效，向 ydc-index.io 发送这些路径也会返回 403，并附带 {"message": "Missing Authentication Token"}。

How It's Different From Full Page Extraction

Contents API 和 Web Search API 的全页提取都能获取完整页面内容，但适用的工作流不同：

| | Contents API | Web Search API + 全页提取 | |---|---|---| | 起点 | 已经知道 URL | 有查询需求，但没有 URL | | 使用场景 | 按需抓取已知页面 | 为搜索结果补充完整内容 | | URL 来源 | 由你提供 | 由 You.com 搜索发现 | | 批量大小 | 每次请求 10 个 URL | 每次搜索最多 100 条结果 | | 定价 | 每 1000 页 $1.00 | 每 1000 次搜索 $5.00 + 每抓取 1000 页 $1.00 |

如果你有一份确定的 URL 列表需要读取，用 Contents API；如果想在一次调用中同时拿到搜索结果和完整内容，用 extraction_mode: "full_page"。参见 Retrieve page content。

What You Get

请求中的每个 URL 都会返回一个结构化对象：

``` [ { "url": "https://competitor.com/pricing", "title": "Pricing — Competitor Inc.", "markdown": "# Pricing\n\n## Starter Plan\n$49/month...", "html": "...", "metadata": { "site_name": "Competitor Inc.", "favicon_url": "https://ydc-index.io/favicon?domain=competitor.com&size=128" } } ] ```

通过 formats 参数控制返回哪些格式，可以任意组合请求 markdown、html 和/或 metadata。

Key Features

任意 URL，按需抓取 单次请求最多可传 10 个 URL，API 会并行抓取并返回内容。无需自己维护无头浏览器或处理原始 HTML。

LLM 友好的 Markdown markdown 格式会自动去除导航菜单、广告、页脚等模板内容，只保留页面的实际内容——可直接放入 prompt。

可配置的超时 通过 crawl_timeout（1–60 秒）在速度和完整性之间做权衡。加载快的页面建议 5–10 秒；重度依赖 JavaScript 渲染的页面建议 20–30 秒。

缓存新鲜度控制 默认情况下，Contents API 可能返回缓存的页面内容以降低延迟。可以用 max_age 控制缓存的新鲜度：传入一个秒数，超过该阈值的缓存内容会被忽略，强制重新抓取页面。 例如，max_age=86400 确保内容不超过 24 小时；max_age=0 则完全绕过缓存、总是重新抓取。不设置 max_age（默认值）则无论缓存多旧都接受。

Metadata 提取 在请求内容的同时获取 metadata，可获得页面的站点名称和 favicon URL——很适合构建需要展示信息来源的 UI。

Parameters

| 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | urls | 字符串数组 | 是 | 要抓取内容的 URL 列表 | | formats | 字符串数组 | 否 | 返回的内容格式：markdown、html、metadata（默认：markdown） | | crawl_timeout | 数字 | 否 | 单个 URL 的超时时间（秒），1 到 60 之间（默认：10） | | max_age | 整数 | 否 | 缓存内容允许的最大时长（秒），必须 ≥ 0。设置后，超过该时长的缓存内容会被忽略并重新抓取页面。默认：null（不限制时长） |

查看完整 API 参考

Common Use Cases

竞争情报 监控竞品的价格、功能或博客页面。定时抓取内容，交给 LLM 分析，自动发现重要变化——无需人工查看。

```python from youdotcom import You from youdotcom.models import ContentsFormats

competitor_pages = [ "https://competitor-a.com/pricing", "https://competitor-b.com/pricing", "https://competitor-c.com/features", ]

with You() as you: pages = you.contents( urls=competitor_pages, formats=[ContentsFormats.MARKDOWN], crawl_timeout=15, ) for page in pages: print(f"\n--- {page.title} ---") # 将 page.markdown 输入 LLM 做摘要或对比 print(page.markdown[:500]) ```

知识库构建 当你有一批权威来源——文档页面、白皮书、内部 wiki——可以批量抓取，转换成干净的 Markdown，然后索引到你的向量数据库中。

```python from youdotcom import You from youdotcom.models import ContentsFormats

# 待索引的权威来源 source_urls = [ "https://docs.example.com/api-reference", "https://docs.example.com/authentication", "https://docs.example.com/rate-limits", ]

with You() as you: pages = you.contents( urls=source_urls, formats=[ContentsFormats.MARKDOWN, ContentsFormats.METADATA], )

documents = [] for page in pages: documents.append({ "source": page.url, "title": page.title, "content": page.markdown, }) # 在这里把文档索引到你的向量数据库 ```

研究助手 让用户能针对特定 URL 提问。实时抓取页面内容并作为上下文输入 LLM——把任意 URL 变成可检索的文档。

```python from youdotcom import You from youdotcom.models import ContentsFormats

def fetch_url_context(url: str) -> str: with You() as you: pages = you.contents(urls=[url], formats=[ContentsFormats.MARKDOWN]) return pages[0].markdown if pages else ""

# 用户提问："帮我总结这个页面" url = "https://example.com/long-report" context = fetch_url_context(url) prompt = f"请总结以下页面内容：\n\n{context}" # 将 prompt 传给你的 LLM ```

Best Practices

只请求需要的格式 每种格式都会增加处理时间。如果只需要 Markdown 给 LLM 用，就不要请求 html；UI 里用不到站点信息，就跳过 metadata。

批量提交 URL 一次请求 10 个 URL 比发 10 次单独请求更快，API 会并行处理。

根据目标站点设置 crawl_timeout 简单的静态页面 5–10 秒通常足够；JavaScript 较重的页面（SPA、仪表盘）建议调到 20–30 秒，给渲染留出时间。

妥善处理部分失败 如果批量请求中某个 URL 抓取失败（例如需要登录或返回 404），API 会在其 markdown 和 html 字段返回 null。处理前务必检查：

```python for page in pages: if page.markdown: # 处理内容 pass else: print(f"抓取失败: {page.url}") ```

Pricing

每 1000 页 $1.00

完整定价详情请查看 Billing 页面。

包含内容：

- 单次请求可批量提交多个 URL - 输出干净的 Markdown 或原始 HTML - 提供 Python SDK、MCP Server 和 REST API - 无需浏览器自动化或 HTML 解析

如需批量折扣、年度定价或企业功能，请访问 you.com/pricing 或联系 api@you.com。

Next Steps

- Quickstart：发出你的第一个 Contents API 请求 - API Reference：完整的参数说明、请求/响应 schema 和错误码 - Web Search API Overview：将搜索结果与全页提取结合，在获取实时网络数据的同时拿到完整内容 - Python SDK：使用官方 SDK 获得更简洁的集成体验