Olostep 文档 - 抓取端点

通过 Olostep 的 /v1/scrapes 端点，你可以实时从任何 URL 提取适合 LLM 的 Markdown、HTML、文本、截图或结构化 JSON。

输出干净的 markdown、结构化数据、截图或 html
通过 Parsers 或 LLM 提取提取 JSON
处理动态内容：js 渲染的网站、通过动作的登录流程、PDF

有关 API 详细信息，请参阅抓取端点 API 参考。

抓取 URL

使用 /v1/scrapes 端点抓取单个 URL 并选择输出格式。

安装

pip install olostep

使用方法

你可以使用该端点抓取单个 URL 并选择输出格式。必需的参数是 url_to_scrape 和 formats。其他一些常用参数包括 wait_before_scraping（以毫秒为单位）、remove_css_selectors（默认、无或选择器数组）和 country。

from olostep import Olostep

client = Olostep(api_key="YOUR_REAL_KEY")

result = client.scrapes.create(
    url_to_scrape="https://en.wikipedia.org/wiki/Alexander_the_Great",
    formats=["markdown", "html"],
)

print(result.markdown_content)
print(result.html_content)

响应

API 返回一个 scrape 对象作为响应。 scrape 有一些属性，如 id 和 result。 result 对象具有以下字段（根据 formats 参数，有些可能为 null）：

html_content: 页面的 HTML 内容。传递 formats: ["html"] 来获取此内容。
markdown_content: 页面的 MD 内容。传递 formats: ["markdown"] 来获取此内容。
text_content: 页面的文本内容。传递 formats: ["text"] 来获取此内容。
json_content: 页面的 JSON 内容。传递 formats: ["json"] 来获取此内容，并提供 parser 或 llm_extract 参数。
screenshot_hosted_url: 截图的托管 URL。
html_hosted_url: HTML 内容的托管 URL。
markdown_hosted_url: Markdown 内容的托管 URL。
json_hosted_url: JSON 内容的托管 URL。
text_hosted_url: 文本内容的托管 URL。
links_on_page: 页面上的链接。
page_metadata: 页面的元数据。

{
  "id": "scrape_6h89o8u1kt",
  "object": "scrape",
  "created": 1745673871,
  "metadata": {},
  "retrieve_id": "6h89o8u1kt",
  "url_to_scrape": "https://en.wikipedia.org/wiki/Alexander_the_Great",
  "result": {
    "html_content": "<html...",
    "markdown_content": "## Alexander the Great...",
    "text_content": null,
    "json_content": null,
    "screenshot_hosted_url": null,
    "html_hosted_url": "https://olostep-storage.s3.us-east-1.amazonaws.com/text_6h89o8u1kt.txt",
    "markdown_hosted_url": "https://olostep-storage.s3.us-east-1.amazonaws.com/markDown_6h89o8u1kt.txt",
    "json_hosted_url": null,
    "text_hosted_url": null,
    "links_on_page": [],
    "page_metadata": { "status_code": 200, "title": "" }
  }
}

缓存

为了优化速度，Olostep 提供了一个可选的共享缓存层，用于 HTML、Markdown、文本和解析的 JSON 结果。

工作原理

当请求抓取时，Olostep 会检查是否存在具有相同参数的匹配抓取。如果找到足够新的匹配项，内容将立即从 Olostep 的存储中提供，而无需启动新的浏览器抓取。

共享缓存： 缓存是全球共享的。如果另一个请求在你的新鲜度窗口内抓取了完全相同的 URL 和配置，你将受益于加速。
后处理仍然是实时的： 操作如 llm_extract 和 links_on_page 过滤器在缓存文档上即时运行。你只缓存核心页面检索，保持你的结构化提取动态。

新鲜度和 `max_age`

默认情况下，生产 API 始终执行实时抓取以保证实时准确性。你可以使用 max_age 参数选择加入缓存。

参数	类型	默认值	描述
`max_age`	`integer`	`0`	可接受的内容年龄，以秒为单位。如果存在缓存副本且比 `max_age` 秒更新，则从缓存中提供。

默认 API 行为 (max_age: 0)： 每个 API 请求都会触发新的抓取。
默认 Playground 行为： 在仪表板 playground 中，max_age 默认为 24 小时（86400 秒），以防止重复抓取并在构建和测试时节省积分。
最大年龄： 缓存的硬限制为 7 天（604800 秒）。任何请求超过此限制的 max_age 都将回退到最多 7 天。

使用示例

from olostep import Olostep

client = Olostep(api_key="YOUR_REAL_KEY")

# 选择加入缓存：接受最多 1 天（86400 秒）前的结果
result = client.scrapes.create(
    url_to_scrape="https://example.com",
    formats=["markdown"],
    max_age=86400
)

何时跳过缓存？

对于需要唯一会话、实时视觉输出或自定义文件处理的功能，缓存会自动绕过（强制进行实时抓取）：

交互式会话： 使用 session_id 的请求或加载自定义浏览器 context。
视觉效果： 可视化工具和截图（htmlVisualizer）。
特殊文件类型： 二进制文件下载或原始 PDF 渲染。
调试和网络： 捕获 network_calls 或使用异步解析器作业。

提取链接

在请求中传递一个 links_on_page 对象以收集页面上找到的链接。所有链接都以绝对 URL 返回。

"links_on_page": {
  "include_links": ["/blog/*"],
  "exclude_links": ["*.pdf"],
  "query_to_order_links_by": "pricing"
}

include_links / exclude_links: 匹配每个链接 URL 路径的 glob 模式。
query_to_order_links_by: 按与此文本的相关性重新排序返回的链接。

Glob 模式匹配路径段。单个 * 不会跨越 /，因此 "/blog/*" 匹配 "/blog/post-1" 但不匹配索引 "/blog" 本身——并且永远不会匹配 "/blog?tag=x"，因为查询字符串不属于路径的一部分。要包括索引，请使用 "/blog*" 或 "{/blog,/blog/**}"。

抓取格式

通过 formats 选择一个或多个输出格式：

markdown: 适合 LLM 的 markdown
html: 清理过的 HTML
text: 纯文本
json: 结构化输出（通过解析器或 llm_extract）
raw_pdf: 提取到托管 URL 的原始 PDF 字节
screenshot: 通过动作设置以捕获截图并返回托管 URL

输出键作为 result 中的 *_content 字段和 *_hosted_url 返回。

提取结构化数据

你可以通过两种方式提取结构化 JSON：使用 Parsers 或 LLM 提取。

使用解析器（推荐用于规模）

定义 formats: ["json"] 并提供解析器 id。

from olostep import Olostep

client = Olostep(api_key="YOUR_REAL_KEY")

result = client.scrapes.create(
    url_to_scrape="https://www.google.com/search?q=alexander+the+great&gl=us&hl=en",
    formats=["json"],
    parser="@olostep/google-search",
)

print(result.json_content)

Olostep 有一些为热门网站预构建的解析器，但你也可以通过仪表板创建自己的解析器，或者请求我们的团队为你创建。解析器是自愈的，并会更新到网站的最新版本。

使用 LLM 提取（schema 和/或 prompt）

提供 llm_extract 以及 JSON Schema (schema) 和/或自然语言指令 (prompt)。你可以同时传递这两个参数，但如果都提供了，schema 优先。相反，如果你只传递 prompt，LLM 将根据提示提取数据，并自行决定数据结构。

from olostep import LLMExtract, Olostep

client = Olostep(api_key="YOUR_REAL_KEY")

result = client.scrapes.create(
    url_to_scrape="https://www.berklee.edu/events/stefano-marchese-friends",
    formats=["markdown", "json"],
    llm_extract=LLMExtract(
        schema={
            "event": {
                "type": "object",
                "properties": {
                    "title": {"type": "string"},
                    "date": {"type": "string"},
                    "description": {"type": "string"},
                    "venue": {"type": "string"},
                    "address": {"type": "string"},
                    "start_time": {"type": "string"},
                },
            }
        }
    ),
)

print(result.json_content)

注意：result.json_content 返回的是字符串化的 JSON。如果你需要对象，请在代码中解析它。 定价： llm_extract 每次抓取花费 10 个积分。为了降低成本，你可以使用自己的 API 密钥或启用基于使用的定价。联系 info@olostep.com 获取访问权限。

提取页面上的链接

使用 links_on_page 选项，你可以提取你抓取的页面上存在的所有链接。它接受以下参数来帮助过滤和排序提取的链接：

absolute_links（布尔值，默认：true）：为 true 时，返回完整的 URL（例如，https://example.com/page）而不是相对路径（例如，/page）。
query_to_order_links_by（字符串）：按与提供的查询文本的相似性排序返回的链接，优先显示最相关的匹配项。
include_links（字符串数组）：使用 glob 模式过滤提取的链接。使用 *.pdf 等模式匹配文件扩展名，/blog/* 匹配特定路径，或完整 URL 如 https://example.com/*。支持通配符（*）、字符类（[a-z]）和交替（{pattern1,pattern2}）。
exclude_links（字符串数组）：使用 glob 模式排除特定链接，遵循与 include_links 相同的语法。

使用动作与页面交互

在抓取前执行动作以与动态网站交互。支持的动作：

wait 带 milliseconds
click 带 selector
fill_input 带 selector 和 value
scroll 带 direction 和 amount

在其他动作之前/之后使用 wait 以允许页面加载通常很有用。

示例

from olostep import FillInputAction, Olostep, WaitAction

client = Olostep(api_key="YOUR_REAL_KEY")

result = client.scrapes.create(
    url_to_scrape="https://example.com/login",
    formats=["markdown"],
    actions=[
        FillInputAction(selector="input[type=email]", value="john@example.com"),
        WaitAction(milliseconds=500),
        FillInputAction(selector="input[type=password]", value="secret"),
        {"type": "click", "selector": "button[type=\"submit\"]"},
        WaitAction(milliseconds=1500),
    ],
)

print(result.markdown_content)

响应将包括任何请求的格式（例如，markdown_content）。

用例

以下是一些客户使用 /scrapes 端点的实际应用。

内容分析与研究

竞争分析：从竞争对手网站提取产品详情、定价和功能
市场研究：分析登陆页面、产品描述和客户评价
学术研究：从科学出版物或研究门户中收集特定数据
法律文档：从官方网站提取案例研究、法规或法律先例

电子商务与零售

动态定价策略：从竞争商店获取实时产品定价
产品信息管理：提取详细规格和描述
库存/库存监控：检查其他零售商的产品可用性
评论分析：收集消费者反馈和特定产品的情感

营销与内容创作

内容策展：为新闻简报提取相关文章和博客文章
SEO 分析：检查竞争对手的关键词使用、元描述和页面结构
线索生成：从商业目录或公司页面提取联系信息
影响者研究：收集参与度指标和影响者个人资料的内容风格
个性化社交媒体生成：通过分析客户网站创建 AI 驱动的社交媒体营销

数据应用

AI 训练数据收集：为机器学习模型收集特定示例
自定义知识库构建：从软件网站提取文档或说明
历史数据档案：在特定时间点保存网站内容
结构化数据提取：将网页内容转换为格式化数据集以进行分析

监控与警报

合规监控：跟踪法律或监管网站的变化
危机管理：监控新闻网站对特定事件或组织的提及
事件跟踪：从场地或组织者网站提取即将举行的活动的详细信息
服务状态监控：检查特定平台或工具的服务状态页面

出版与媒体

新闻聚合：从官方来源提取突发新闻
媒体监控：跨新闻网站跟踪特定主题
内容验证：提取信息以核实声明或陈述
多媒体提取：为媒体库收集嵌入的视频、图像或音频

金融应用

投资研究：从公司网站提取财务报表或年度报告
经济指标：从政府或金融机构网站收集经济数据
加密货币数据：提取实时价格和市值信息
金融新闻分析：监控金融新闻网站以获取特定市场信号

技术应用

API 文档提取：收集技术文档以供参考
集成测试：提取网站元素以验证第三方集成
可访问性测试：分析网站结构以符合可访问性标准
网络档案创建：捕获完整的网站内容以进行历史保存

集成场景

CRM 系统：通过公司网站或 Linkedin 增强客户资料
内容管理系统：导入相关的外部内容
商业智能工具：补充外部市场信息以补充内部数据
项目管理软件：从客户网站提取规格或要求
自定义仪表板：将提取的数据与内部指标一起显示

错误处理

所有错误都遵循共享的信封形状。检查 error.type 和 error.code 以进行编程分支：

{
  "id": "error_abc123",
  "object": "error",
  "created": 1745673871,
  "url": "https://example.com",
  "metadata": {},
  "error": {
    "type": "...",
    "code": "...",
    "message": "..."
  }
}

HTTP	`error.type`	`error.code`	含义
400	`invalid_request_error`	`dns_resolution_failed`	域名不存在或 URL 有拼写错误。
400	`invalid_request_error`	`invalid_url`	URL 格式错误。
502	`invalid_request_error`	`tls_error`	网站有无效或不兼容的 TLS/SSL 证书。`error.detail` 包含低级 SSL 代码。
504	`request_timeout`	`scrape_poll_timeout`	抓取未在 ~55 秒的等待预算内完成。

DNS 失败 (400)

域名无法解析。检查 URL 是否有拼写错误。

{
  "error": {
    "type": "invalid_request_error",
    "code": "dns_resolution_failed",
    "message": "URL 包含拼写错误，或域名不存在。"
  }
}

TLS/SSL 错误 (502)

目标网站有损坏或不兼容的 HTTPS 配置。error.detail 提供特定的 SSL 错误代码以进行诊断；error.code 始终为 tls_error。

{
  "error": {
    "type": "invalid_request_error",
    "code": "tls_error",
    "detail": "err_ssl_tlsv1_alert_internal_error",
    "message": "网站关闭或拒绝 TLS 握手。服务器可能配置错误或使用不支持的 SSL/TLS 版本。"
  }
}

请求超时 (504)

抓取未在等待预算内完成。页面可能很慢、受机器人保护或暂时不可用。此响应可以安全重试。

{
  "error": {
    "type": "request_timeout",
    "code": "scrape_poll_timeout",
    "message": "请求在等待抓取结果时超时。页面可能很慢、对我们的抓取器阻止或暂时不可用。"
  }
}

定价

抓取默认花费 1 个积分。如果你还传递了 parsers，费用根据解析器不同（1-5 个积分）。如果你使用 LLM 提取，则花费 10 个积分。

​抓取 URL

​安装

​使用方法

​响应

​缓存

​工作原理

​新鲜度和 max_age

​使用示例

​何时跳过缓存？

​提取链接

​抓取格式

​提取结构化数据

​使用解析器（推荐用于规模）

​使用 LLM 提取（schema 和/或 prompt）

​提取页面上的链接

​使用动作与页面交互

​示例

​用例

​内容分析与研究

​电子商务与零售

​营销与内容创作

​数据应用

​监控与警报

​出版与媒体

​金融应用

​技术应用

​集成场景

​错误处理

​DNS 失败 (400)

​TLS/SSL 错误 (502)

​请求超时 (504)

​定价

抓取 URL

安装

使用方法

响应

缓存

工作原理

新鲜度和 `max_age`

使用示例

何时跳过缓存？

提取链接

抓取格式

提取结构化数据

使用解析器（推荐用于规模）

使用 LLM 提取（schema 和/或 prompt）

提取页面上的链接

使用动作与页面交互

示例

用例

内容分析与研究

电子商务与零售

营销与内容创作

数据应用

监控与警报

出版与媒体

金融应用

技术应用

集成场景

错误处理

DNS 失败 (400)

TLS/SSL 错误 (502)

请求超时 (504)

定价