exa-contents

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Exa Contents

Requires API key: Get one at https://dashboard.exa.ai/api-keys
Header:
x-api-key: $EXA_API_KEY

Use

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

when the agent already knows the URLs and needs clean, LLM-ready extraction without running a new search. Start with one content mode:

highlights

for compact agent context,

text

for broad page context, or

summary

for Exa-side compression.

需要API密钥：前往https://dashboard.exa.ai/api-keys获取
请求头：
x-api-key: $EXA_API_KEY

当Agent已知目标URL，且无需执行新搜索即可获取适合LLM处理的干净提取内容时，可调用

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

接口。初始可选择一种内容模式：

highlights

（用于紧凑的Agent上下文）、

text

（用于全面的页面上下文）或

summary

（由Exa端进行内容压缩）。

Quick Start (cURL)

快速开始（cURL）

Basic text extraction

基础文本提取

bash

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
  }'

bash

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
  }'

Highlights with freshness control

带时效性控制的高亮内容提取

bash

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
  }'

bash

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
  }'

Endpoint

接口地址

text

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

Authentication:

x-api-key: <API_KEY>

header. Exa also accepts

Authorization: Bearer <API_KEY>

, but prefer

x-api-key

in cURL examples for consistency.

Use this endpoint for known-URL extraction. If the agent needs discovery or ranking first, use

POST /search

text

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

认证方式：使用

x-api-key: <API_KEY>

请求头。Exa也支持

Authorization: Bearer <API_KEY>

，但为保持一致性，cURL示例中优先使用

x-api-key

。

此接口适用于已知URL的内容提取。若Agent需要先进行内容发现或排序，请使用

POST /search

接口。

Parameters

参数

Core request parameters

核心请求参数

Parameter	Type	Required	Default	Description
`urls`	string[]	Yes	-	URLs to extract content from. Use this for known URLs.
`text`	boolean or object	No	-	Return full page text as markdown. Object form supports `maxCharacters` , `includeHtmlTags` , `verbosity` , `includeSections` , and `excludeSections` .
`highlights`	boolean or object	No	-	Return key excerpts. Prefer `true` for agent workflows unless a custom focus is needed.
`summary`	boolean or object	No	-	Return per-page LLM summaries. Use when the caller wants Exa-side compression or structured extraction.
`maxAgeHours`	integer	No	-	Freshness control. `0` always live crawls; `-1` uses cache only; omit for default cache-first behavior with crawl fallback.
`livecrawlTimeout`	integer	No	`10000`	Timeout for live crawling in milliseconds. Use `10000` to `15000` for most freshness-sensitive calls.
`subpages`	integer	No	`0`	Number of linked subpages to crawl from each URL.
`subpageTarget`	string or string[]	No	-	Terms used to prioritize which subpages matter, such as `["api", "reference", "pricing"]` .
`extras.links`	integer	No	`0`	Number of links to extract from each page.
`extras.imageLinks`	integer	No	`0`	Number of image URLs to extract from each page.
`compliance`	string	No	-	Enterprise-only compliance mode, such as `hipaa` , when enabled for the account.

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

Text object options

Text对象选项

Parameter	Type	Default	Description
`maxCharacters`	integer	-	Character limit for returned text. Use this instead of `tokensNum` .
`includeHtmlTags`	boolean	`false`	Preserve HTML tags in output.
`verbosity`	string	`compact`	`compact` , `standard` , or `full` . Pair fresh section-aware extraction with `maxAgeHours: 0` .
`includeSections`	string[]	-	Only include selected sections: `header` , `navigation` , `banner` , `body` , `sidebar` , `footer` , `metadata` .
`excludeSections`	string[]	-	Exclude selected sections from the same section list.

参数	类型	默认值	描述
`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 object options

Highlights对象选项

Prefer

highlights: true

for the highest-quality default. Only use object form when the agent needs a custom focus or budget.

Parameter	Type	Default	Description
`query`	string	-	Custom query guiding which excerpts are returned.
`maxCharacters`	integer	-	Cap highlight characters per URL. Omit unless the caller has a strict budget.

优先使用

highlights: true

以获取最优默认效果。仅当Agent需要自定义聚焦方向或控制成本时，才使用对象形式。

参数	类型	默认值	描述
`query`	string	-	指导摘录内容返回的自定义查询语句。
`maxCharacters`	integer	-	限制每个URL返回的高亮内容字符数。仅当调用方有严格成本控制需求时使用。

Summary object options

Summary对象选项

Parameter	Type	Default	Description
`query`	string	-	Custom query for the summary.
`schema`	object	-	JSON Schema for structured per-page summaries.

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

Content Modes

内容模式

/contents

text

highlights

, and

summary

are top-level request fields.

Mode	Best for	Notes
`text`	Deep analysis and broad page context	Use `maxCharacters` to keep payloads bounded.
`highlights`	Agent workflows and factual lookups	Most token-efficient default. Excerpts are grounded in the source page.
`summary`	Compression or structured per-page extraction	Adds Exa-side synthesis per page.

Avoid requesting multiple modes unless the caller truly needs multiple views of the same page.

在

/contents

接口中，

text

、

highlights

和

summary

为顶层请求字段。

模式	适用场景	注意事项
`text`	深度分析与全面页面上下文	使用 `maxCharacters` 限制返回内容大小。
`highlights`	Agent工作流与事实查询	最节省Token的默认模式。摘录内容均源自原页面。
`summary`	内容压缩或结构化单页面提取	由Exa端对每个页面进行内容合成。

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

Freshness and Crawling

时效性与爬取

Use

maxAgeHours

as the normative freshness control.

Value	Behavior
omitted	Use default cache-first behavior with crawl fallback when needed.
positive integer	Use cache if it is less than N hours old, otherwise live crawl.
`0`	Always live crawl. Highest freshness, higher latency.
`-1`	Cache only. Fastest, but fails if no cached content exists.

Set

livecrawlTimeout

when live crawling should not block past a fixed budget.

使用

maxAgeHours

作为标准时效性控制参数。

值	行为
省略	使用默认的"优先缓存，缓存失效时回退到爬取"策略。
正整数	若缓存内容的生成时间小于N小时则使用缓存，否则实时爬取。
`0`	始终实时爬取。时效性最高，但延迟也更高。
`-1`	仅使用缓存内容。速度最快，但如果没有缓存内容则请求失败。

当实时爬取不能超过固定时间限制时，请设置

livecrawlTimeout

参数。

Subpages and extras

子页面与额外内容

Use

subpages

and

subpageTarget

when linked pages matter.

bash

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
    }
  }'

Start with

subpages

around

, then increase only when the caller needs broader site coverage.

当关联页面重要时，可使用

subpages

和

subpageTarget

参数。

bash

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

设置为

至

，仅当调用方需要更广泛的站点覆盖时再增加数值。

Response Fields and Statuses

响应字段与状态

Inspect

statuses

even when the HTTP status is 200. The endpoint can succeed for one URL and fail for another in the same request.

bash

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}'

Field	Type	Description
`requestId`	string	Unique request identifier.
`results`	array	Extracted content result objects.
`results[].title`	string	Page title.
`results[].url`	string	Page URL.
`results[].publishedDate`	string or null	Estimated publication date when available.
`results[].author`	string or null	Author when available.
`results[].text`	string	Returned when `text` is requested.
`results[].highlights`	string[]	Returned when `highlights` is requested.
`results[].highlightScores`	number[]	Similarity scores for highlights.
`results[].summary`	string	Returned when `summary` is requested.
`results[].subpages`	array	Nested result objects from subpage crawling.
`results[].extras.links`	string[]	Extracted links when requested.
`statuses`	array	Per-URL success or error states. Always inspect this field.
`statuses[].id`	string	Requested URL.
`statuses[].status`	string	`success` or `error` .
`statuses[].error.tag`	string	Error type for failed URLs.
`statuses[].error.httpStatusCode`	integer or null	HTTP code associated with a per-URL failure.
`costDollars.total`	number	Total request cost when returned.

Common per-URL error tags include

CRAWL_NOT_FOUND

CRAWL_TIMEOUT

CRAWL_LIVECRAWL_TIMEOUT

SOURCE_NOT_AVAILABLE

UNSUPPORTED_URL

, and

CRAWL_UNKNOWN_ERROR

即使HTTP状态码为200，也需检查

statuses

字段。同一请求中，可能部分URL处理成功，部分失败。

bash

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

。

Critical Pitfalls

关键注意事项

Keep
```
text
```
,
```
highlights
```
, and
```
summary
```
at the top level on
```
/contents
```
.
Do not wrap extraction options in a
```
contents
```
object; that nesting belongs to
```
/search
```
.
Do not assume HTTP 200 means every URL succeeded; inspect
```
statuses
```
.
Do not send
```
stream: true
```
;
```
/contents
```
is not a streaming endpoint.
Do not send
```
tokensNum
```
; use
```
text.maxCharacters
```
to cap extracted text.
Do not use
```
useAutoprompt
```
,
```
numSentences
```
,
```
highlightsPerUrl
```
, or older
```
livecrawl
```
string values in new requests.
Prefer
```
maxAgeHours
```
for freshness and pair it with
```
livecrawlTimeout
```
when crawl latency matters.
Use
```
subpageTarget
```
with
```
subpages
```
; otherwise subpage selection is best effort.
Pick one of
```
highlights
```
,
```
text
```
, or
```
summary
```
by default. Stack modes only when the caller truly needs multiple views of each page.

在
```
/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
```
中的一种模式。仅当调用方确实需要每个页面的多种视图时，才同时使用多种模式。