> ## Documentation Index
> Fetch the complete documentation index at: https://docs.olostep.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 创建抓取
> 使用提供的配置抓取一个URL并获取内容。
**可选缓存：** 传递 `max_age`（以秒为单位）以重用具有相同参数的最近抓取，而不是再次获取页面。默认值为 `0`（始终最新）。在仪表板游乐场中，默认值为24小时。详情请参见[缓存](/features/scrapes#caching)。
## OpenAPI
````yaml zh/openapi/scrapes.json POST /v1/scrapes
openapi: 3.0.3
info:
title: Scrapes API
version: 1.0.0
servers:
- url: https://api.olostep.com
security: []
paths:
/v1/scrapes:
post:
summary: 启动网页抓取
description: 这个端点允许用户通过各种配置启动网页抓取。
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
url_to_scrape:
type: string
format: uri
description: 开始抓取的URL。
wait_before_scraping:
type: integer
description: 在开始抓取之前等待的时间，以毫秒为单位。
formats:
type: array
items:
type: string
enum:
- html
- markdown
- text
- json
- raw_pdf
- screenshot
description: 你想要内容的格式。
remove_css_selectors:
type: string
enum:
- default
- none
- array
description: >-
选择从内容中移除某些CSS选择器。你也可以传递一个JSON字符串化的数组，指定你想要移除的特定选择器。当此选项设置为默认时，移除的CSS选择器为
['nav','footer','script','style','noscript','svg',[role=alert],[role=banner],[role=dialog],[role=alertdialog],[role=region][aria-label*=skip
i],[aria-modal=true]]
actions:
type: array
items:
type: object
discriminator:
propertyName: type
oneOf:
- type: object
title: 等待
required:
- type
- milliseconds
properties:
type:
type: string
enum:
- wait
description: 等待指定的毫秒数
milliseconds:
type: integer
minimum: 0
description: 等待时间（毫秒）
- type: object
title: 点击
required:
- type
- selector
properties:
type:
type: string
enum:
- click
description: 点击一个元素
selector:
type: string
description: 要点击的元素的CSS选择器
- type: object
title: 填写输入
required:
- type
- selector
- value
properties:
type:
type: string
enum:
- fill_input
description: 用一个值填充输入元素
selector:
type: string
description: 输入元素的CSS选择器
value:
type: string
description: 要输入的文本
- type: object
title: 滚动
required:
- type
- direction
- amount
properties:
type:
type: string
enum:
- scroll
description: 滚动页面
direction:
type: string
enum:
- up
- down
- left
- right
description: 滚动方向
amount:
type: number
description: 滚动的像素量
description: 在获取内容之前对页面执行的操作。
country:
type: string
description: >-
加载请求的住宅国家。 支持的值有： - US (United States) - CA (Canada) - IT
(Italy) - IN (India) - GB (England) - JP (Japan) - MX
(Mexico) - AU (Australia) - ID (Indonesia) - UA (UAE) - RU
(Russia) - RANDOM 一些操作，如抓取Google搜索和Google新闻，支持所有国家。
transformer:
type: string
enum:
- postlight
- none
description: >-
指定要使用的HTML转换器（如果有）。使用Postlight的Mercury
Parser库来移除广告和其他不需要的内容。
remove_images:
type: boolean
description: 选择从抓取的内容中移除图像。默认为false。
default: false
remove_class_names:
type: array
items:
type: string
description: 要从内容中移除的类名列表。
parser:
type: object
properties:
id:
type: string
description: 要使用的解析器ID。
required:
- id
description: >-
当定义json作为格式时，你可以使用此参数指定要使用的解析器。解析器对于从网页中提取结构化内容非常有用。Olostep为大多数常见网页内置了一些解析器，你也可以创建自己的解析器。
llm_extract:
type: object
properties:
schema:
type: object
description: LLM提取的模式。
links_on_page:
type: object
properties:
query_to_order_links_by:
type: string
description: 按照与提供的查询文本的相似性对返回的链接进行排序，优先显示最相关的匹配项。
include_links:
type: array
items:
type: string
description: >-
使用`include_links`通过glob模式过滤提取的链接。模式与链接的URL路径匹配。使用类似"*.pdf"的模式匹配文件扩展名，"/blog/*"匹配特定路径，或完整URL如"https://example.com/*"。支持通配符(*)、字符类([a-z])和交替({pattern1,pattern2})。注意：单个`*`不会跨越`/`，所以"/blog/*"匹配"/blog/post-1"但不匹配索引"/blog"本身（或"/blog?tag=x"，因为查询字符串不是路径的一部分）。要包括索引，请使用"/blog*"或"{/blog,/blog/**}"。
exclude_links:
type: array
items:
type: string
description: >-
使用`exclude_links`通过glob模式过滤提取的链接。模式与链接的URL路径匹配。使用类似"*.pdf"的模式匹配文件扩展名，"/blog/*"匹配特定路径，或完整URL如"https://example.com/*"。支持通配符(*)、字符类([a-z])和交替({pattern1,pattern2})。注意：单个`*`不会跨越`/`，所以"/blog/*"匹配"/blog/post-1"但不匹配索引"/blog"本身（或"/blog?tag=x"，因为查询字符串不是路径的一部分）。
description: 使用此选项，你可以获取你抓取的页面上存在的所有链接。链接始终以绝对URL返回。
screen_size:
type: object
properties:
screen_type:
type: string
enum:
- default
- mobile
- desktop
description: 屏幕类型。桌面使用1920x1080像素，移动设备使用414x896像素，默认使用1024x768像素。
screen_width:
type: integer
description: 屏幕的宽度，以像素为单位。桌面：1920px，移动设备：414px，默认：768px。
screen_height:
type: integer
description: 屏幕的高度，以像素为单位。桌面：1080px，移动设备：896px，默认：1024px。
description: >-
屏幕尺寸配置。通过 screen_type 可用的预设尺寸有：desktop (1920x1080)、mobile
(414x896) 或 default (768x1024)。
screenshot:
type: object
properties:
full_page:
type: boolean
description: 如果传递 true，整个页面的截图将在滚动到网站底部后拍摄。
metadata:
type: object
description: 用户定义的元数据。尚不支持。
max_age:
type: integer
minimum: 0
default: 0
description: >-
缓存内容的最大可接受年龄，以秒为单位。当已存在的抓取匹配并且比 max_age 秒更新时，Olostep
返回存储的结果，而不是启动新的浏览器抓取。默认值为 0（始终抓取最新）。在仪表板游乐场中，默认值为 86400（24
小时）。允许的最大值为 604800（7 天）。有关详细信息，请参阅抓取功能文档中的缓存部分。
required:
- url_to_scrape
responses:
'200':
description: 成功响应，包含抓取启动的详细信息。
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: 抓取 ID
object:
type: string
description: 对象的种类。此端点为 "scrape"。
created:
type: number
description: 创建的纪元时间
metadata:
type: object
description: 用户定义的元数据。
url_to_scrape:
type: string
description: 被抓取的 URL。
result:
type: object
properties:
html_content:
type: string
markdown_content:
type: string
text_content:
type: string
json_content:
type: string
description: 来自解析器的内容。
screenshot_hosted_url:
type: string
html_hosted_url:
type: string
markdown_hosted_url:
type: string
text_hosted_url:
type: string
links_on_page:
type: array
items:
type: string
page_metadata:
type: object
properties:
status_code:
type: integer
title:
type: string
credits_consumed:
type: integer
nullable: true
description: 此请求消耗的积分数量。在执行完成后填充。积分是计费的真实来源。
cost_usd:
type: number
nullable: true
description: >-
此请求的估计成本（以美元计）。在执行完成后填充。根据消耗的积分和你的计划费率计算——99% 准确，但
credits_consumed 是权威值。
'400':
description: >-
由于目标 URL
的问题，无法完成请求。常见代码：`dns_resolution_failed`（域名不存在），`invalid_url`（URL
格式错误）。
content:
application/json:
schema:
type: object
properties:
id:
type: string
object:
type: string
enum:
- error
created:
type: integer
metadata:
type: object
error:
type: object
properties:
type:
type: string
enum:
- invalid_request_error
code:
type: string
example: dns_resolution_failed
message:
type: string
example:
id: error_x2nmu5bqn6
object: error
created: 1777923912
metadata: {}
error:
type: invalid_request_error
code: dns_resolution_failed
message: The URL contains a typo, or the domain does not exist.
'402':
description: 需要付款 — API 密钥无效或已用尽。
'404':
description: 请求的抓取 ID 未找到。
'500':
description: 内部服务器错误。
'502':
description: >-
目标网站存在 TLS/SSL 配置问题。`error.code` 始终为 `tls_error`；`error.detail`
包含具体的低级别 SSL 错误代码（例如
`err_ssl_tlsv1_alert_internal_error`，`cert_verification_failed`）。
content:
application/json:
schema:
type: object
properties:
id:
type: string
object:
type: string
enum:
- error
created:
type: integer
url:
type: string
metadata:
type: object
error:
type: object
properties:
type:
type: string
enum:
- invalid_request_error
code:
type: string
enum:
- tls_error
detail:
type: string
description: 用于诊断的低级别 SSL 错误代码。
message:
type: string
example:
id: error_ogeb6rik8c
object: error
created: 1777923969
url: https://example.com
metadata: {}
error:
type: invalid_request_error
code: tls_error
detail: err_ssl_tlsv1_alert_internal_error
message: >-
The website closed or rejected the TLS handshake. The server
may be misconfigured or use an unsupported SSL/TLS version.
'504':
description: 抓取未在等待预算内完成（约 55 秒）。目标页面可能很慢、受到机器人保护或暂时不可用。可以安全重试。
content:
application/json:
schema:
type: object
properties:
id:
type: string
object:
type: string
enum:
- error
created:
type: integer
url:
type: string
metadata:
type: object
error:
type: object
properties:
type:
type: string
enum:
- request_timeout
code:
type: string
enum:
- scrape_poll_timeout
message:
type: string
example:
id: error_qat3d1amjt
object: error
created: 1777923969
url: https://example.com
metadata: {}
error:
type: request_timeout
code: scrape_poll_timeout
message: >-
Request timed out while waiting for scrape result. The page
may be slow, blocked for our fetchers, or temporarily
unavailable.
security:
- Authorization: []
components:
securitySchemes:
Authorization:
type: http
scheme: bearer
description: Bearer认证头格式为Bearer ，其中是你的认证令牌。
````