> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firecrawl.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 抓取

> 注意：全新的 [此 API 的 v2 版本](/zh/api-reference/endpoint/scrape) 现已上线，提供更强大的功能和更高的性能。


## OpenAPI

````yaml zh/api-reference/v1-openapi.json POST /scrape
openapi: 3.0.0
info:
  contact:
    email: support@firecrawl.dev
    name: Firecrawl Support
    url: https://firecrawl.dev/support
  description: 用于与 Firecrawl 服务交互，以进行网页抓取和爬取任务的 API。
  title: Firecrawl API
  version: v1
servers:
  - url: https://api.firecrawl.dev/v1
security:
  - bearerAuth: []
paths:
  /scrape:
    post:
      tags:
        - Scraping
      summary: 抓取单个 URL，并可选择使用 LLM 提取信息
      operationId: scrapeAndExtractFromUrl
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - properties:
                    url:
                      description: 要爬取的 URL
                      format: uri
                      type: string
                  required:
                    - url
                  type: object
                - $ref: '#/components/schemas/ScrapeOptions'
                - properties:
                    zeroDataRetention:
                      default: false
                      description: 如果为 true，将对本次抓取启用零数据保留策略。要开启此功能，请联系 help@firecrawl.dev
                      type: boolean
                  type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScrapeResponse'
          description: 成功响应
        '402':
          content:
            application/json:
              schema:
                properties:
                  error:
                    example: Payment required to access this resource.
                    type: string
                type: object
          description: 需要付费
        '429':
          content:
            application/json:
              schema:
                properties:
                  error:
                    example: >-
                      Request rate limit exceeded. Please wait and try again
                      later.
                    type: string
                type: object
          description: 请求次数过多
        '500':
          content:
            application/json:
              schema:
                properties:
                  error:
                    example: An unexpected error occurred on the server.
                    type: string
                type: object
          description: 服务器错误
      security:
        - bearerAuth: []
components:
  schemas:
    ScrapeOptions:
      allOf:
        - $ref: '#/components/schemas/BaseScrapeOptions'
        - properties:
            changeTrackingOptions:
              description: >-
                用于 changeTracking 的选项（Beta）。仅当在 formats 中包含 'changeTracking'
                时才适用。使用 changeTracking 时，还必须同时指定 'markdown' 格式。
              properties:
                modes:
                  description: 用于更改跟踪的模式。`git-diff` 提供详细的差异对比，而 `json` 用于比较提取的 JSON 数据。
                  items:
                    enum:
                      - git-diff
                      - json
                    type: string
                  type: array
                prompt:
                  description: 在使用 JSON 模式进行变更跟踪时要使用的提示。如果未提供，则会使用默认提示。
                  type: string
                schema:
                  description: >-
                    在使用 `json` 模式时用于 JSON 提取的 schema。用于定义要提取和对比的数据结构。必须符合 [JSON
                    Schema](https://json-schema.org/) 规范。
                  type: object
                tag:
                  default: null
                  description: >-
                    用于变更跟踪的标签。标签可以将变更跟踪历史划分为不同的「分支」，使用特定标签的变更跟踪只会与同一标签下的抓取结果进行比较。如果未提供，则会使用默认标签（null）。
                  nullable: true
                  type: string
              type: object
            formats:
              default:
                - markdown
              description: 输出中要包含的formats。
              items:
                enum:
                  - markdown
                  - html
                  - rawHtml
                  - links
                  - screenshot
                  - screenshot@fullPage
                  - json
                  - changeTracking
                type: string
              type: array
          type: object
    ScrapeResponse:
      properties:
        data:
          properties:
            actions:
              description: '`actions` 参数中各项 actions 的执行结果。仅当请求中提供了 `actions` 参数时才会包含此字段。'
              nullable: true
              properties:
                javascriptReturns:
                  description: JavaScript 的返回值，其顺序与提供的 executeJavascript actions 相同。
                  items:
                    properties:
                      type:
                        type: string
                      value: {}
                    type: object
                  type: array
                pdfs:
                  description: 生成的 PDF，其顺序与提供的 pdf actions 保持一致。
                  items:
                    type: string
                  type: array
                scrapes:
                  description: 按照提供的 scrape actions 的顺序抓取内容。
                  items:
                    properties:
                      html:
                        type: string
                      url:
                        type: string
                    type: object
                  type: array
                screenshots:
                  description: 截图 URL，与提供的截图 actions 顺序一致。截图将在 24 小时后过期，之后将无法再下载。
                  items:
                    format: url
                    type: string
                  type: array
              type: object
            changeTracking:
              description: >-
                当 `formats` 中包含 `changeTracking` 时，会返回变更追踪信息。仅在请求
                `changeTracking` format 时才会提供。
              nullable: true
              properties:
                changeStatus:
                  description: >-
                    两个页面版本比较的结果。`new` 表示该页面之前不存在，`same` 表示内容没有变化，`changed`
                    表示内容发生了变化，`removed` 表示该页面已被移除。
                  enum:
                    - new
                    - same
                    - changed
                    - removed
                  type: string
                diff:
                  description: 在使用“git-diff”模式时生成的 Git 风格差异（diff）。仅在模式设置为“git-diff”时才会出现。
                  nullable: true
                  type: string
                json:
                  description: >-
                    在使用 `json` 模式时的 JSON 比较结果。仅在模式设置为 `json` 时可用。它会根据 `schema`
                    中定义的类型，返回 `previous` 和 `current`
                    抓取结果中所有键及其对应值的列表。示例参见[这里](/features/change-tracking)
                  nullable: true
                  type: object
                previousScrapeAt:
                  description: 用于与当前页面进行比较的上一次抓取时间戳。如果不存在之前的抓取记录，则为 null。
                  format: date-time
                  nullable: true
                  type: string
                visibility:
                  description: >-
                    当前页面/URL 的可见性。"visible" 表示该 URL 是通过自然路径（链接或
                    sitemap）发现的，"hidden" 表示该 URL 是通过之前抓取结果的记忆发现的。
                  enum:
                    - visible
                    - hidden
                  type: string
              type: object
            html:
              description: >-
                当 `formats` 中包含 `html` 时，返回页面的已清理 HTML：会移除
                `<script>`、`<style>`、`<noscript>`、`<meta>` 和 `<head>` 标签；将相对 URL
                转换为绝对 URL；并将响应式图片的 `srcset` 解析为尺寸最大的版本。同时会应用
                `onlyMainContent`、`includeTags` 和 `excludeTags` 过滤器。
              nullable: true
              type: string
            links:
              description: 当 `formats` 中包含 `links` 时，页面上的链接列表
              items:
                type: string
              type: array
            llm_extraction:
              description: 在使用 LLM 提取时显示。根据定义的 schema 从页面中提取的数据。
              nullable: true
              type: object
            markdown:
              type: string
            metadata:
              properties:
                '<any other metadata> ':
                  type: string
                description:
                  type: string
                error:
                  description: 页面错误信息
                  nullable: true
                  type: string
                keywords:
                  description: 从页面中提取的关键词，可以为字符串或字符串数组
                  oneOf:
                    - type: string
                    - items:
                        type: string
                      type: array
                language:
                  nullable: true
                  type: string
                numPages:
                  description: 对于 PDF 输入，表示已解析的页数（受 parser 的 maxPages 选项上限限制）。
                  type: integer
                ogLocaleAlternate:
                  description: 此页面的其他语言版本
                  items:
                    type: string
                  type: array
                sourceURL:
                  format: uri
                  type: string
                statusCode:
                  description: 页面状态码
                  type: integer
                title:
                  type: string
                totalPages:
                  description: >-
                    对于 PDF 输入，表示文档在未受 maxPages 限制前的实际总页数。若无法确定则省略；如果 totalPages
                    大于 numPages，则表示结果已被截断。
                  type: integer
              type: object
            rawHtml:
              description: 当 `formats` 中包含 `rawHtml` 时，将返回从页面获取的原始、未处理的 HTML，不会执行任何清洗或过滤操作。
              nullable: true
              type: string
            screenshot:
              description: 如果在 `formats` 中包含 `screenshot`，将返回该页面的截图。截图将在 24 小时后失效，之后将无法再下载。
              nullable: true
              type: string
            warning:
              description: 在使用 LLM Extraction 时显示。警告信息会提示你提取过程中的任何问题。
              nullable: true
              type: string
          type: object
        success:
          type: boolean
      type: object
    BaseScrapeOptions:
      properties:
        actions:
          description: 在抓取页面内容前需要执行的 actions
          items:
            oneOf:
              - properties:
                  milliseconds:
                    description: 等待的时间（毫秒）
                    minimum: 1
                    type: integer
                  selector:
                    description: 用于定位该元素的查询选择器
                    example: '#my-element'
                    type: string
                  type:
                    description: 等待指定的毫秒数
                    enum:
                      - wait
                    type: string
                required:
                  - type
                title: Wait
                type: object
              - properties:
                  fullPage:
                    default: false
                    description: 是否截取整页截图，或仅截取当前视口。
                    type: boolean
                  quality:
                    description: 截图质量，取值范围为 1 至 100，100 为最高质量。
                    type: integer
                  type:
                    description: 进行截图。链接将位于响应的 `actions.screenshots` 数组中。
                    enum:
                      - screenshot
                    type: string
                required:
                  - type
                title: Screenshot
                type: object
              - properties:
                  all:
                    default: false
                    description: 点击所有匹配该选择器的元素，而不仅仅是第一个元素。如果没有元素匹配该选择器，也不会抛出错误。
                    type: boolean
                  selector:
                    description: 用于查找元素的查询选择器
                    example: '#load-more-button'
                    type: string
                  type:
                    description: 单击元素
                    enum:
                      - click
                    type: string
                required:
                  - type
                  - selector
                title: Click
                type: object
              - properties:
                  text:
                    description: 输入文本
                    example: Hello, world!
                    type: string
                  type:
                    description: >-
                      在输入框、文本区域或 contenteditable
                      元素中写入文本。注意：在写入之前，必须先通过一次“click”操作使该元素获得焦点。文本将以逐字符输入的方式进行，以模拟键盘敲击。
                    enum:
                      - write
                    type: string
                required:
                  - type
                  - text
                title: Write text
                type: object
              - description: >-
                  请在页面上按下任意键。按键代码请参考：https://asawicki.info/nosense/doc/devices/keyboard/key_codes.html。
                properties:
                  key:
                    description: 按键
                    example: Enter
                    type: string
                  type:
                    description: 在页面上按下任意键
                    enum:
                      - press
                    type: string
                required:
                  - type
                  - key
                title: Press a key
                type: object
              - properties:
                  direction:
                    default: down
                    description: 滚动方向
                    enum:
                      - up
                      - down
                    type: string
                  selector:
                    description: 需要滚动的元素的查询选择器
                    example: '#my-element'
                    type: string
                  type:
                    description: 滚动页面或特定元素
                    enum:
                      - scroll
                    type: string
                required:
                  - type
                title: Scroll
                type: object
              - properties:
                  type:
                    description: 抓取当前页面内容，同时返回其 URL 和 HTML。
                    enum:
                      - scrape
                    type: string
                required:
                  - type
                title: Scrape
                type: object
              - properties:
                  script:
                    description: 待执行的 JavaScript 代码
                    example: document.querySelector('.button').click();
                    type: string
                  type:
                    description: 在页面上执行 JavaScript 代码
                    enum:
                      - executeJavascript
                    type: string
                required:
                  - type
                  - script
                title: Execute JavaScript
                type: object
              - properties:
                  format:
                    default: Letter
                    description: 生成的 PDF 的页面大小
                    enum:
                      - A0
                      - A1
                      - A2
                      - A3
                      - A4
                      - A5
                      - A6
                      - Letter
                      - Legal
                      - Tabloid
                      - Ledger
                    type: string
                  landscape:
                    default: false
                    description: 是否以横向页面方向生成 PDF 文件
                    type: boolean
                  scale:
                    default: 1
                    description: 生成的 PDF 的缩放比例
                    type: number
                  type:
                    description: 生成当前页面的 PDF。该 PDF 将在响应中的 `actions.pdfs` 数组里返回。
                    enum:
                      - pdf
                    type: string
                required:
                  - type
                title: Generate PDF
                type: object
          type: array
        blockAds:
          default: true
          description: 启用广告拦截和 Cookie 弹窗屏蔽。
          type: boolean
        excludeTags:
          description: 在输出结果中要排除的标签。
          items:
            type: string
          type: array
        headers:
          description: 随请求发送的请求头。可用于携带 cookies、user-agent 等信息。
          type: object
        includeTags:
          description: 需要包含在输出中的标签。
          items:
            type: string
          type: array
        jsonOptions:
          description: JSON 配置对象
          properties:
            prompt:
              description: 在无 schema 情况下用于抽取的数据提示词（可选）
              type: string
            schema:
              description: 用于提取的数据模式（可选）。必须符合 [JSON Schema](https://json-schema.org/) 规范。
              type: object
            systemPrompt:
              description: 用于抽取的系统提示（可选）
              type: string
          type: object
        location:
          description: 请求的地理位置设置。指定后，如果可用，将使用合适的代理服务器，并模拟相应的语言和时区设置。如果未指定，默认值为“US”。
          properties:
            country:
              default: US
              description: ISO 3166-1 alpha-2 两位字母国家代码（例如：“US”、“AU”、“DE”、“JP”）
              pattern: ^[A-Z]{2}$
              type: string
            languages:
              description: >-
                按照优先级为本次请求指定首选语言和区域设置。默认使用所指定地区的语言。详见：https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language
              items:
                example: en-US
                type: string
              type: array
          type: object
        maxAge:
          default: 0
          description: >-
            如果页面的缓存版本的生成时间距现在小于此值（毫秒），则返回该缓存版本；如果缓存版本早于此值，则会重新抓取页面。如果你不需要极其实时的数据，启用此选项可以将抓取速度最多提升
            5 倍。默认值为 0，表示禁用缓存。
          type: integer
        mobile:
          default: false
          description: 若要模拟移动端抓取，请将其设置为 true。适用于测试响应式页面并获取移动端截图。
          type: boolean
        onlyMainContent:
          default: true
          description: 仅返回页面的主体内容，不包括页眉、导航、页脚等。
          type: boolean
        parsePDF:
          default: true
          description: >-
            控制在爬取过程中如何处理 PDF 文件。为 true 时，会提取 PDF 内容并转换为 Markdown 格式，按页数计费（每页 1
            个积分）。为 false 时，会返回以 base64 编码的 PDF 文件，统一按 1 个积分计费。
          type: boolean
        proxy:
          description: |-
            指定要使用的代理类型。

             - **basic**：适用于抓取没有或仅有基础防爬机制网站的代理。速度快，通常足够好用。
             - **enhanced**：适用于抓取具有高级防爬机制网站的增强型代理。速度较慢，但在某些网站上更可靠。每次请求最多消耗 5 个积分。
             - **auto**：当使用 basic 代理抓取失败时，Firecrawl 会自动使用 enhanced 代理重试。如果使用 enhanced 重试成功，该次抓取将收取 5 个积分；如果首次使用 basic 即抓取成功，则只收取常规费用。

            如果未指定代理类型，Firecrawl 将默认使用 basic。
          enum:
            - basic
            - enhanced
            - auto
          type: string
        removeBase64Images:
          default: true
          description: 从输出中移除所有 Base64 图片，以避免内容过于冗长。图片的替代文本（alt 文本）会保留在输出中，但其 URL 会被占位符替换。
          type: boolean
        skipTlsVerification:
          default: false
          description: 在发送请求时跳过 TLS 证书校验
          type: boolean
        storeInCache:
          default: true
          description: >-
            如果为 true，该页面将被存储到 Firecrawl 的索引和缓存中。若你的抓取活动可能涉及数据保护方面的问题，将其设置为 false
            会更合适。使用某些与敏感抓取相关的参数（如 actions、headers）时，该参数会被强制设为 false。
          type: boolean
        threatProtection:
          $ref: '#/components/schemas/ThreatProtectionOverride'
        timeout:
          default: 30000
          description: 请求超时时间（毫秒）
          type: integer
        waitFor:
          default: 0
          description: 设置在获取内容前的延迟时间（毫秒），以便页面有足够时间加载完成。
          type: integer
      type: object
    ThreatProtectionOverride:
      description: >-
        此请求的 [威胁防护](https://docs.firecrawl.dev/features/threat-protection)
        单次请求覆盖配置。你提供的字段只会替换本次请求中组织策略里的对应字段；未提供的字段将保留组织级别的值。你的团队必须已启用威胁防护（企业版功能），否则该请求将被
        403 拒绝。如果你的组织已禁用单次请求覆盖，任何包含此对象的请求都会被 403 拒绝。如果你的团队强制启用了威胁防护，则不能将 `mode`
        设为 `off`。
      properties:
        blacklist:
          description: 始终封禁的域名，可为普通域名（`example.com`）或通配 glob（`*.example.com`）。不包含协议、路径或端口。
          items:
            type: string
          maxItems: 1000
          type: array
        blockedTlds:
          description: 要直接封禁的顶级域名，使用不带前导点的小写形式（例如 `zip`）。
          items:
            type: string
          maxItems: 1000
          type: array
        failurePolicy:
          description: 当无法访问分类器时的处理方式：`closed` 会封禁该请求，`open` 则会允许该请求。
          enum:
            - open
            - closed
          type: string
        mode:
          description: >-
            此请求的 URL 扫描模式。`normal` 会根据 Google Web Risk 检查 URL（每扫描一个 URL 额外消耗 2
            点额度）。
          enum:
            - 'off'
            - normal
          type: string
        riskScoreThreshold:
          description: 标准化风险分数阈值（0–100）：当分类器判定结果达到或超过该值时，URL 会被封禁。值越低，限制越严格。
          example: 75
          maximum: 100
          minimum: 0
          type: integer
        whitelist:
          description: 始终允许的域名，可为普通域名或通配 glob。其优先级高于其他所有规则。
          items:
            type: string
          maxItems: 1000
          type: array
      title: Threat Protection Override
      type: object
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http

````