exa-contents

Exa 内容

需要 API 密钥：在 https://dashboard.exa.ai/api-keys 获取

请求头：x-api-key: $EXA_API_KEY

当 Agent 已知 URL，且需要提取干净、适用于大模型的内容，而无需执行新搜索时，请使用 POST https://api.exa.ai/contents。先选择一种内容模式：highlights 用于提供精简的 Agent 上下文，text 用于提供全面的页面上下文，或 summary 用于由 Exa 压缩内容。

快速开始（cURL）

基本文本提取

curl -sS -X POST "https://api.exa.ai/contents" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "urls": ["https://example.com"],
    "text": true
  }'

控制内容时效性的摘要

curl -sS -X POST "https://api.exa.ai/contents" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "urls": ["https://arxiv.org/abs/2307.06435"],
    "highlights": {
      "query": "methodology and results"
    },
    "maxAgeHours": 24,
    "livecrawlTimeout": 12000
  }'

端点

POST https://api.exa.ai/contents

身份验证：使用 x-api-key: <API_KEY> 请求头。Exa 也接受 Authorization: Bearer <API_KEY>，但为保持一致，cURL 示例中优先使用 x-api-key。

已知 URL 的内容提取请使用此端点。如果 Agent 需要先发现或排序内容，请使用 POST /search。

参数

核心请求参数

参数	类型	必填	默认值	描述
urls	string[]	是	-	要提取内容的 URL。用于已知 URL。
text	boolean or object	否	-	以 Markdown 格式返回完整页面文本。对象形式支持 maxCharacters、includeHtmlTags、verbosity、includeSections 和 excludeSections。
highlights	boolean or object	否	-	返回关键摘录。除非需要自定义关注点，否则建议在 Agent 工作流中设为 true。
summary	boolean or object	否	-	返回每页的大模型摘要。适用于调用方需要由 Exa 压缩内容或进行结构化提取的情况。
maxAgeHours	integer	否	-	控制内容时效性。0 表示始终实时抓取；-1 表示仅使用缓存；省略则默认优先使用缓存，抓取作为回退方案。
livecrawlTimeout	integer	否	10000	实时抓取的超时时间，单位为毫秒。对于大多数对时效性敏感的调用，建议设为 10000 至 15000。
subpages	integer	否	0	从每个 URL 抓取的链接子页面数量。
subpageTarget	string or string[]	否	-	用于优先选择相关子页面的词语，例如 ["api", "reference", "pricing"]。
extras.links	integer	否	0	从每个页面提取的链接数量。
extras.imageLinks	integer	否	0	从每个页面提取的图片 URL 数量。
compliance	string	否	-	企业专用合规模式，例如在账户中启用时使用的 hipaa。

Text 对象选项

参数	类型	默认值	描述
maxCharacters	integer	-	返回文本的字符数上限。请用此参数替代 tokensNum。
includeHtmlTags	boolean	false	在输出中保留 HTML 标签。
verbosity	string	compact	可选值：compact、standard 或 full。将新鲜度与分节提取搭配使用时，设置 maxAgeHours: 0。
includeSections	string[]	-	仅包含选定的部分：header、navigation、banner、body、sidebar、footer、metadata。
excludeSections	string[]	-	从同一部分列表中排除选定部分。

Highlights 对象选项

默认情况下，建议使用 highlights: true，以获得最高质量的结果。只有 Agent 需要自定义关注点或字符数预算时，才使用对象形式。

参数	类型	默认值	描述
query	string	-	用于引导返回哪些摘录的自定义查询。
maxCharacters	integer	-	限制每个 URL 的摘要字符数。除非调用方有严格的字符数预算，否则不要设置。

Summary 对象选项

参数	类型	默认值	描述
query	string	-	摘要的自定义查询。
schema	object	-	用于生成结构化页面摘要的 JSON Schema。

内容模式

在 /contents 中，text、highlights 和 summary 是顶层请求字段。

模式	最适用于	备注
text	深度分析和广泛的页面上下文	使用 maxCharacters 限制载荷大小。
highlights	Agent 工作流和事实查询	默认选项中最节省 token。摘录以源页面内容为依据。
summary	内容压缩或按页面结构化提取	为每个页面添加 Exa 侧的综合内容。

除非调用方确实需要同一页面的多个视图，否则避免请求多种模式。

新鲜度和抓取

使用 maxAgeHours 作为规范的新鲜度控制参数。

值	行为
省略	使用默认的缓存优先行为，并在需要时回退到抓取。
正整数	如果缓存内容的时间在 N 小时以内，则使用缓存；否则进行实时抓取。
0	始终进行实时抓取。新鲜度最高，但延迟较高。
-1	仅使用缓存。速度最快，但没有缓存内容时会失败。

当实时抓取不应超过固定时限时，设置 livecrawlTimeout。

子页面和额外内容

当链接页面很重要时，使用 subpages 和 subpageTarget。

curl -sS -X POST "https://api.exa.ai/contents" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "urls": ["https://docs.example.com"],
    "text": {
      "maxCharacters": 5000
    },
    "subpages": 10,
    "subpageTarget": ["api", "reference", "guide"],
    "extras": {
      "links": 10,
      "imageLinks": 5
    }
  }'

先将 subpages 设为 5 到 10 左右，仅在调用方需要更广泛的网站覆盖时再增加。

响应字段和状态

即使 HTTP 状态为 200，也要检查 statuses。同一请求中的某个 URL 可能成功，而另一个 URL 可能失败。

curl -sS -X POST "https://api.exa.ai/contents" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "urls": ["https://example.com", "https://failed-url.example.com"],
    "highlights": true
  }' | jq '{results, statuses}'

字段	类型	描述
requestId	string	唯一请求标识符。
results	array	提取出的内容结果对象。
results[].title	string	页面标题。
results[].url	string	页面 URL。
results[].publishedDate	string 或 null	可用时提供的估计发布日期。
results[].author	string 或 null	可用时提供的作者。
results[].text	string	请求 text 时返回。
results[].highlights	string[]	请求 highlights 时返回。
results[].highlightScores	number[]	摘录的相似度分数。
results[].summary	string	请求 summary 时返回。
results[].subpages	array	从子页面抓取中获取的嵌套结果对象。
results[].extras.links	string[]	请求时提取的链接。
statuses	array	每个 URL 的成功或错误状态。务必检查此字段。
statuses[].id	string	请求的 URL。
statuses[].status	string	success 或 error。
statuses[].error.tag	string	失败 URL 的错误类型。
statuses[].error.httpStatusCode	integer 或 null	与单个 URL 失败相关的 HTTP 代码。
costDollars.total	number	返回时提供的请求总费用。

常见的单个 URL 错误标签包括 CRAWL_NOT_FOUND、CRAWL_TIMEOUT、CRAWL_LIVECRAWL_TIMEOUT、SOURCE_NOT_AVAILABLE、UNSUPPORTED_URL 和 CRAWL_UNKNOWN_ERROR。

关键注意事项

• 在 /contents 中，将 text、highlights 和 summary 保持为顶层字段。
• 不要将提取选项包装在 contents 对象中；这种嵌套属于 /search。
• 不要认为 HTTP 200 就意味着所有 URL 都成功；请检查 statuses。
• 不要发送 stream: true；/contents 不是流式端点。
• 不要发送 tokensNum；使用 text.maxCharacters 限制提取文本。
• 不要在新请求中使用 useAutoprompt、numSentences、highlightsPerUrl 或旧版 livecrawl 字符串值。
• 优先使用 maxAgeHours 控制新鲜度，并在抓取延迟很重要时配合使用 livecrawlTimeout。
• 使用 subpages 时同时设置 subpageTarget；否则子页面选择将尽力而为。
• 默认选择 highlights、text 或 summary 之一。只有在调用方确实需要每个页面的多个视图时，才叠加多种模式。