# 更新监控 (/zh/api-reference/endpoint/monitor-update) Related: [Search（搜索）](/zh/api-reference/endpoint/search.md), [搜索反馈](/zh/api-reference/endpoint/search-feedback.md), [Scrape](/zh/api-reference/endpoint/scrape.md), [批量抓取](/zh/api-reference/endpoint/batch-scrape.md), [获取批量抓取状态](/zh/api-reference/endpoint/batch-scrape-get.md), [取消批量抓取](/zh/api-reference/endpoint/batch-scrape-delete.md) `PATCH /monitor/{monitorId}` 更新监控 ## OpenAPI ```json { "security": [ { "bearerAuth": [] } ], "parameters": [ { "description": "监控 ID", "in": "path", "name": "monitorId", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "schedule": { "text": "every 15 minutes starting at :07" }, "status": "active" }, "schema": { "description": "部分监控更新 payload。请至少包含一个字段。", "properties": { "goal": { "description": "用于判定页面变更是否有实际意义的自然语言目标。若提供此字段且省略 `judgeEnabled`，则会自动启用判定。当任一目标为 `search` 目标时，除非 `judgeEnabled` 为 `false`，否则此字段必填且不得为空。", "maxLength": 2000, "nullable": true, "type": "string" }, "judgeEnabled": { "description": "是否根据 `goal` 判断已变更页面。运行时需要提供非空的 `goal`。", "type": "boolean" }, "name": { "maxLength": 256, "type": "string" }, "notification": { "properties": { "email": { "properties": { "enabled": { "default": false, "type": "boolean" }, "includeDiffs": { "default": false, "description": "在电子邮件摘要中包含已变更页面的详细信息。", "type": "boolean" }, "recipients": { "items": { "format": "email", "type": "string" }, "maxItems": 25, "type": "array" } }, "type": "object" } }, "type": "object" }, "retentionDays": { "maximum": 365, "minimum": 1, "type": "integer" }, "schedule": { "description": "监控检查的调度计划。请提供 `cron` 或 `text` 其中之一。", "properties": { "cron": { "description": "五字段 cron 表达式。最短间隔为 5 分钟。", "example": "*/30 * * * *", "type": "string" }, "text": { "description": "自然语言调度设置。支持的示例包括 `every 30 minutes`、`every 15 minutes starting at :07`、`hourly`、`every 2 hours`、`daily`、`daily at 9:00`、`daily at 9am`、`daily at 5:30 PM` 和 `weekly`。", "example": "every 30 minutes", "type": "string" }, "timezone": { "default": "UTC", "description": "该调度计划使用的 IANA 时区。", "example": "UTC", "type": "string" } }, "type": "object" }, "status": { "enum": [ "active", "paused" ], "type": "string" }, "targets": { "items": { "oneOf": [ { "properties": { "id": { "description": "此目标的可选稳定 ID。若省略则会自动生成。", "format": "uuid", "type": "string" }, "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" }, "auditMetadata": { "additionalProperties": false, "description": "为组织启用 SIEM Logging 后，SIEM 日志事件中会包含用户归属信息。", "properties": { "username": { "description": "与该请求关联的用户名。", "maxLength": 1024, "type": "string" } }, "required": [ "username" ], "type": "object" }, "blockAds": { "default": true, "description": "启用广告拦截和 Cookie 弹窗拦截功能。", "type": "boolean" }, "excludeTags": { "description": "在输出中需要排除的标签。", "items": { "type": "string" }, "type": "array" }, "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" }, "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": "<[\n {\n \"key\": \"0\",\n \"translation\": \"设置后，请求将仅检查缓存，不会触发新的抓取。该值以毫秒为单位，指定缓存数据必须满足的最小存在时长。如果存在匹配的缓存数据，将立即返回。若未找到缓存数据，则返回 404，错误代码为 SCRAPE_NO_CACHED_DATA。将其设为 1 可接受任意缓存数据，不受时长限制。\"\n }\n]", "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": "指定要使用的代理类型。\n\n - **basic**：用于抓取几乎没有或只有基础反爬策略的网站的代理。速度快，通常可用。\n - **enhanced**：用于抓取具有高级反爬策略的网站的增强型代理。速度较慢，但在某些站点上更可靠。每个请求最多消耗 5 点积分。\n - **auto**：当 basic 代理抓取失败时，Firecrawl 会自动重试并切换为 enhanced 代理。如果使用 enhanced 重试成功，该次抓取将收取 5 点积分；如果使用 basic 一次就成功，则只按常规定价计费。", "enum": [ "basic", "enhanced", "auto" ], "type": "string" }, "redactPII": { "default": false, "description": "对返回的 markdown 中的个人身份识别信息进行脱敏。传入 `true` 可使用默认值，或传入一个对象来自定义模式、实体和替换样式。", "oneOf": [ { "type": "boolean" }, { "additionalProperties": false, "description": "PII 脱敏的配置选项。", "properties": { "entities": { "description": "将脱敏限制为这些实体类别。如果省略，则会对所有支持的实体进行脱敏。", "items": { "description": "Firecrawl 脱敏支持的公开 PII 实体类别。", "enum": [ "PERSON", "EMAIL", "PHONE", "LOCATION", "FINANCIAL", "SECRET" ], "type": "string" }, "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" } ] }, "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" }, "threatProtection": { "description": "此请求的[威胁防护](https://docs.firecrawl.dev/features/threat-protection)按请求覆盖配置。你提供的字段仅会替换此次请求中你所在组织策略的对应字段；未提供的字段则保留组织级配置值。你的团队必须已启用威胁防护（企业版功能），否则该请求会因 403 被拒绝。如果你的组织已禁用请求级覆盖，任何包含此对象的请求都会因 403 被拒绝。如果你的团队强制启用了威胁防护，则不得将 `mode` 设为 `off`。", "properties": { "blacklist": { "description": "始终封禁的域名，可使用普通域名（`example.com`）或通配符模式（`*.example.com`）。不包含协议、路径或端口。", "items": { "type": "string" }, "maxItems": 1000, "type": "array" }, "blockedTlds": { "description": "直接封禁的顶级域名，使用不带前导点的小写形式（例如 `zip`）。", "items": { "type": "string" }, "maxItems": 1000, "type": "array" }, "failurePolicy": { "description": "当无法访问 classifier 时的处理方式：`closed` 会封禁该请求，`open` 则允许该请求。", "enum": [ "open", "closed" ], "type": "string" }, "mode": { "description": "此次请求的 URL 扫描模式。`normal` 使用 Google Web Risk 检查 URL（每扫描 1 个 URL 额外消耗 2 个额度）。", "enum": [ "off", "normal" ], "type": "string" }, "riskScoreThreshold": { "description": "归一化风险评分（0–100）阈值。达到或超过该值时，分类器判定会封禁该 URL。值越低，限制越严格。", "example": 75, "maximum": 100, "minimum": 0, "type": "integer" }, "whitelist": { "description": "始终允许的域名，可使用普通域名或通配符模式。优先级高于其他所有规则。", "items": { "type": "string" }, "maxItems": 1000, "type": "array" } }, "title": "Threat Protection Override", "type": "object" }, "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" }, "type": { "enum": [ "scrape" ], "type": "string" }, "urls": { "items": { "format": "uri", "type": "string" }, "minItems": 1, "type": "array" } }, "required": [ "type", "urls" ], "title": "Scrape target", "type": "object" }, { "properties": { "crawlOptions": { "description": "爬取选项，例如 `limit`、`maxDepth`、`includePaths` 和 `excludePaths`。", "type": "object" }, "id": { "description": "此目标的可选稳定 ID。若省略则会自动生成。", "format": "uuid", "type": "string" }, "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" }, "auditMetadata": { "additionalProperties": false, "description": "为组织启用 SIEM Logging 后，SIEM 日志事件中会包含用户归属信息。", "properties": { "username": { "description": "与该请求关联的用户名。", "maxLength": 1024, "type": "string" } }, "required": [ "username" ], "type": "object" }, "blockAds": { "default": true, "description": "启用广告拦截和 Cookie 弹窗拦截功能。", "type": "boolean" }, "excludeTags": { "description": "在输出中需要排除的标签。", "items": { "type": "string" }, "type": "array" }, "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" }, "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": "<[\n {\n \"key\": \"0\",\n \"translation\": \"设置后，请求将仅检查缓存，不会触发新的抓取。该值以毫秒为单位，指定缓存数据必须满足的最小存在时长。如果存在匹配的缓存数据，将立即返回。若未找到缓存数据，则返回 404，错误代码为 SCRAPE_NO_CACHED_DATA。将其设为 1 可接受任意缓存数据，不受时长限制。\"\n }\n]", "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": "指定要使用的代理类型。\n\n - **basic**：用于抓取几乎没有或只有基础反爬策略的网站的代理。速度快，通常可用。\n - **enhanced**：用于抓取具有高级反爬策略的网站的增强型代理。速度较慢，但在某些站点上更可靠。每个请求最多消耗 5 点积分。\n - **auto**：当 basic 代理抓取失败时，Firecrawl 会自动重试并切换为 enhanced 代理。如果使用 enhanced 重试成功，该次抓取将收取 5 点积分；如果使用 basic 一次就成功，则只按常规定价计费。", "enum": [ "basic", "enhanced", "auto" ], "type": "string" }, "redactPII": { "default": false, "description": "对返回的 markdown 中的个人身份识别信息进行脱敏。传入 `true` 可使用默认值，或传入一个对象来自定义模式、实体和替换样式。", "oneOf": [ { "type": "boolean" }, { "additionalProperties": false, "description": "PII 脱敏的配置选项。", "properties": { "entities": { "description": "将脱敏限制为这些实体类别。如果省略，则会对所有支持的实体进行脱敏。", "items": { "description": "Firecrawl 脱敏支持的公开 PII 实体类别。", "enum": [ "PERSON", "EMAIL", "PHONE", "LOCATION", "FINANCIAL", "SECRET" ], "type": "string" }, "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" } ] }, "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" }, "threatProtection": { "description": "此请求的[威胁防护](https://docs.firecrawl.dev/features/threat-protection)按请求覆盖配置。你提供的字段仅会替换此次请求中你所在组织策略的对应字段；未提供的字段则保留组织级配置值。你的团队必须已启用威胁防护（企业版功能），否则该请求会因 403 被拒绝。如果你的组织已禁用请求级覆盖，任何包含此对象的请求都会因 403 被拒绝。如果你的团队强制启用了威胁防护，则不得将 `mode` 设为 `off`。", "properties": { "blacklist": { "description": "始终封禁的域名，可使用普通域名（`example.com`）或通配符模式（`*.example.com`）。不包含协议、路径或端口。", "items": { "type": "string" }, "maxItems": 1000, "type": "array" }, "blockedTlds": { "description": "直接封禁的顶级域名，使用不带前导点的小写形式（例如 `zip`）。", "items": { "type": "string" }, "maxItems": 1000, "type": "array" }, "failurePolicy": { "description": "当无法访问 classifier 时的处理方式：`closed` 会封禁该请求，`open` 则允许该请求。", "enum": [ "open", "closed" ], "type": "string" }, "mode": { "description": "此次请求的 URL 扫描模式。`normal` 使用 Google Web Risk 检查 URL（每扫描 1 个 URL 额外消耗 2 个额度）。", "enum": [ "off", "normal" ], "type": "string" }, "riskScoreThreshold": { "description": "归一化风险评分（0–100）阈值。达到或超过该值时，分类器判定会封禁该 URL。值越低，限制越严格。", "example": 75, "maximum": 100, "minimum": 0, "type": "integer" }, "whitelist": { "description": "始终允许的域名，可使用普通域名或通配符模式。优先级高于其他所有规则。", "items": { "type": "string" }, "maxItems": 1000, "type": "array" } }, "title": "Threat Protection Override", "type": "object" }, "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" }, "type": { "enum": [ "crawl" ], "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "type", "url" ], "title": "Crawl target", "type": "object" }, { "description": "每次检查时运行网页搜索查询，并对符合监控目标的新结果发出告警。除非 `judgeEnabled` 为 `false`，否则监控顶层的 `goal` 必须为非空。", "properties": { "excludeDomains": { "description": "可选。排除来自这些域名的结果。", "items": { "type": "string" }, "maxItems": 50, "type": "array" }, "id": { "description": "此目标的可选稳定 ID。如省略则会自动生成。", "format": "uuid", "type": "string" }, "includeDomains": { "description": "可选。将结果限制在这些域名内。", "items": { "type": "string" }, "maxItems": 50, "type": "array" }, "maxResults": { "default": 10, "description": "每次检查要评估的结果总数，会在所有查询间合并并去重（这是总上限，不是每个查询各自的上限）。", "maximum": 50, "minimum": 1, "type": "integer" }, "queries": { "description": "每次检查要运行的搜索查询（1–12 个）。", "items": { "maxLength": 256, "minLength": 1, "type": "string" }, "maxItems": 12, "minItems": 1, "type": "array" }, "searchWindow": { "default": "24h", "description": "时效性筛选——仅考虑在此时间窗口内发布的结果。", "enum": [ "5m", "15m", "1h", "6h", "24h", "7d" ], "type": "string" }, "type": { "enum": [ "search" ], "type": "string" } }, "required": [ "type", "queries" ], "title": "Search target", "type": "object" } ] }, "maxItems": 50, "minItems": 1, "type": "array" }, "webhook": { "description": "用于接收监控页面事件和检查完成事件的 Webhook 目标地址。", "properties": { "events": { "description": "要接收的监控 Webhook 事件。默认接收所有监控事件。", "items": { "enum": [ "monitor.page", "monitor.check.completed" ], "type": "string" }, "type": "array" }, "headers": { "additionalProperties": { "type": "string" }, "description": "发送到 Webhook URL 的请求头。", "type": "object" }, "metadata": { "additionalProperties": true, "description": "包含在 Webhook payload 中的自定义元数据。", "type": "object" }, "url": { "description": "用于接收监控 Webhook 的 URL。", "format": "uri", "type": "string" } }, "required": [ "url" ], "type": "object" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "createdAt": { "format": "date-time", "type": "string" }, "currentCheckId": { "format": "uuid", "nullable": true, "type": "string" }, "estimatedCreditsPerMonth": { "description": "每月额度预估上限。启用判断后，实际用量可能更低，因为判断额度仅对已变更且需要判断的页面计费。", "nullable": true, "type": "integer" }, "goal": { "nullable": true, "type": "string" }, "id": { "format": "uuid", "type": "string" }, "judgeEnabled": { "type": "boolean" }, "lastCheckSummary": { "properties": { "changed": { "type": "integer" }, "error": { "type": "integer" }, "new": { "type": "integer" }, "removed": { "type": "integer" }, "same": { "type": "integer" }, "totalPages": { "type": "integer" } }, "type": "object" }, "lastRunAt": { "format": "date-time", "nullable": true, "type": "string" }, "name": { "type": "string" }, "nextRunAt": { "format": "date-time", "nullable": true, "type": "string" }, "notification": { "properties": { "email": { "properties": { "enabled": { "default": false, "type": "boolean" }, "includeDiffs": { "default": false, "description": "在电子邮件摘要中包含已变更页面的详细信息。", "type": "boolean" }, "recipients": { "items": { "format": "email", "type": "string" }, "maxItems": 25, "type": "array" } }, "type": "object" } }, "type": "object" }, "retentionDays": { "type": "integer" }, "schedule": { "properties": { "cron": { "type": "string" }, "timezone": { "type": "string" } }, "type": "object" }, "status": { "enum": [ "active", "paused", "deleted" ], "type": "string" }, "targets": { "items": { "oneOf": [ { "properties": { "id": { "description": "此目标的可选稳定 ID。若省略则会自动生成。", "format": "uuid", "type": "string" }, "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" }, "auditMetadata": { "additionalProperties": false, "description": "为组织启用 SIEM Logging 后，SIEM 日志事件中会包含用户归属信息。", "properties": { "username": { "description": "与该请求关联的用户名。", "maxLength": 1024, "type": "string" } }, "required": [ "username" ], "type": "object" }, "blockAds": { "default": true, "description": "启用广告拦截和 Cookie 弹窗拦截功能。", "type": "boolean" }, "excludeTags": { "description": "在输出中需要排除的标签。", "items": { "type": "string" }, "type": "array" }, "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" }, "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": "<[\n {\n \"key\": \"0\",\n \"translation\": \"设置后，请求将仅检查缓存，不会触发新的抓取。该值以毫秒为单位，指定缓存数据必须满足的最小存在时长。如果存在匹配的缓存数据，将立即返回。若未找到缓存数据，则返回 404，错误代码为 SCRAPE_NO_CACHED_DATA。将其设为 1 可接受任意缓存数据，不受时长限制。\"\n }\n]", "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": "指定要使用的代理类型。\n\n - **basic**：用于抓取几乎没有或只有基础反爬策略的网站的代理。速度快，通常可用。\n - **enhanced**：用于抓取具有高级反爬策略的网站的增强型代理。速度较慢，但在某些站点上更可靠。每个请求最多消耗 5 点积分。\n - **auto**：当 basic 代理抓取失败时，Firecrawl 会自动重试并切换为 enhanced 代理。如果使用 enhanced 重试成功，该次抓取将收取 5 点积分；如果使用 basic 一次就成功，则只按常规定价计费。", "enum": [ "basic", "enhanced", "auto" ], "type": "string" }, "redactPII": { "default": false, "description": "对返回的 markdown 中的个人身份识别信息进行脱敏。传入 `true` 可使用默认值，或传入一个对象来自定义模式、实体和替换样式。", "oneOf": [ { "type": "boolean" }, { "additionalProperties": false, "description": "PII 脱敏的配置选项。", "properties": { "entities": { "description": "将脱敏限制为这些实体类别。如果省略，则会对所有支持的实体进行脱敏。", "items": { "description": "Firecrawl 脱敏支持的公开 PII 实体类别。", "enum": [ "PERSON", "EMAIL", "PHONE", "LOCATION", "FINANCIAL", "SECRET" ], "type": "string" }, "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" } ] }, "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" }, "threatProtection": { "description": "此请求的[威胁防护](https://docs.firecrawl.dev/features/threat-protection)按请求覆盖配置。你提供的字段仅会替换此次请求中你所在组织策略的对应字段；未提供的字段则保留组织级配置值。你的团队必须已启用威胁防护（企业版功能），否则该请求会因 403 被拒绝。如果你的组织已禁用请求级覆盖，任何包含此对象的请求都会因 403 被拒绝。如果你的团队强制启用了威胁防护，则不得将 `mode` 设为 `off`。", "properties": { "blacklist": { "description": "始终封禁的域名，可使用普通域名（`example.com`）或通配符模式（`*.example.com`）。不包含协议、路径或端口。", "items": { "type": "string" }, "maxItems": 1000, "type": "array" }, "blockedTlds": { "description": "直接封禁的顶级域名，使用不带前导点的小写形式（例如 `zip`）。", "items": { "type": "string" }, "maxItems": 1000, "type": "array" }, "failurePolicy": { "description": "当无法访问 classifier 时的处理方式：`closed` 会封禁该请求，`open` 则允许该请求。", "enum": [ "open", "closed" ], "type": "string" }, "mode": { "description": "此次请求的 URL 扫描模式。`normal` 使用 Google Web Risk 检查 URL（每扫描 1 个 URL 额外消耗 2 个额度）。", "enum": [ "off", "normal" ], "type": "string" }, "riskScoreThreshold": { "description": "归一化风险评分（0–100）阈值。达到或超过该值时，分类器判定会封禁该 URL。值越低，限制越严格。", "example": 75, "maximum": 100, "minimum": 0, "type": "integer" }, "whitelist": { "description": "始终允许的域名，可使用普通域名或通配符模式。优先级高于其他所有规则。", "items": { "type": "string" }, "maxItems": 1000, "type": "array" } }, "title": "Threat Protection Override", "type": "object" }, "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" }, "type": { "enum": [ "scrape" ], "type": "string" }, "urls": { "items": { "format": "uri", "type": "string" }, "minItems": 1, "type": "array" } }, "required": [ "type", "urls" ], "title": "Scrape target", "type": "object" }, { "properties": { "crawlOptions": { "description": "爬取选项，例如 `limit`、`maxDepth`、`includePaths` 和 `excludePaths`。", "type": "object" }, "id": { "description": "此目标的可选稳定 ID。若省略则会自动生成。", "format": "uuid", "type": "string" }, "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" }, "auditMetadata": { "additionalProperties": false, "description": "为组织启用 SIEM Logging 后，SIEM 日志事件中会包含用户归属信息。", "properties": { "username": { "description": "与该请求关联的用户名。", "maxLength": 1024, "type": "string" } }, "required": [ "username" ], "type": "object" }, "blockAds": { "default": true, "description": "启用广告拦截和 Cookie 弹窗拦截功能。", "type": "boolean" }, "excludeTags": { "description": "在输出中需要排除的标签。", "items": { "type": "string" }, "type": "array" }, "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" }, "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": "<[\n {\n \"key\": \"0\",\n \"translation\": \"设置后，请求将仅检查缓存，不会触发新的抓取。该值以毫秒为单位，指定缓存数据必须满足的最小存在时长。如果存在匹配的缓存数据，将立即返回。若未找到缓存数据，则返回 404，错误代码为 SCRAPE_NO_CACHED_DATA。将其设为 1 可接受任意缓存数据，不受时长限制。\"\n }\n]", "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": "指定要使用的代理类型。\n\n - **basic**：用于抓取几乎没有或只有基础反爬策略的网站的代理。速度快，通常可用。\n - **enhanced**：用于抓取具有高级反爬策略的网站的增强型代理。速度较慢，但在某些站点上更可靠。每个请求最多消耗 5 点积分。\n - **auto**：当 basic 代理抓取失败时，Firecrawl 会自动重试并切换为 enhanced 代理。如果使用 enhanced 重试成功，该次抓取将收取 5 点积分；如果使用 basic 一次就成功，则只按常规定价计费。", "enum": [ "basic", "enhanced", "auto" ], "type": "string" }, "redactPII": { "default": false, "description": "对返回的 markdown 中的个人身份识别信息进行脱敏。传入 `true` 可使用默认值，或传入一个对象来自定义模式、实体和替换样式。", "oneOf": [ { "type": "boolean" }, { "additionalProperties": false, "description": "PII 脱敏的配置选项。", "properties": { "entities": { "description": "将脱敏限制为这些实体类别。如果省略，则会对所有支持的实体进行脱敏。", "items": { "description": "Firecrawl 脱敏支持的公开 PII 实体类别。", "enum": [ "PERSON", "EMAIL", "PHONE", "LOCATION", "FINANCIAL", "SECRET" ], "type": "string" }, "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" } ] }, "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" }, "threatProtection": { "description": "此请求的[威胁防护](https://docs.firecrawl.dev/features/threat-protection)按请求覆盖配置。你提供的字段仅会替换此次请求中你所在组织策略的对应字段；未提供的字段则保留组织级配置值。你的团队必须已启用威胁防护（企业版功能），否则该请求会因 403 被拒绝。如果你的组织已禁用请求级覆盖，任何包含此对象的请求都会因 403 被拒绝。如果你的团队强制启用了威胁防护，则不得将 `mode` 设为 `off`。", "properties": { "blacklist": { "description": "始终封禁的域名，可使用普通域名（`example.com`）或通配符模式（`*.example.com`）。不包含协议、路径或端口。", "items": { "type": "string" }, "maxItems": 1000, "type": "array" }, "blockedTlds": { "description": "直接封禁的顶级域名，使用不带前导点的小写形式（例如 `zip`）。", "items": { "type": "string" }, "maxItems": 1000, "type": "array" }, "failurePolicy": { "description": "当无法访问 classifier 时的处理方式：`closed` 会封禁该请求，`open` 则允许该请求。", "enum": [ "open", "closed" ], "type": "string" }, "mode": { "description": "此次请求的 URL 扫描模式。`normal` 使用 Google Web Risk 检查 URL（每扫描 1 个 URL 额外消耗 2 个额度）。", "enum": [ "off", "normal" ], "type": "string" }, "riskScoreThreshold": { "description": "归一化风险评分（0–100）阈值。达到或超过该值时，分类器判定会封禁该 URL。值越低，限制越严格。", "example": 75, "maximum": 100, "minimum": 0, "type": "integer" }, "whitelist": { "description": "始终允许的域名，可使用普通域名或通配符模式。优先级高于其他所有规则。", "items": { "type": "string" }, "maxItems": 1000, "type": "array" } }, "title": "Threat Protection Override", "type": "object" }, "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" }, "type": { "enum": [ "crawl" ], "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "type", "url" ], "title": "Crawl target", "type": "object" }, { "description": "每次检查时运行网页搜索查询，并对符合监控目标的新结果发出告警。除非 `judgeEnabled` 为 `false`，否则监控顶层的 `goal` 必须为非空。", "properties": { "excludeDomains": { "description": "可选。排除来自这些域名的结果。", "items": { "type": "string" }, "maxItems": 50, "type": "array" }, "id": { "description": "此目标的可选稳定 ID。如省略则会自动生成。", "format": "uuid", "type": "string" }, "includeDomains": { "description": "可选。将结果限制在这些域名内。", "items": { "type": "string" }, "maxItems": 50, "type": "array" }, "maxResults": { "default": 10, "description": "每次检查要评估的结果总数，会在所有查询间合并并去重（这是总上限，不是每个查询各自的上限）。", "maximum": 50, "minimum": 1, "type": "integer" }, "queries": { "description": "每次检查要运行的搜索查询（1–12 个）。", "items": { "maxLength": 256, "minLength": 1, "type": "string" }, "maxItems": 12, "minItems": 1, "type": "array" }, "searchWindow": { "default": "24h", "description": "时效性筛选——仅考虑在此时间窗口内发布的结果。", "enum": [ "5m", "15m", "1h", "6h", "24h", "7d" ], "type": "string" }, "type": { "enum": [ "search" ], "type": "string" } }, "required": [ "type", "queries" ], "title": "Search target", "type": "object" } ] }, "type": "array" }, "updatedAt": { "format": "date-time", "type": "string" }, "webhook": { "description": "用于接收监控页面事件和检查完成事件的 Webhook 目标地址。", "properties": { "events": { "description": "要接收的监控 Webhook 事件。默认接收所有监控事件。", "items": { "enum": [ "monitor.page", "monitor.check.completed" ], "type": "string" }, "type": "array" }, "headers": { "additionalProperties": { "type": "string" }, "description": "发送到 Webhook URL 的请求头。", "type": "object" }, "metadata": { "additionalProperties": true, "description": "包含在 Webhook payload 中的自定义元数据。", "type": "object" }, "url": { "description": "用于接收监控 Webhook 的 URL。", "format": "uri", "type": "string" } }, "required": [ "url" ], "type": "object" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "监控已更新" }, "404": { "description": "未找到监控" } } } ```