Firecrawl（全球，搜索与网页抓取）

平台提供三个 Firecrawl 端点：Search 拿搜索结果、Map 发现站点 URL 结构、Scrape 抓取单页正文。三者互相独立，可以单独调用，也可以串起来用（Map 找页面 → Scrape 取正文 → 喂给 LLM）。

官方文档：Firecrawl API Reference ↗

通用约定

三个端点都是 POST + JSON body，只需要 Authorization: Bearer $TURING_API_KEY 一个头。
每个端点只接受下面表格列出的字段，出现表外字段会直接返回 422，请求不会发出。嵌套对象同样如此：categories[]、location 里出现未列出的键也会被拒绝。
字段名推荐用 camelCase（includeDomains、onlyMainContent、redactPII）；对应的 snake_case 写法（include_domains、only_main_content、redact_pii）同样接受。但大小写必须精确匹配这两种写法之一——ignoreInvalidURLs 的 URL 是三个大写字母，写成 ignoreInvalidUrls 会被当成表外字段拒绝。
location 在 Search 里是字符串，在 Map / Scrape 里是对象，两者不通用。
所有 url / 域名必须是公网 http(s) 地址：不接受 localhost、*.local、*.internal、私网 IP、非规范 IP 写法（如 0x7f.1），也不接受带账号密码的 URL；域名类字段要填 host，带 https:// 会被拒绝。
所有 timeout 单位是毫秒。平台读超时会在你设置的值上再加 5 秒缓冲。
响应中值为 null 的字段不会出现在返回里。

Search

端点：POST /proxy/firecrawl/search
必填参数：query

参数	类型 / 默认值	说明
`query`	string，必填	查询词，1–500 字符，前后空白会被去掉，不能为空
`limit`	int，默认 `10`	返回结果数，1–100
`sources`	string[]	取值 `web` / `images` / `news`，1–3 项
`categories`	object[]	元素形如 `{"type": "github"}`，`type` 取值 `github` / `research` / `pdf`，最多 3 项。注意是对象数组，直接写 `["github"]` 会被拒绝
`includeDomains`	string[]	只保留这些域名的结果，1–20 项，填 host（不带协议、路径），不允许重复
`excludeDomains`	string[]	排除这些域名，规则同上。不能和 `includeDomains` 同时使用
`tbs`	string	Google 时间过滤串，≤100 字符
`location`	string	检索地区提示，≤200 字符
`country`	string，默认 `US`	两位大写国家码，小写会被自动转成大写
`timeout`	int，默认 `60000`	1000–60000 毫秒
`ignoreInvalidURLs`	bool，默认 `false`	忽略无效 URL 而不是整体失败
`highlights`	bool，默认 `true`	是否返回命中片段

备注

搜索结果只给链接和摘要，不带网页正文。需要正文时，拿到 URL 后再调 Scrape。

curl $TURING_BASE_URL/proxy/firecrawl/search \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Firecrawl API",
    "limit": 5,
    "sources": ["web"],
    "includeDomains": ["docs.firecrawl.dev"]
  }'

响应节选：

{
  "success": true,
  "data": {
    "web": [
      {
        "url": "https://docs.firecrawl.dev",
        "position": 1
      }
    ]
  },
  "creditsUsed": 2
}

顶层返回 success、data，可能还带 creditsUsed（本次消耗的 credit 数）、warning、id。data 按 sources 分组（web / images / news），每组是一个数组，组内条目原样返回。

Map

只发现站点有哪些 URL，不抓正文，适合先摸清站点结构、再挑页面调 Scrape。

端点：POST /proxy/firecrawl/map
必填参数：url

参数	类型 / 默认值	说明
`url`	string，必填	起始 URL，≤2048 字符
`search`	string	按关键词筛选发现到的 URL，1–200 字符
`sitemap`	默认 `include`	`include` 用 sitemap 并补充爬取、`only` 只用 sitemap、`skip` 不用 sitemap
`includeSubdomains`	bool，默认 `false`	是否包含子域名
`ignoreQueryParameters`	bool，默认 `true`	把只有 query 参数不同的 URL 视为同一个
`ignoreCache`	bool，默认 `false`	跳过缓存重新发现
`limit`	int，默认 `1000`	返回 URL 数上限，1–5000
`timeout`	int，默认 `60000`	1000–60000 毫秒
`location`	object	`{"country": "GB", "languages": ["en-GB"]}`，`country` 两位国家码，`languages` 1–10 项、每项 ≤35 字符

curl $TURING_BASE_URL/proxy/firecrawl/map \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://docs.firecrawl.dev",
    "search": "api",
    "limit": 100
  }'

响应节选：

{
  "success": true,
  "links": [
    {
      "url": "https://docs.firecrawl.dev/api-reference/introduction",
      "title": "Introduction",
      "description": "Firecrawl API reference"
    }
  ]
}

备注

links 里每个条目固定为 url / title / description 三个字段，其中 url 一定存在，另外两个可能缺省。

Scrape

抓取单个 URL 的正文。需要抓多页时，先用 Map 拿到 URL 列表，再逐个调用。

端点：POST /proxy/firecrawl/scrape
必填参数：url

参数	类型 / 默认值	说明
`url`	string，必填	目标 URL，≤2048 字符
`formats`	string[]，默认 `["markdown"]`	取值 `markdown` / `summary` / `html` / `rawHtml` / `links`，1–5 项且不可重复
`onlyMainContent`	bool，默认 `true`	只保留正文，去掉导航页脚
`onlyCleanContent`	bool，默认 `false`	进一步清理噪声内容
`includeTags`	string[]	只保留这些 HTML 标签 / 选择器，1–50 项，每项 ≤128 字符，不可重复
`excludeTags`	string[]	排除这些标签 / 选择器，规则同上
`maxAge`	int，默认 `172800000`（48 小时）	可接受的缓存年龄上限，`0` 表示强制重新抓取
`minAge`	int，≥1	可接受的缓存年龄下限
`headers`	object	自定义请求头，如 `{"Cookie": "session=..."}`
`waitFor`	int，默认 `0`	页面渲染等待毫秒数，0–5000
`mobile`	bool，默认 `false`	用移动端 UA / 视口抓取
`skipTlsVerification`	bool，默认 `false`	跳过证书校验，仅在目标站点证书确有问题时开启
`timeout`	int，默认 `60000`	1000–295000 毫秒（比 Search / Map 宽松）
`location`	object	同 Map
`blockAds`	bool，默认 `true`	拦截广告
`storeInCache`	bool，默认 `true`	是否把本次结果写入缓存
`redactPII`	bool 或 object，默认 `false`	传 `true` 用默认策略；传对象可指定 `mode`（`accurate` / `aggressive` / `fast`）、`entities`（`PERSON` / `EMAIL` / `PHONE` / `LOCATION` / `FINANCIAL` / `SECRET`）、`replaceStyle`（`tag` / `mask` / `remove`）

取值固定的字段

下面三个字段的取值是固定的。可以显式传，但只能传这个值，传别的值返回 422：

字段	只接受	影响
`parsers`	`[]`	不做 PDF 分页解析。抓 PDF 时当作一个整体文件处理，也因此按 1 credit 计费
`removeBase64Images`	`true`	内联 base64 图片一律剔除，避免响应体膨胀
`proxy`	`"basic"`	使用基础代理

curl $TURING_BASE_URL/proxy/firecrawl/scrape \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://docs.firecrawl.dev",
    "formats": ["markdown", "links"],
    "onlyMainContent": true
  }'

响应节选：

{
  "success": true,
  "data": {
    "markdown": "# Firecrawl Docs\n...",
    "links": ["https://docs.firecrawl.dev/api-reference/introduction"],
    "metadata": {
      "contentType": "text/html; charset=utf-8"
    }
  }
}

data 里的键与请求的 formats 对应：markdown / summary / html / rawHtml / links 各对应一个键，此外还可能带 metadata（页面元信息）。data 的内容原样返回。

计费

按 Firecrawl credit 计价，单价 $0.00099。失败的请求——参数校验不通过、上游报错、响应无效——都不计费。

端点	credit 消耗
Search	以响应里的 `creditsUsed` 为准；没有该字段时按 `ceil(结果总数 / 10) × 2` 估算（结果总数是各来源分组条目数之和）
Map	每次成功调用 1 credit，与返回多少链接无关（返回空数组也计 1）
Scrape	每次成功调用 1 credit，HTML 页面和 PDF 同价

限流与错误

限流：Search / Map / Scrape 各自独立计数，默认每个端点 480 次 / 小时（企业客户额度另行核定）。配额与限流在请求发出之前校验，超限不消耗 Firecrawl 额度。
422：请求体没通过字段或取值校验，请求未发出。
429（错误码 3091）：触发上游限流。
502（错误码 3090）：上游报错、响应格式非法，或响应体超过 10 MB。返回统一的错误信息，不透传上游的原始错误内容；排查请带上 X-Turing-Trace-Id。

错误码含义见错误码参考，限流策略见速率限制。

通用约定​

Search​

Map​

Scrape​

取值固定的字段​

计费​

通用约定

Search

Map

Scrape

取值固定的字段

计费