> ## 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. # 批量抓取 > 如果你是需要 Firecrawl API 密钥的 AI 代理，请参阅 [firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) 获取自动化入门说明。 ## OpenAPI ````yaml zh/api-reference/v2-openapi.json POST /batch/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: v2 servers: - url: https://api.firecrawl.dev/v2 security: - bearerAuth: [] paths: /batch/scrape: post: tags: - Scraping summary: 抓取多个 URL，并可选择使用 LLM 提取信息 operationId: scrapeAndExtractFromUrls requestBody: content: application/json: schema: allOf: - properties: ignoreInvalidURLs: default: true description: >- 如果在 urls 数组中指定了无效的 URL，这些 URL 会被忽略。它们不会导致整个请求失败，而是会使用剩余的有效 URL 创建一次批量抓取任务，并在响应的 invalidURLs 字段中返回这些无效的 URL。 type: boolean maxConcurrency: description: 最大并发抓取数。此参数用于为本次批量抓取设置并发上限。若未指定，批量抓取将遵循你的团队的并发限制。 type: integer urls: items: description: 要爬取的 URL format: uri type: string type: array webhook: description: Webhook 规范对象。 properties: events: description: 要发送到该 webhook URL 的事件类型。（默认：全部） items: enum: - completed - page - failed - started type: string type: array headers: additionalProperties: type: string description: 发送到 webhook URL 的请求头。 type: object metadata: additionalProperties: true description: 将添加到此次爬取的所有 webhook 有效载荷中的自定义元数据 type: object url: description: >- 用于接收 webhook 的 URL。它会在批量抓取开始时触发（batch_scrape.started）、每个页面被抓取时触发（batch_scrape.page），以及在批量抓取完成时触发（batch_scrape.completed 或 batch_scrape.failed）。响应与 `/scrape` 端点相同。 type: string required: - url type: object required: - urls 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/BatchScrapeResponseObj' 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: properties: actions: description: 在抓取页面内容之前需要执行的页面 actions items: oneOf: - oneOf: - additionalProperties: false properties: milliseconds: description: 要等待的毫秒数 minimum: 1 type: integer type: description: 等待指定的毫秒数 enum: - wait type: string required: - type - milliseconds title: Wait by Duration type: object - additionalProperties: false properties: selector: description: 用于等待的 CSS 选择器 example: '#my-element' type: string type: description: 等待特定元素出现 enum: - wait type: string required: - type - selector title: Wait for Element type: object title: Wait - properties: fullPage: default: false description: 是否捕获整个页面的截图（忽略 viewport.height），还是仅截取当前视口区域。 type: boolean quality: description: 截图质量，取值范围为 1 到 100，100 为最高质量。 type: integer type: description: 截取屏幕截图。链接将在响应的 `actions.screenshots` 数组中返回。 enum: - screenshot type: string viewport: properties: height: description: 视口高度（以像素为单位） type: integer width: description: 以像素为单位的视口宽度 type: integer required: - width - height type: object 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 formats: $ref: '#/components/schemas/Formats' headers: description: 随请求发送的请求头。可用于传递 cookies、User-Agent 等信息。 type: object includeTags: description: 在输出中要包含的标签。 items: type: string type: array 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 lockdown: default: false description: >- 如果为 true，则仅从 Firecrawl 的缓存中返回该请求的结果，绝不会向目标 URL 发出外部请求。此选项专为受合规要求限制或隔离网络环境而设计，因为爬取请求本身可能会泄露敏感信息。若缓存未命中，则返回 404 和错误代码 SCRAPE_LOCKDOWN_CACHE_MISS（未命中时绝不会记录该 URL）。Lockdown 请求按零数据保留处理。默认 maxAge 会延长至 2 年，因此现有缓存页面仍然仍可使用。命中缓存时计费 5 个额度，缓存未命中时计费 1 个额度。 type: boolean maxAge: default: 172800000 description: >- 如果页面的缓存版本的生成时间距今少于该毫秒数，则返回该缓存页面；如果缓存版本距今超过该时间，则会重新抓取页面。若你不需要特别新的数据，启用此选项可将抓取速度提升至 5 倍。默认值为 2 天。 type: integer minAge: description: |- <[ { "key": "0", "translation": "设置后，请求将仅检查缓存，不会触发新的抓取。该值以毫秒为单位，指定缓存数据必须满足的最小存在时长。如果存在匹配的缓存数据，将立即返回。若未找到缓存数据，则返回 404，错误代码为 SCRAPE_NO_CACHED_DATA。将其设为 1 可接受任意缓存数据，不受时长限制。" } ] type: integer mobile: default: false description: 若要模拟在移动设备上进行抓取，请将其设置为 true。适用于测试响应式页面并获取移动端截图。 type: boolean onlyCleanContent: default: false description: >- 测试版。在已生成的 markdown 上额外执行一轮基于 LLM 的处理，以移除 `onlyMainContent` 可能遗漏的残余样板内容（如 cookie 横幅、广告块、社交分享组件、面包屑导航、新闻简报订阅区、评论区、相关文章列表）。标题、列表、表格、代码块、图片引用和内联链接都会保留。可与 `onlyMainContent` 结合使用（最常见的配置），也可单独使用。当 markdown 超过清理模型的输出 token 限制时，将跳过此步骤并发出警告（原始 markdown 会保留）。不支持零数据保留请求。 type: boolean onlyMainContent: default: true description: 仅返回页面主体内容，不包括页眉、导航栏、页脚等。这是在生成 markdown 之前应用的确定性 HTML 层级过滤；不涉及 LLM。 type: boolean parsers: default: - pdf description: >- 用于控制在抓取过程中如何处理文件。包含 "pdf" 时（默认），会提取 PDF 内容并转换为 Markdown 格式，计费基于页数（每页 1 点数）。当传入空数组时，会以 base64 编码返回整个 PDF 文件，并对整份 PDF 按单一费率收取 1 点数。 items: oneOf: - additionalProperties: false properties: maxPages: description: 从该 PDF 中最多解析的页数。必须为不超过 10000 的正整数。 maximum: 10000 minimum: 1 type: integer mode: default: auto description: >- PDF 解析模式。"fast"：仅执行基于文本的提取（提取内嵌文本，速度最快）。"auto"（默认）：优先尝试 fast 提取，如有需要再回退到 OCR。"ocr"：对每一页强制执行 OCR 识别。 enum: - fast - auto - ocr type: string type: enum: - pdf type: string required: - type type: object type: array profile: description: >- 在抓取和交互会话之间启用持久化浏览器存储。抓取时传入一个 profile，以保留 cookies、localStorage 和会话数据。使用相同 profile 名称的会话会共享浏览器状态。 properties: name: description: 配置文件的名称。使用相同名称的抓取任务会共享浏览器状态（cookies、localStorage、会话）。 maxLength: 128 minLength: 1 type: string saveChanges: default: true description: >- 为 true 时，交互会话停止后，浏览器状态会保存回该 profile。设为 false 则只加载现有数据而不写入。同一时间只允许一个会话执行保存。 type: boolean required: - name type: object proxy: default: auto description: |- 指定要使用的代理类型。 - **basic**：用于抓取几乎没有或只有基础反爬策略的网站的代理。速度快，通常可用。 - **enhanced**：用于抓取具有高级反爬策略的网站的增强型代理。速度较慢，但在某些站点上更可靠。每个请求最多消耗 5 点积分。 - **auto**：当 basic 代理抓取失败时，Firecrawl 会自动重试并切换为 enhanced 代理。如果使用 enhanced 重试成功，该次抓取将收取 5 点积分；如果使用 basic 一次就成功，则只按常规定价计费。 enum: - basic - enhanced - auto type: string redactPII: default: false description: 对返回的 markdown 中的个人身份识别信息进行脱敏。传入 `true` 可使用默认值，或传入一个对象来自定义模式、实体和替换样式。 oneOf: - type: boolean - $ref: '#/components/schemas/RedactPIIOptions' removeBase64Images: default: true description: >- 从 markdown 输出中移除所有 base 64 图像，以避免输出内容过长。这不会影响 html 或 rawHtml formats。图像的 alt 文本会保留在输出中，但 URL 会替换为占位符。 type: boolean skipTlsVerification: default: true description: 在发起请求时跳过 TLS 证书验证。 type: boolean storeInCache: default: true description: >- 如果为 true，该页面会存储到 Firecrawl 的索引和缓存中。如果你的抓取操作可能涉及数据保护方面的顾虑，将其设置为 false 会很有用。使用某些与敏感抓取相关的参数（例如 actions、headers）时，会被强制将此参数设为 false。 type: boolean timeout: default: 60000 description: 请求超时时间（以毫秒为单位）。最小值为 1000（1 秒）。默认值为 60000（60 秒）。最大值为 300000（300 秒）。 maximum: 300000 minimum: 1000 type: integer waitFor: default: 0 description: 指定在抓取内容前的延迟时间（毫秒），以便页面有足够时间完成加载。该等待时间是在 Firecrawl 的智能等待功能基础上的额外等待。 type: integer type: object BatchScrapeResponseObj: properties: id: type: string invalidURLs: description: >- 如果 ignoreInvalidURLs 为 true，则该字段是一个数组，包含请求中指定的所有无效 URL。若没有无效 URL，则该数组为空。如果 ignoreInvalidURLs 为 false，则该字段为 undefined。 items: type: string nullable: true type: array success: type: boolean url: format: uri type: string type: object Formats: default: - markdown description: >- 要在响应中包含的输出 formats。你可以指定一个或多个 formats，既可以使用字符串（例如：`'markdown'`），也可以使用带有其他选项的对象（例如：`{ type: 'json', schema: {...} }`）。某些 formats 需要配置特定选项。示例：`['markdown', { type: 'json', schema: {...} }]`。 items: oneOf: - properties: type: enum: - markdown type: string required: - type title: Markdown type: object - properties: type: enum: - summary type: string required: - type title: Summary type: object - properties: type: enum: - html type: string required: - type title: HTML type: object - properties: type: enum: - rawHtml type: string required: - type title: Raw HTML type: object - properties: type: enum: - links type: string required: - type title: Links type: object - properties: type: enum: - images type: string required: - type title: Images type: object - properties: fullPage: default: false description: 是否捕获整个页面的截图（忽略 viewport.height），还是仅截取当前视口区域。 type: boolean quality: description: 截图质量，范围为 1 到 100，100 为最高质量。 type: integer type: enum: - screenshot type: string viewport: properties: height: description: 视口高度（像素） type: integer width: description: 视口宽度（像素） type: integer required: - width - height type: object required: - type title: Screenshot type: object - properties: prompt: description: 用于生成 JSON 输出的提示 type: string schema: description: >- 用于 JSON 输出的 Schema，必须符合 [JSON Schema](https://json-schema.org/) 规范。 type: object type: enum: - json type: string required: - type title: JSON type: object - 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: enum: - changeTracking type: string required: - type title: Change Tracking type: object - properties: type: enum: - branding type: string required: - type title: Branding type: object - properties: type: enum: - product type: string required: - type title: Product type: object - properties: type: enum: - menu type: string required: - type title: Menu type: object - description: 从受支持的视频 URL（如 YouTube）中提取音频（MP3）。返回已签名的 GCS URL。 properties: type: enum: - audio type: string required: - type title: Audio type: object - description: 从受支持的视频 URL（如 YouTube）中提取最高画质的视频。返回已签名的 GCS URL。 properties: type: enum: - video type: string required: - type title: Video type: object - description: 针对页面提出自然语言问题。答案会在响应的 `answer` 字段中返回。 properties: question: description: 要回答的页面相关问题。最大长度为 10,000 个字符。 maxLength: 10000 type: string type: enum: - question type: string required: - type - question title: Question type: object - description: 从页面中查找相关源文本。选中的文本会在响应的 `highlights` 字段中返回。 properties: query: description: 要对页面执行的文本选择查询。最大长度为 10,000 个字符。 maxLength: 10000 type: string type: enum: - highlights type: string required: - type - query title: Highlights type: object type: array RedactPIIOptions: additionalProperties: false description: PII 脱敏的配置选项。 properties: entities: description: 将脱敏限制为这些实体类别。如果省略，则会对所有支持的实体进行脱敏。 items: $ref: '#/components/schemas/RedactPIIEntity' type: array mode: default: accurate description: >- 脱敏策略。`accurate` 仅使用模型，针对准确性进行了优化；`aggressive` 通过额外的启发式规则提高召回率；`fast` 则仅使用启发式规则，不调用模型。 enum: - accurate - aggressive - fast type: string replaceStyle: default: tag description: >- `tag` 会将文本片段替换为 `` 这类占位符，`mask` 会用 `*` 替换字符，`remove` 会删除该文本片段。 enum: - tag - mask - remove type: string type: object RedactPIIEntity: description: Firecrawl 脱敏支持的公开 PII 实体类别。 enum: - PERSON - EMAIL - PHONE - LOCATION - FINANCIAL - SECRET type: string securitySchemes: bearerAuth: scheme: bearer type: http ````