Crawl API

概述

POST /v1/crawl 用于按规则批量抓取页面

请求

Endpoint

POST https://run.xcrawl.com/v1/crawl

Headers

Content-Type: application/json
Authorization: Bearer <api_key>

请求体

顶层字段

字段	类型	必填	默认值	说明
`url`	string	是	-	站点入口 URL
`crawler`	object	否	-	爬虫配置
`proxy`	object	否	-	代理配置
`request`	object	否	-	请求配置
`js_render`	object	否	-	JS 渲染配置
`output`	object	否	-	输出配置
`webhook`	object	否	-	异步回调配置

`crawler`（爬虫配置）

字段	类型	必填	默认值	说明
`limit`	integer	否	`100`	抓取页面数量上限
`include`	string[]	否	-	仅抓取匹配规则的 URL（支持正则表达式）
`exclude`	string[]	否	-	排除匹配规则的 URL（支持正则表达式）
`max_depth`	integer	否	`3`	最大爬取深度（从入口开始计算）
`include_entire_domain`	boolean	否	`false`	是否抓取全站内容（而非仅入口子路径下的链接）
`include_subdomains`	boolean	否	`false`	是否包含子域名链接
`include_external_links`	boolean	否	`false`	是否包含外部域名链接
`sitemaps`	boolean	否	`true`	是否使用站点 sitemap

`proxy`（代理配置）

字段	类型	必填	默认值	说明
`location`	string	否	`US`	ISO-3166-1 alpha-2 国家代码，例如 `US` / `JP` / `SG`
`sticky_session`	string	否	自动生成	粘性会话 ID；相同 ID 会尽量复用相同出口

`request`（请求配置）

字段	类型	必填	默认值	说明
`locale`	string	否	`en-US,en;q=0.9`	影响 `Accept-Language`
`device`	string	否	`desktop`	目前支持 `desktop` / `mobile`，会影响 UA 与 viewport
`cookies`	object map	否	-	Cookie 键值对
`headers`	object map	否	-	Header 键值对
`only_main_content`	boolean	否	`true`	仅返回主要内容（尽量过滤导航、侧栏等）
`block_ads`	boolean	否	`true`	尝试屏蔽广告相关资源
`skip_tls_verification`	boolean	否	`true`	跳过 TLS 证书校验

`js_render`（JS 渲染配置）

字段	类型	必填	默认值	说明
`enabled`	boolean	否	`true`	是否启用浏览器渲染
`wait_until`	string	否	`load`	支持 `load` / `domcontentloaded` / `networkidle`
`viewport.width`	integer	否	-	视口宽度：桌面端默认 `1920`，移动端默认 `402`
`viewport.height`	integer	否	-	视口高度：桌面端默认 `1080`，移动端默认 `874`

`output`（输出配置）

字段	类型	必填	默认值	说明
`formats`	string[]	否	`["markdown"]`	输出格式列表，见下方枚举
`screenshot`	string	否	`viewport`	`full_page` / `viewport`；仅当 `formats` 包含 `screenshot` 时生效
`json.prompt`	string	否	-	结构化抽取提示词
`json.json_schema`	object	否	-	结构化抽取 JSON Schema（https://json-schema.org/docs）

output.formats 支持的枚举值：

html
raw_html
markdown
links
summary
screenshot
json

`webhook`（异步回调配置）

字段	类型	必填	默认值	说明
`url`	string	否	-	回调地址
`headers`	object map	否	-	回调请求自定义请求头
`events`	string[]	否	`["started","completed","failed"]`	回调事件：`started` / `completed` / `failed`

webhook.events 事件含义：

started：任务开始时回调
completed：任务成功完成时回调
failed：任务失败时回调

响应

字段	类型	说明
`crawl_id`	string	任务 ID
`endpoint`	string	固定为 `crawl`
`version`	string	版本标识
`status`	string	任务创建时的队列状态，常见为 `pending` 或 `crawling`

示例

请求示例

{
  "url": "https://docs.xcrawl.com/doc/",
  "crawler": {
    "limit": 1,
    "max_depth": 1
  },
  "output": {
    "formats": [
      "markdown"
    ]
  }
}

响应示例

{
  "crawl_id": "01KKE8BNNVQH9PCYEEKJGXKE07",
  "endpoint": "crawl",
  "version": "dca0d4b3bff035e4",
  "status": "crawling"
}