已有 URL 时用 Exa Contents API…

当 agent 已持有 URL，且需要不经 SDK 用 cURL 或原始 HTTP 调用 Exa POST /contents 获取 LLM-ready 内容时适用。

适用场景

解决思路

1. 发送请求到 POST https://api.exa.ai/contents，使用 Content-Type: application/json 和 x-api-key: $EXA_API_KEY 请求头。
2. Exa 也接受 Authorization: Bearer <API_KEY>，但在 cURL 示例中优先使用 x-api-key 以保持一致。
3. 对已知 URLs 直接调用 POST https://api.exa.ai/contents 提取内容，不先跑搜索。
4. 如果 agent 需要先做发现或排序，使用 POST /search。
5. 默认从一种内容模式开始：highlights 用于紧凑 agent 上下文，text 用于广泛页面上下文，summary 用于 Exa 侧压缩。
6. 基本 text 提取时，用 curl -sS -X POST https://api.exa.ai/contents，加 -H Content-Type: application/json 与 -H x-api-key:$EXA_API_KEY，并用 -d 传 JSON 请求体，其中 urls 传 https://example.com，text 传 true。
7. Highlights 加 freshness 控制时，用同一 endpoint 发送请求体，其中 urls 传 https://arxiv.org/abs/2307.06435，highlights 传包含 query 为 methodology and results 的对象，maxAgeHours 传 24，livecrawlTimeout 传 12000。
8. 在 /contents 上把 text、highlights、summary 作为顶层请求字段发送。
9. urls 参数必填，类型为 string[]，用于传入要提取内容的已知 URL。
10. text 参数可不传、传 boolean 或传 object；object 形式支持 maxCharacters、includeHtmlTags、verbosity、includeSections、excludeSections。
11. highlights 参数可不传、传 boolean 或传 object；在 agent workflows 中优先传 true，除非需要自定义 focus。
12. summary 参数可不传、传 boolean 或传 object；当调用方需要 Exa 侧压缩或结构化提取时使用。
13. 用 maxAgeHours 控制 freshness：省略时使用默认 cache-first 行为，必要时 crawl fallback。
14. maxAgeHours 传正整数时，缓存小于 N 小时则使用缓存，否则 live crawl。
15. maxAgeHours 传 0 时总是 live crawl，freshness 最高但 latency 更高。
16. maxAgeHours 传 -1 时仅使用 cache，最快，但没有 cached content 时失败。
17. 在 live crawling 不应超过固定预算时设置 livecrawlTimeout；默认值为 10000 毫秒，大多数 freshness 敏感调用用 10000 到 15000。
18. 需要爬取每个 URL 的链接子页时设置 subpages，默认值为 0。
19. 与 subpages 一起用 subpageTarget，传字符串或字符串数组，以优先选择重要子页，例如 api、reference、pricing。
20. 用 extras.links 设置每页提取的链接数量，默认值为 0。
21. 用 extras.imageLinks 设置每页提取的图片 URL 数量，默认值为 0。
22. 企业账户启用时可用 compliance 传合规模式，例如 hipaa。
23. Text object 中用 maxCharacters 限制返回文本字符数，替代 tokensNum。
24. Text object 中用 includeHtmlTags 控制是否保留 HTML tags，默认 false。
25. Text object 中用 verbosity 设置 compact、standard 或 full，默认 compact；与 maxAgeHours: 0 搭配用于 fresh section-aware extraction。
26. Text object 中用 includeSections 只包含 header、navigation、banner、body、sidebar、footer、metadata 中的选定 sections。
27. Text object 中用 excludeSections 从同一 section 列表中排除选定 sections。
28. Highlights object 中用 query 指导返回哪些 excerpts。
29. Highlights object 中用 maxCharacters 限制每个 URL 的 highlight 字符数；除非调用方有严格预算，否则省略。
30. Summary object 中用 query 自定义摘要查询。
31. Summary object 中用 schema 传 JSON Schema，获取结构化 per-page summaries。
32. text 模式适合深度分析和广泛页面上下文；用 maxCharacters 保持 payload bounded。
33. highlights 模式适合 agent workflows 和 factual lookups；它最 token-efficient，且 excerpts grounded in source page。
34. summary 模式适合压缩或结构化 per-page extraction；它增加 Exa 侧 synthesis per page。
35. 默认避免请求多个模式，除非调用方确实需要同一页面的多个视图。
36. 当 linked pages 重要时，用 subpages 和 subpageTarget；从 subpages 约 5 到 10 开始，只有调用方需要更广 site coverage 时才增加。
37. 子页与 extras 示例：urls 传 https://docs.example.com，text 对象中 maxCharacters 传 5000，subpages 传 10，subpageTarget 传 api、reference、guide，extras 中 links 传 10、imageLinks 传 5。
38. 即使 HTTP 状态为 200 也检查 statuses；同一请求中可能一个 URL 成功而另一个 URL 失败。
39. 用 curl ... | jq '{results, statuses}' 检查响应中的 results 和 statuses。
40. 读取响应字段：requestId、results、results[].title、results[].url、results[].publishedDate、results[].author、results[].text、results[].highlights、results[].highlightScores、results[].summary、results[].subpages、results[].extras.links、statuses、statuses[].id、statuses[].status、statuses[].error.tag、statuses[].error.httpStatusCode、costDollars.total。
41. 处理常见 per-URL error tags：CRAWL_NOT_FOUND、CRAWL_TIMEOUT、CRAWL_LIVECRAWL_TIMEOUT、SOURCE_NOT_AVAILABLE、UNSUPPORTED_URL、CRAWL_UNKNOWN_ERROR。
42. 在 /contents 上保持 text、highlights、summary 在顶层。
43. 不要把 extraction options 包在 contents 对象中；该 nesting 属于 /search。
44. 不要假设 HTTP 200 代表每个 URL 成功；检查 statuses。
45. 不要发送 stream: true；/contents 不是 streaming endpoint。
46. 不要发送 tokensNum；用 text.maxCharacters 限制 extracted text。
47. 不要在新请求中使用 useAutoprompt、numSentences、highlightsPerUrl 或旧 livecrawl 字符串值。
48. 优先用 maxAgeHours 控制 freshness，并在 crawl latency 重要时搭配 livecrawlTimeout。
49. 将 subpageTarget 与 subpages 一起用；否则子页选择是 best effort。
50. 默认选择 highlights、text、summary 之一；只有调用方确实需要每页多个视图时才叠模式。

适用边界 · 注意事项

• 没有 Exa API key/账号或不能调用第三方 Exa API 时不适用。
• 需要先做 URL 发现或排序时不适用；应改用 POST /search。
• 需要流式响应时不适用；/contents 不是 streaming endpoint。