octen-extract

Octen Extract

将一个或多个 URL 转换为整洁、适合大模型使用的内容。除页面正文外，每个结果还包含一个类别、一个页面结构标签，以及——传入 query 时——与查询相关的重点内容，而非完整页面。

需要 API Key：前往 https://octen.ai 获取 · 设置方式：export OCTEN_API_KEY=your-api-key

API Key 设置

提取内容前，请确保已设置 OCTEN_API_KEY。遇到 401 时，请停止操作并告知用户需要密钥（https://octen.ai），协助其完成配置后再继续。 为相关 Agent 配置密钥（与其他 Octen 技能相同）：

• Claude Code — 将 { "env": { "OCTEN_API_KEY": "your-key" } } 添加到 ~/.claude/settings.json
• Cursor / 通用 shell — 在 ~/.zshrc 或 ~/.bashrc 中执行 export OCTEN_API_KEY="your-key"
• Codex — 在 ~/.codex/config.toml 的 [shell_environment_policy] 中设置 set = { OCTEN_API_KEY = "your-key" }
• OpenClaw — 将 OCTEN_API_KEY=your-key 添加到 ~/.openclaw/.env

端点

POST https://api.octen.ai/extract

身份验证：X-Api-Key: <API_KEY> 请求头 · Content-Type：application/json

快速开始（cURL）

批量提取（完整内容）

curl -s -X POST "https://api.octen.ai/extract" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{
    "urls": ["https://example.com", "https://octen.ai"],
    "format": "markdown"
  }'

基于查询的重点内容（而非完整内容）

curl -s -X POST "https://api.octen.ai/extract" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{
    "urls": ["https://en.wikipedia.org/wiki/Python_(programming_language)"],
    "query": "async programming"
  }'

难处理的网站（高级模式）

curl -s -X POST "https://api.octen.ai/extract" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{
    "urls": ["https://www.reddit.com/r/LocalLLaMA/"],
    "mode": "advanced",
    "timeout": 60
  }'

混合批次，难度未知（自动模式）

curl -s -X POST "https://api.octen.ai/extract" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{
    "urls": ["https://example.com", "https://octen.ai", "https://news.ycombinator.com/item?id=1"],
    "mode": "auto",
    "timeout": 60
  }'

页面链接（优先列出外部引用）

curl -s -X POST "https://api.octen.ai/extract" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{
    "urls": ["https://octen.ai"],
    "include_links": {"scope": "prefer_external", "max_links": 50}
  }'

参数

参数	类型	必填	默认值	说明
urls	string[]	是	-	一次批量获取 1–20 个 URL
mode	string	否	standard（省略时）	standard、advanced 或 auto — 参见选择模式
query	string	否	-	设置后，每个结果会返回与查询相关的 highlights，并省略 full_content（最多 500 个字符）
max_age_seconds	integer	否	86400	接受此时间范围内的缓存结果（最短 300）；更早的缓存版本会重新获取
format	string	否	markdown	内容格式：markdown 或 text
timeout	integer	否	30	每个 URL 的获取时限，单位为秒（1–60）
include_images	boolean	否	false	包含页面中找到的图像资源（如果页面有封面图，也会返回 cover_image）
include_videos	boolean	否	false	包含页面中找到的视频 URL
include_audio	boolean	否	false	包含页面中找到的音频 URL
include_links	object	否	-	用于发现网站页面或跟进外部引用。返回页面的链接：{scope, max_links}。scope：prefer_internal（默认；优先同一网站的链接）或 prefer_external（优先其他已注册域名）；各组内保持页面原有顺序。max_links：1–1000（默认 200；超出范围会返回 400，不会截断）。{} 使用这两个默认值

选择模式

由你选择模式；省略时默认为 standard。

• standard（默认）：速度最快、成本最低。适用于没有反爬保护的普通、结构良好的页面，如新闻、博客、文档、产品页面和静态网站。对于有登录墙、严重依赖 JS 或有反爬保护的网站，它可能返回空内容或仅返回页面骨架，但仍会报告 status: "success"。
• advanced：成功率最高——在真实浏览器中渲染，并采用更强的反爬处理；速度较慢，价格是 2.5 倍。适用于已知的难抓取网站：有反爬/WAF 保护的网站、严重依赖 JS 的 SPA、社交网站（Reddit、X、LinkedIn）、学术网站（ResearchGate）以及动态加载内容的网站。
• auto：针对每个 URL 自行选择——能用 standard 满足需求时使用 standard，仅对难抓取的 URL 使用 advanced；每个 URL 按实际使用的模式计费。当一批 URL 中难抓取的 URL 不易判断时使用。如果大多数 URL 都很难抓取，成本会接近全部使用 advanced。

场景	mode
新闻／博客／文档／产品页面（普通网站）	standard（或省略）
已知的难抓取网站（Reddit／X／LinkedIn／ResearchGate／反爬网站／SPA）	advanced
混合批次，不确定哪些网站难抓取	auto
对成本敏感，以普通网站为主	standard
优先考虑质量，以难抓取网站为主	advanced

经验法则：全是普通网站 → standard（或省略）；已知的难抓取网站 → advanced；混合情况或不确定 → auto。

恢复处理：如果 standard 结果失败，或返回空内容／页面骨架（page_structure.primary 为 "No Main Content"，或本应有正文的页面仅返回非常短的内容），则仅对这些 URL 使用 "mode": "advanced" 重试。

超时：advanced 和 auto 速度较慢——请调高 timeout（例如 60）。

响应格式

字段	类型	说明
request_id	string	唯一请求标识符
data.results[]	array	每个 URL 对应一个结果
data.results[].url	string	URL
data.results[].status	string	success 或 failed
data.results[].resolved_mode	string?	standard 或 advanced——此 URL 实际使用的模式。成功时存在，失败时缺省。可能与请求的模式不同（auto 会针对每个 URL 选择模式；advanced 可能最终使用 standard）
data.results[].error_message	string?	失败原因（当 status = failed 时）
data.results[].title	string?	页面标题
data.results[].full_content	string?	清理后的页面内容（未设置 query 时）
data.results[].highlights	string[]?	与查询相关的片段（设置 query 时）
data.results[].category	object?	{primary, secondary}——页面主题
data.results[].page_structure	object?	{primary, secondary}——页面类型
data.results[].time_published	string?	发布时间，ISO 8601 格式
data.results[].time_last_crawled	string?	上次抓取时间，ISO 8601 格式
data.results[].favicon	string?	页面 favicon URL——有可用值时默认返回
data.results[].cover_image	object?	{url}——页面封面图片（include_images 为 true 且页面有封面图片时）
data.results[].images / videos / audio	object[]?	[{url}]——页面中的媒体（对应的 include_* 为 true 时）
data.results[].links	object[]?	[{url, anchor_text, is_external}]——页面链接（成功时，设置 include_links 且找到链接时）
meta.usage.total_urls	integer	请求的 URL 数量
meta.usage.successful_urls	integer	成功获取的 URL 数量
meta.usage.successful_by_mode	object	{standard_urls, advanced_urls}——各模式下成功获取的 URL 数量。实际计费以这些计数为准，而非汇总 resolved_mode
meta.warning	string	例如 "1 URL(s) failed and were not billed"；无内容需要报告时为空字符串

meta 位于顶层（与 data 同级），而非 data.meta。

错误代码

HTTP 状态	描述
400	参数缺失或无效
401	API 密钥无效或缺失
403	余额不足
429	请求过多，已触发速率限制
500	服务器内部错误

注意事项

• 部分成功是首要设计原则：失败的 URL 会以 status: "failed" 和 error_message 返回；同一批次中的其他 URL 仍会成功。请务必检查每个结果的 status。
• 仅在需要用于 RAG/grounding 的聚焦 highlights 时传入 query；省略它即可获取完整的清理后页面。
• 定价：standard 为每 1K 个成功 URL 收费 $1，advanced 为每 1K 个成功 URL 收费 $2.5。失败的 URL 不收费。
• category 和 page_structure 可用于路由或筛选页面（例如，跳过索引/操作页面，保留内容页面），无需读取整个正文。