> ## Documentation Index
> Fetch the complete documentation index at: https://student-213fb9fc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 抓取



## OpenAPI

````yaml zh/api-reference/v2-openapi.json post /crawl
openapi: 3.0.0
info:
  title: Firecrawl API
  version: v2
  description: 用于与 Firecrawl 服务交互，执行网页抓取和爬取任务的 API。
  contact:
    name: Firecrawl Support
    url: https://firecrawl.dev/support
    email: support@firecrawl.dev
servers:
  - url: https://api.firecrawl.dev/v2
security:
  - bearerAuth: []
paths:
  /crawl:
    post:
      tags:
        - Crawling
      summary: 根据参数爬取多个 URL
      operationId: crawlUrls
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                  description: 用于开始爬取的基础 URL
                prompt:
                  type: string
                  description: 用于根据自然语言生成爬虫选项（包括下方的所有参数）的提示词。显式指定的参数会覆盖生成的对应参数。
                excludePaths:
                  type: array
                  items:
                    type: string
                  description: >-
                    用于将匹配的 URL 排除在爬取之外的 URL 路径名正则表达式模式。例如，如果你为基础 URL
                    firecrawl.dev 设置 `"excludePaths":
                    ["blog/.*"]`，那么所有匹配该模式的结果都会被排除，例如：https://www.firecrawl.dev/blog/firecrawl-launch-week-1-recap。
                includePaths:
                  type: array
                  items:
                    type: string
                  description: >-
                    在抓取过程中用于匹配 URL 的 URL 路径正则表达式规则。只有路径满足这些规则的页面才会包含在响应中。注意：起始
                    URL 也会基于这些规则进行检查——如果起始 URL 不匹配，本次抓取可能返回 0 个页面。例如，如果你在基础 URL
                    firecrawl.dev/blog 下设置 "includePaths": ["blog/.*"]，那么结果中只会包含
                    /blog/
                    下的页面，比如：https://www.firecrawl.dev/blog/firecrawl-launch-week-1-recap。
                maxDiscoveryDepth:
                  type: integer
                  description: >-
                    根据页面被发现的顺序设定的最大爬取深度。根站点和 sitemap 中的页面的发现深度为 0。比如，如果你将其设置为
                    1，并将 `sitemap` 设置为 `'skip'`，则只会爬取你输入的 URL 以及该页面上链接到的所有 URL。
                sitemap:
                  type: string
                  enum:
                    - skip
                    - include
                    - only
                  description: >-
                    爬取时的 Sitemap 处理模式。若设置为“skip”，爬虫会忽略站点的 Sitemap，只爬取你提供的起始
                    URL，并从该页面开始按发现的链接继续爬取。若设置为“only”，爬虫只会根据 Sitemap 中的 URL（加上起始
                    URL）进行爬取，不会再从页面 HTML 中继续发现并跟进新的链接。
                  default: include
                ignoreQueryParameters:
                  type: boolean
                  description: 不要对同一路径使用不同（或没有）查询参数重复抓取
                  default: false
                regexOnFullURL:
                  type: boolean
                  description: >-
                    当设为 true 时，includePaths 和 excludePaths 的正则表达式会匹配完整
                    URL（包括查询参数），而不仅仅是 URL 的路径部分。适用于需要基于查询字符串过滤 URL 的场景。
                  default: false
                limit:
                  type: integer
                  description: 最大爬取页数。默认值为 10000。
                  default: 10000
                crawlEntireDomain:
                  type: boolean
                  description: |-
                    允许爬虫不仅跟踪子路径，还能跟踪同级或父级的站内链接。

                    false：只爬取更深层（子级）URL。
                    → 例如 /features/feature-1 → /features/feature-1/tips ✅
                    → 不会跟踪 /pricing 或 / ❌

                    true：会爬取任意站内链接，包括同级和父级。
                    → 例如 /features/feature-1 → /pricing、/ 等 ✅

                    如需在嵌套路径之外更广泛地覆盖站内页面，请将其设置为 true。
                  default: false
                allowExternalLinks:
                  type: boolean
                  description: 允许爬虫通过链接访问外部网站。
                  default: false
                allowSubdomains:
                  type: boolean
                  description: 允许爬虫通过链接继续爬取主域名下的子域名。
                  default: false
                delay:
                  type: number
                  description: 两次抓取之间的延迟时间（以秒为单位）。有助于遵守网站的速率限制。
                maxConcurrency:
                  type: integer
                  description: 最大并发抓取数量。此参数允许你为本次抓取设置并发上限。如果未指定，则本次抓取将遵循你所在团队的并发限制。
                webhook:
                  type: object
                  description: 一个 Webhook 规范对象。
                  properties:
                    url:
                      type: string
                      description: >-
                        用于接收 webhook 的 URL。该 webhook
                        会在以下事件触发：爬取开始时（crawl.started）、每当有页面被爬取时（crawl.page）、以及爬取结束时（crawl.completed
                        或 crawl.failed）。其响应将与 `/scrape` 端点相同。
                    headers:
                      type: object
                      description: 发送到 webhook URL 的请求头。
                      additionalProperties:
                        type: string
                    metadata:
                      type: object
                      description: 将包含在本次抓取所有 webhook 负载中的自定义元数据
                      additionalProperties: true
                    events:
                      type: array
                      description: 应发送到 webhook URL 的事件类型。（默认：全部）
                      items:
                        type: string
                        enum:
                          - completed
                          - page
                          - failed
                          - started
                  required:
                    - url
                scrapeOptions:
                  $ref: '#/components/schemas/ScrapeOptions'
                zeroDataRetention:
                  type: boolean
                  default: false
                  description: 如果设置为 true，将为本次抓取任务启用零数据保留。要启用此功能，请联系 help@firecrawl.dev
              required:
                - url
      responses:
        '200':
          description: 成功的响应
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrawlResponse'
        '402':
          description: 需要支付
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Payment required to access this resource.
        '429':
          description: 请求次数过多
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: >-
                      Request rate limit exceeded. Please wait and try again
                      later.
        '500':
          description: 服务器错误
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: An unexpected error occurred on the server.
      security:
        - bearerAuth: []
components:
  schemas:
    ScrapeOptions:
      type: object
      properties:
        formats:
          $ref: '#/components/schemas/Formats'
        onlyMainContent:
          type: boolean
          description: 仅返回页面的主要内容，不包含 header、nav、footer 等元素。
          default: true
        includeTags:
          type: array
          items:
            type: string
          description: 在输出中要包含的标签。
        excludeTags:
          type: array
          items:
            type: string
          description: 在输出中需要排除的标签。
        maxAge:
          type: integer
          description: >-
            如果页面的缓存版本的生成时间距今少于该毫秒数，则返回该缓存页面；如果缓存版本距今超过该时间，则会重新抓取页面。若你不需要特别新的数据，启用此选项可将抓取速度提升至
            5 倍。默认值为 2 天。
          default: 172800000
        headers:
          type: object
          description: 随请求发送的请求头。可用于传递 cookies、User-Agent 等信息。
        waitFor:
          type: integer
          description: 指定在抓取内容前的延迟时间（毫秒），以便页面有足够时间完成加载。该等待时间是在 Firecrawl 的智能等待功能基础上的额外等待。
          default: 0
        mobile:
          type: boolean
          description: 若要模拟在移动设备上进行抓取，请将其设置为 true。适用于测试响应式页面并获取移动端截图。
          default: false
        skipTlsVerification:
          type: boolean
          description: 在发起请求时跳过 TLS 证书验证。
          default: true
        timeout:
          type: integer
          description: 请求超时时间（毫秒）。默认 30000（30 秒），最大 300000（300 秒）。
          default: 30000
          maximum: 300000
        parsers:
          type: array
          description: >-
            用于控制在抓取过程中如何处理文件。包含 "pdf" 时（默认），会提取 PDF 内容并转换为 Markdown 格式，计费基于页数（每页
            1 点数）。当传入空数组时，会以 base64 编码返回整个 PDF 文件，并对整份 PDF 按单一费率收取 1 点数。
          items:
            oneOf:
              - type: object
                properties:
                  type:
                    type: string
                    enum:
                      - pdf
                  mode:
                    type: string
                    enum:
                      - fast
                      - auto
                      - ocr
                    default: auto
                    description: >-
                      PDF 解析模式。"fast"：仅执行基于文本的提取（提取内嵌文本，速度最快）。"auto"（默认）：优先尝试
                      fast 提取，如有需要再回退到 OCR。"ocr"：对每一页强制执行 OCR 识别。
                  maxPages:
                    type: integer
                    minimum: 1
                    maximum: 10000
                    description: 从该 PDF 中最多解析的页数。必须为不超过 10000 的正整数。
                required:
                  - type
                additionalProperties: false
          default:
            - pdf
        actions:
          type: array
          description: 在抓取页面内容之前需要执行的页面 actions
          items:
            oneOf:
              - title: Wait
                oneOf:
                  - type: object
                    title: Wait by Duration
                    properties:
                      type:
                        type: string
                        enum:
                          - wait
                        description: 等待指定的毫秒数
                      milliseconds:
                        type: integer
                        minimum: 1
                        description: 要等待的毫秒数
                    required:
                      - type
                      - milliseconds
                    additionalProperties: false
                  - type: object
                    title: Wait for Element
                    properties:
                      type:
                        type: string
                        enum:
                          - wait
                        description: 等待特定元素出现
                      selector:
                        type: string
                        description: 用于等待的 CSS 选择器
                        example: '#my-element'
                    required:
                      - type
                      - selector
                    additionalProperties: false
              - type: object
                title: Screenshot
                properties:
                  type:
                    type: string
                    enum:
                      - screenshot
                    description: 截取屏幕截图。链接将在响应的 `actions.screenshots` 数组中返回。
                  fullPage:
                    type: boolean
                    description: 是否捕获整个页面的截图（忽略 viewport.height），还是仅截取当前视口区域。
                    default: false
                  quality:
                    type: integer
                    description: 截图质量，取值范围为 1 到 100，100 为最高质量。
                  viewport:
                    type: object
                    properties:
                      width:
                        type: integer
                        description: 以像素为单位的视口宽度
                      height:
                        type: integer
                        description: 视口高度（以像素为单位）
                    required:
                      - width
                      - height
                required:
                  - type
              - type: object
                title: Click
                properties:
                  type:
                    type: string
                    enum:
                      - click
                    description: 单击一个元素
                  selector:
                    type: string
                    description: 用于查找元素的查询选择器
                    example: '#load-more-button'
                  all:
                    type: boolean
                    description: 点击所有匹配该选择器的元素，而不仅仅是第一个。即使没有任何元素匹配该选择器，也不会抛出错误。
                    default: false
                required:
                  - type
                  - selector
              - type: object
                title: Write text
                properties:
                  type:
                    type: string
                    enum:
                      - write
                    description: >-
                      向输入框、文本区域或 contenteditable
                      元素写入文本。注意：在写入之前，你必须先使用「click」操作使该元素获得焦点。文本将以逐字符方式输入，以模拟键盘输入。
                  text:
                    type: string
                    description: 要键入的文本
                    example: Hello, world!
                required:
                  - type
                  - text
              - type: object
                title: Press a key
                description: >-
                  请在页面上按下一个按键。按键代码请参见：https://asawicki.info/nosense/doc/devices/keyboard/key_codes.html。
                properties:
                  type:
                    type: string
                    enum:
                      - press
                    description: 在页面上按下任意键
                  key:
                    type: string
                    description: 要按的键
                    example: Enter
                required:
                  - type
                  - key
              - type: object
                title: Scroll
                properties:
                  type:
                    type: string
                    enum:
                      - scroll
                    description: 滚动整个页面或某个特定元素
                  direction:
                    type: string
                    enum:
                      - up
                      - down
                    description: 滚动方向
                    default: down
                  selector:
                    type: string
                    description: 用于滚动的元素选择器
                    example: '#my-element'
                required:
                  - type
              - type: object
                title: Scrape
                properties:
                  type:
                    type: string
                    enum:
                      - scrape
                    description: 抓取当前页面内容，并返回其 URL 和 HTML。
                required:
                  - type
              - type: object
                title: Execute JavaScript
                properties:
                  type:
                    type: string
                    enum:
                      - executeJavascript
                    description: 在页面上执行 JavaScript 代码
                  script:
                    type: string
                    description: 待执行的 JavaScript 代码
                    example: document.querySelector('.button').click();
                required:
                  - type
                  - script
              - type: object
                title: Generate PDF
                properties:
                  type:
                    type: string
                    enum:
                      - pdf
                    description: 生成当前页面的 PDF 文件。该 PDF 文件会通过响应中的 `actions.pdfs` 数组返回。
                  format:
                    type: string
                    enum:
                      - A0
                      - A1
                      - A2
                      - A3
                      - A4
                      - A5
                      - A6
                      - Letter
                      - Legal
                      - Tabloid
                      - Ledger
                    description: 生成的 PDF 的页面大小
                    default: Letter
                  landscape:
                    type: boolean
                    description: 是否以横向方向生成 PDF
                    default: false
                  scale:
                    type: number
                    description: 生成 PDF 的缩放比例
                    default: 1
                required:
                  - type
        location:
          type: object
          description: 请求的地理位置设置。指定后，如果有可用的代理，将使用合适的代理，并模拟相应的语言和时区设置。如果未指定，则默认为“US”。
          properties:
            country:
              type: string
              description: ISO 3166-1 alpha-2 国家/地区代码（例如：“US”、“AU”、“DE”、“JP”）
              pattern: ^[A-Z]{2}$
              default: US
            languages:
              type: array
              description: >-
                按优先级排序的请求首选语言和区域设置。默认为指定位置的语言。详情请参阅：https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language
              items:
                type: string
                example: en-US
        removeBase64Images:
          type: boolean
          description: 从输出中移除所有 Base64 编码图片，以避免内容过于冗长。图片的 alt 文本会保留在输出中，但其 URL 会被占位符替换。
          default: true
        blockAds:
          type: boolean
          description: 启用广告拦截和 Cookie 弹窗拦截功能。
          default: true
        proxy:
          type: string
          enum:
            - basic
            - enhanced
            - auto
          description: |-
            指定要使用的代理类型。

             - **basic**：用于抓取几乎没有或只有基础反爬策略的网站的代理。速度快，通常可用。
             - **enhanced**：用于抓取具有高级反爬策略的网站的增强型代理。速度较慢，但在某些站点上更可靠。每个请求最多消耗 5 点积分。
             - **auto**：当 basic 代理抓取失败时，Firecrawl 会自动重试并切换为 enhanced 代理。如果使用 enhanced 重试成功，该次抓取将收取 5 点积分；如果使用 basic 一次就成功，则只按常规定价计费。
          default: auto
        storeInCache:
          type: boolean
          description: >-
            如果为 true，该页面会存储到 Firecrawl 的索引和缓存中。如果你的抓取操作可能涉及数据保护方面的顾虑，将其设置为 false
            会很有用。使用某些与敏感抓取相关的参数（例如 actions、headers）时，会被强制将此参数设为 false。
          default: true
    CrawlResponse:
      type: object
      properties:
        success:
          type: boolean
        id:
          type: string
        url:
          type: string
          format: uri
    Formats:
      type: array
      items:
        oneOf:
          - type: object
            title: Markdown
            properties:
              type:
                type: string
                enum:
                  - markdown
            required:
              - type
          - type: object
            title: Summary
            properties:
              type:
                type: string
                enum:
                  - summary
            required:
              - type
          - type: object
            title: HTML
            properties:
              type:
                type: string
                enum:
                  - html
            required:
              - type
          - type: object
            title: Raw HTML
            properties:
              type:
                type: string
                enum:
                  - rawHtml
            required:
              - type
          - type: object
            title: Links
            properties:
              type:
                type: string
                enum:
                  - links
            required:
              - type
          - type: object
            title: Images
            properties:
              type:
                type: string
                enum:
                  - images
            required:
              - type
          - type: object
            title: Screenshot
            properties:
              type:
                type: string
                enum:
                  - screenshot
              fullPage:
                type: boolean
                description: 是否捕获整个页面的截图（忽略 viewport.height），还是仅截取当前视口区域。
                default: false
              quality:
                type: integer
                description: 截图质量，范围为 1 到 100，100 为最高质量。
              viewport:
                type: object
                properties:
                  width:
                    type: integer
                    description: 视口宽度（像素）
                  height:
                    type: integer
                    description: 视口高度（像素）
                required:
                  - width
                  - height
            required:
              - type
          - type: object
            title: JSON
            properties:
              type:
                type: string
                enum:
                  - json
              schema:
                type: object
                description: >-
                  用于 JSON 输出的 Schema，必须符合 [JSON
                  Schema](https://json-schema.org/) 规范。
              prompt:
                type: string
                description: 用于生成 JSON 输出的提示
            required:
              - type
          - type: object
            title: Change Tracking
            properties:
              type:
                type: string
                enum:
                  - changeTracking
              modes:
                type: array
                items:
                  type: string
                  enum:
                    - git-diff
                    - json
                description: 用于变更跟踪的模式。`git-diff` 提供详细的差异对比，而 `json` 则对比提取出的 JSON 数据。
              schema:
                type: object
                description: >-
                  在使用「json」模式进行 JSON 提取时所用的 schema。用于定义要提取和对比的数据结构。必须符合 [JSON
                  Schema](https://json-schema.org/) 标准。
              prompt:
                type: string
                description: 在使用 `json` 模式进行变更跟踪时要使用的提示词。如果未提供，将使用默认提示词。
              tag:
                type: string
                nullable: true
                default: null
                description: >-
                  用于变更跟踪的标签。标签可以将变更跟踪历史划分为不同的「分支」，带有特定标签的变更跟踪只会与同一标签下的抓取结果进行比较。如果未提供，则会使用默认标签（null）。
            required:
              - type
          - type: object
            title: Branding
            properties:
              type:
                type: string
                enum:
                  - branding
            required:
              - type
      description: >-
        要在响应中包含的输出 formats。你可以指定一个或多个
        formats，既可以使用字符串（例如：`'markdown'`），也可以使用带有其他选项的对象（例如：`{ type: 'json',
        schema: {...} }`）。某些 formats 需要配置特定选项。示例：`['markdown', { type: 'json',
        schema: {...} }]`。
      default:
        - markdown
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````