exa-search

Exa 搜索

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

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

使用 POST https://api.exa.ai/search，通过一次原始 HTTP 调用实现语义网页检索、结果排序和可选的结果级提取。常规检索请从 type: "auto" 开始。仅当调用方需要网页文本、重点内容、摘要、可控制新鲜度的抓取、子页面或提取的链接时，才添加 contents。

快速开始（cURL）

基本搜索

curl -sS -X POST "https://api.exa.ai/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "query": "latest developments in LLMs",
    "type": "auto",
    "numResults": 10
  }'

搜索并获取重点内容

curl -sS -X POST "https://api.exa.ai/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "query": "latest developments in LLMs",
    "type": "auto",
    "numResults": 5,
    "contents": {
      "highlights": true
    }
  }'

使用筛选条件和新鲜度控制

curl -sS -X POST "https://api.exa.ai/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "query": "AI regulation policy updates",
    "type": "auto",
    "category": "news",
    "numResults": 10,
    "includeDomains": ["reuters.com", "bbc.com"],
    "startPublishedDate": "2025-01-01",
    "contents": {
      "text": {
        "maxCharacters": 2000
      },
      "maxAgeHours": 24,
      "livecrawlTimeout": 12000
    }
  }'

深度搜索

curl -sS -X POST "https://api.exa.ai/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "query": "map the major technical and commercial tradeoffs in sodium-ion batteries for grid storage",
    "type": "deep",
    "numResults": 8
  }'

端点

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

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

当 Agent 需要搜索结果时，请使用此端点。如果 Agent 已有 URL，只需要提取内容，则改用 POST /contents。

参数

核心请求参数

参数	类型	必填	默认值	说明
query	字符串	是	-	自然语言搜索查询。内容较长、语义丰富的描述效果良好。
type	字符串	否	auto	搜索方式：auto、fast、instant、deep-lite、deep 或 deep-reasoning。
numResults	整数	否	10	返回的结果数量。Agent 循环中请使用较小的值；最多为 100。
category	字符串	否	-	专用结果类型：company、people、research paper、news、personal site 或 financial report。
includeDomains	字符串数组	否	-	仅返回来自这些域名、路径或通配符模式的结果。最多 1200 个。
excludeDomains	字符串数组	否	-	排除这些域名、路径或通配符模式。最多 1200 个。
startPublishedDate	字符串	否	-	结果发布日期的 ISO 8601 下限。
endPublishedDate	字符串	否	-	结果发布日期的 ISO 8601 上限。
userLocation	字符串	否	-	两位字母的 ISO 国家代码，例如 US 或 GB。
moderation	布尔值	否	false	从结果中过滤不安全内容。
additionalQueries	字符串数组	否	-	为深度搜索变体提供额外的查询。请与主 query 一起使用。
systemPrompt	字符串	否	-	为合成输出和深度搜索规划提供指令，例如对来源的偏好。
outputSchema	对象	否	-	用于控制 output.content 的 JSON Schema。会添加合成输出和依据来源的内容。
stream	布尔值	否	false	如果为 true，则返回 SSE，而不是单个 JSON 响应。
compliance	字符串	否	-	仅限企业版的合规模式，例如在账户中启用时使用的 hipaa。

嵌套在 contents 下的内容参数

在 /search 中，text、highlights 和 summary 必须嵌套在 contents 下。

参数	类型	必填	默认值	描述
contents.text	布尔值或对象	否	-	以 Markdown 格式返回完整的页面文本。对象形式支持 maxCharacters、includeHtmlTags、verbosity、includeSections 和 excludeSections。
contents.highlights	布尔值或对象	否	-	返回与查询相关的摘录。除非需要固定字符数上限，否则建议在 Agent 工作流中使用 true。
contents.summary	布尔值或对象	否	-	返回每条结果的大模型摘要。请谨慎使用，因为每条结果都会增加综合处理工作量。
contents.maxAgeHours	整数	否	-	新鲜度控制。0 表示始终实时抓取；-1 表示仅使用缓存；省略时采用默认的优先使用缓存、抓取作为后备的行为。
contents.livecrawlTimeout	整数	否	10000	实时抓取超时时间，单位为毫秒。对大多数对新鲜度敏感的调用，使用 10000 到 15000。
contents.subpages	整数	否	0	每条结果要抓取的链接子页面数量。
contents.subpageTarget	字符串或字符串数组	否	-	用于优先筛选相关子页面的词语，例如 ["api", "pricing"]。
contents.extras.links	整数	否	0	从每个结果页面提取的链接数量。
contents.extras.imageLinks	整数	否	0	从每个结果页面提取的图片 URL 数量。

文本对象选项

参数	类型	默认值	描述
maxCharacters	整数	-	返回文本的字符数上限。使用此选项代替 tokensNum。
includeHtmlTags	布尔值	false	在输出中保留 HTML 标签。
verbosity	字符串	compact	可选值为 compact、standard 或 full。将新鲜的、感知章节的提取与 contents.maxAgeHours: 0 配合使用。
includeSections	字符串数组	-	仅包含所选章节：header、navigation、banner、body、sidebar、footer、metadata。
excludeSections	字符串数组	-	从同一章节列表中排除所选章节。

Highlights 对象选项

若要获得最高质量的默认结果，建议使用 contents.highlights: true。只有当 Agent 需要自定义关注点或字符数上限时，才使用对象形式。

参数	类型	默认值	描述
query	字符串	-	用于指导返回哪些摘录的自定义查询。
maxCharacters	整数	-	限制每个 URL 的高亮内容字符数。除非调用方有严格的字符数上限，否则省略此参数。

Summary 对象选项

参数	类型	默认值	描述
query	字符串	-	摘要的自定义查询。
schema	对象	-	用于结构化单条结果摘要的 JSON Schema。

搜索类型

搜索 type 用于控制检索和综合模式。请根据工作流选择模式，而不仅仅是输出格式。任何搜索类型都可以使用 outputSchema；如果搜索过程本身需要更多规划、综合或推理，请使用更深入的模式。

类型	最适合	权衡
auto	通用默认搜索和大多数新集成	无需调用方调整检索策略，即可平衡速度和质量。
fast	低延迟 Agent 循环和产品流程	比 auto 更快；当响应速度比最大推理深度更重要时使用。
instant	实时 UI、聊天、语音和自动补全类流程	延迟最低的模式；适用于快速检索，而非深度综合。
deep-lite	轻量级研究或综合	比 auto 增加更多规划和综合，同时比完整的 deep 更轻量。
deep	多步骤研究、比较和以综合为主的检索	延迟较高；适用于需要跨多个来源进行探索的查询。
deep-reasoning	歧义较大或权衡复杂的高难度研究任务	延迟和推理深度最高。

除非延迟或推理深度是首要限制，否则请使用 auto。对于有时效要求的调用，请使用 fast 或 instant。当查询需要多步骤的来源发现、比较或综合时，请使用 deep、deep-lite 或 deep-reasoning。

仅模式示例

{
  "query": "recent product launches from major AI chip companies",
  "type": "fast",
  "numResults": 5
}

{
  "query": "compare competing explanations for the recent rise in grid-scale battery deployments",
  "type": "deep",
  "numResults": 8
}

结构化输出

使用 systemPrompt 控制行为，使用 outputSchema 定义结构。请保持架构简洁：只包含少量命名字段、浅层嵌套，以及声明了 items 的数组。下面的示例大致符合 /search 所需的宽度。如果需要更多列，请删除最不重要的列，而不是扩展架构。

curl -sS -X POST "https://api.exa.ai/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "query": "compare the latest frontier AI model releases",
    "type": "deep",
    "systemPrompt": "Prefer official sources and avoid duplicate results.",
    "outputSchema": {
      "type": "object",
      "properties": {
        "models": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "notable_claims": {
                "type": "array",
                "items": { "type": "string" }
              }
            },
            "required": ["name", "notable_claims"]
          }
        }
      },
      "required": ["models"]
    },
    "contents": {
      "highlights": true
    }
  }'

请保持架构简洁且范围有限。不要在架构中添加引用字段；依据来源的信息会单独返回在 output.grounding 中。

流式传输

流式传输适用于综合后的输出，因此请同时包含 outputSchema、-N、Accept: text/event-stream 和 stream: true。如果没有 outputSchema，即使 stream 为 true，端点也会返回常规 JSON 搜索响应。

curl -sS -N -X POST "https://api.exa.ai/search" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "query": "recent grid-scale battery deployments",
    "type": "deep",
    "stream": true,
    "outputSchema": {
      "type": "object",
      "properties": {
        "summary": { "type": "string" }
      },
      "required": ["summary"]
    },
    "contents": {
      "highlights": true
    }
  }'

请将流式传输视为 SSE，而不是 JSON。每个 data: 帧都包含一个兼容 OpenAI 的聊天补全数据块；请从 choices[0].delta.content 读取部分文本，并稳妥地处理完成或错误帧。

响应字段

字段	类型	描述
requestId	string	唯一的请求标识符。
results	array	已排序的结果对象。
results[].title	string	页面标题。
results[].url	string	页面 URL。
results[].publishedDate	string or null	可用时返回的估计发布日期。
results[].author	string or null	可用时返回的作者。
results[].text	string	请求 contents.text 时返回。
results[].highlights	string[]	请求 contents.highlights 时返回。
results[].highlightScores	number[]	高亮内容的相似度分数。
results[].summary	string	请求 contents.summary 时返回。
results[].subpages	array	从子页面抓取中获得的嵌套结果对象。
results[].extras.links	string[]	请求时返回的提取链接。
output.content	string or object	提供 outputSchema 时的综合输出。
output.grounding	array	综合字段的引用和置信度标签。
costDollars.total	number	返回时表示请求的总成本。
searchTime	number	返回时表示搜索延迟。

关键注意事项

• 在 /search 的 contents 中保留 text、highlights 和 summary。
• 不要发送顶层的 text、highlights 或 summary；这种结构属于 /contents。
• 不要发送 tokensNum；使用 contents.text.maxCharacters 限制提取文本的长度。
• 新请求中不要使用 useAutoprompt、numSentences 或 highlightsPerUrl。
• 使用 contents.maxAgeHours 替代 livecrawl。
• 仅使用文档中列出的类别：company、people、research paper、news、personal site 和 financial report。
• 避免无效的类别和筛选条件组合。company 和 people 不支持 startPublishedDate 或 endPublishedDate。company 支持 excludeDomains；people 不支持，并且 people 的 includeDomains 仅接受 LinkedIn 域名。
• 默认选择 contents.highlights、contents.text 或 contents.summary 之一。只有调用方确实需要查看每个页面的多个视图时，才叠加使用多种模式。
• 只有在 stream: true 与 outputSchema 搭配使用时，才会返回 SSE；否则 /search 会返回常规 JSON 响应。