Firecrawl for Platforms

概述

借助 Firecrawl for Platforms，你的平台可以直接在自己的后端为用户创建和管理 Firecrawl API 密钥。用户无需离开你的平台即可开始使用 Firecrawl。

你可以在 Firecrawl 控制台中自行设置 Firecrawl for Platforms。组织中的任何管理员或成员都可以创建集成：为其命名、选择集成类型、接受该类型对应的协议，然后复制平台密钥。该密钥仅显示一次。之后你可以在 Settings 中生成和撤销密钥。无需提交申请，也无需等待审批。

集成分为两种类型。两者开通账户的方式相同，都是使用同一个平台密钥调用下方的接口；区别在于由谁为用户的使用量付费：

标准版：由你的用户向 Firecrawl 付费。每个开通的账户各自保留 Firecrawl 方案和计费，并直接在 Firecrawl 升级。新账户的初始额度请参见开通账户的额度。
Gateway：由你的组织为用户买单。通过你的集成创建的账户会加入 Gateway，其符合条件的使用量将计入你的组织账单。请参见下方的 Gateway。

集成类型需在创建集成时选定，之后不易更改，因此建议在接受协议前仔细比较这两种类型。概览请参见 Firecrawl for Platforms 页面。部分合作伙伴优惠会为开通的用户提供促销额度；如有，请参见 Partner Credits 了解用户可获得的具体内容。

Gateway

Gateway 是一种集成类型，而非独立的 API，使用的平台密钥和接口均保持不变。Gateway 集成的不同之处如下：

账户专为你的集成创建，仅支持 API 访问，不提供独立的 Dashboard 登录。即使邮箱与某个现有 Firecrawl 账户相同，请求也不会关联到该账户。
符合条件的用量将计入你的组织账单。关于何时优先消耗用户自己的额度，请参见已开通账户的额度。
POST /partner/v1/accounts 的响应中包含 gatewayStatus 字段。
集成在创建时即接受 Gateway 版本的协议。

基础 URL

https://integrations.firecrawl.dev

身份验证

所有 Platforms API 请求都需要在 Authorization 请求头中携带你的平台密钥：

Authorization: Bearer <platform key>

平台密钥与普通的 Firecrawl API 密钥不同。你可以在 Firecrawl Dashboard 的 Settings > Firecrawl for Platforms 中创建和撤销平台密钥。

安全要求

仅限服务器端：平台密钥只能在服务器端代码中使用。切勿在前端代码、客户端 JavaScript 或移动应用中暴露平台密钥。
服务条款：在调用 POST /partner/v1/accounts 之前，您的平台必须提示用户接受 Firecrawl 的服务条款。

预配账户的额度

除非 Firecrawl 已验证你的平台，或你已与 Firecrawl 签署协议，否则通过你的集成创建的账户不附带免费额度。在此之前：

标准版账户初始不含任何额度。用户可随时在 Firecrawl 控制台中添加支付方式或选择方案。
Gateway 账户消耗的所有额度均由你的组织支付。

平台通过验证后，新账户和现有账户都将获得 Free 方案的每月额度；对于 Gateway 账户，会优先消耗这些额度，用完后再向你的组织计费。验证需由 Firecrawl 人工完成。当你的集成正式上线，或你正在构建生产应用时，请发送邮件至 partnerships@firecrawl.dev，并附上你的集成 ID。

限制

账户创建按集成进行限制，既限制每个集成可创建的账户总数，也限制创建速率。这些限制会随着贵组织与 Firecrawl 合作关系的深入而逐步提高，且不会影响你已创建的账户。对已开通的用户重复调用时，将返回现有账户，且不计入账户数量限制。为标准版账户提交的邮箱地址必须是你的用户能够正常收信的地址。如果你已达到限制，或正在规划生产环境集成，请发送邮件至 partnerships@firecrawl.dev，并附上你的集成 ID 和预期用量。如果你的集成被 Firecrawl 暂停，请发送邮件至 help@firecrawl.com。

接口

创建用户

为你的某个用户 (以电子邮件地址标识) 开通 Firecrawl 账户，并返回该账户的 API 密钥。

POST /partner/v1/accounts

行为

对于 Standard 集成：

如果用户尚无 Firecrawl 账户，将创建新用户和新团队。
如果用户已有 Firecrawl 账户，但尚无与你的集成关联的团队，将创建一个与你的集成关联的新团队。
如果用户已有 Firecrawl 账户，且已有与你的集成关联的团队，则返回现有团队。

对于 Gateway 集成：

所有账户均专为你的集成创建。请求绝不会关联到已有的 Firecrawl 账户，即使电子邮件地址与某个现有账户相同也是如此。电子邮件地址仅作为账户的联系地址存储，不会用于查找账户。
使用同一电子邮件地址重复调用时，将返回同一个账户及其 API 密钥。

如果你的集成包含促销额度，这些额度仅在首次创建账户时发放一次。

请求

cURL

curl -X POST "https://integrations.firecrawl.dev/partner/v1/accounts" \
  -H "Authorization: Bearer <platform key>" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

请求体

字段	类型	必填	描述
`email`	string	是	用户的电子邮件地址。对于 Gateway 集成，该地址会存储为账户的联系地址。

响应

200 OK

{
  "apiKey": "fc-...",
  "alreadyExisted": false
}

对于 Gateway 集成，响应中还会包含注册状态：

{
  "apiKey": "fc-...",
  "alreadyExisted": false,
  "gatewayStatus": "enrolled"
}

字段	类型	描述
`apiKey`	string	你的集成为该用户开通的团队对应的 Firecrawl API 密钥
`alreadyExisted`	boolean	若你的集成此前已为该邮箱开通过账户，则为 `true`。该字段并不反映该邮箱是否已存在于 Firecrawl 的其他位置。
`gatewayStatus`	string	仅适用于 Gateway 集成。创建账户的那次调用返回 `enrolled`，之后针对同一邮箱的重复调用返回 `already_enrolled`。

错误

状态	描述
`400`	请求错误 - `email` 缺失或格式不正确
`401`	未授权 - 平台密钥错误或无效
`403`	请求被拒绝 - 响应体中的 `error.code` 会说明原因：`partner_account_cap_reached` (该集成的账户数量已达上限) 、`partner_provisioning_email_rejected` (该电子邮件地址无法用于注册 Firecrawl 账户) 或 `partner_integration_suspended`。请参见限制
`429`	请求过多 - `rate_limit_exceeded`；请降低请求频率后重试
`502`	Firecrawl 在创建账户时无法连接其计费提供商 - 请重试该请求
`503`	Firecrawl 无法检查限流状态 - 请稍后重试
`500`	内部服务器错误 - Firecrawl 会监控此类错误

验证 API 密钥

验证 Firecrawl API 密钥，并返回其关联的团队名称和用户电子邮件地址。仅当 API 密钥是通过您的集成创建时，才会返回有效结果。

POST /partner/v1/api-keys/validate

重要说明

Firecrawl API 密钥不设权限，也没有过期时间。
用户可以随时手动删除 API 密钥。
删除 API 密钥并非软删除。Firecrawl 无法区分已删除的密钥与从未存在过的密钥。

请求

cURL

curl -X POST "https://integrations.firecrawl.dev/partner/v1/api-keys/validate" \
  -H "Authorization: Bearer <platform key>" \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "fc-..."}'

请求体

字段	类型	必填	描述
`apiKey`	string	是	待验证的 API 密钥

响应

200 OK

{
  "teamName": "Example Team",
  "email": "user@example.com"
}

字段	类型	描述
`teamName`	string	与此 API 密钥关联的团队名称
`email`	string	开通该账户时使用的邮箱。对于 Gateway 账户，该值为您提供的联系邮箱。

错误

状态	描述
`400`	请求错误 - API 密钥格式不正确
`401`	未授权 - 平台密钥不正确或无效
`404`	无法识别 API 密钥 - 该密钥不存在，或并非通过您的集成创建
`500`	内部服务器错误 - Firecrawl 会监控此类错误

轮换 API 密钥

删除现有的 Firecrawl API 密钥，并为同一用户和团队创建新的密钥。

POST /partner/v1/api-keys/rotate

请求

cURL

curl -X POST "https://integrations.firecrawl.dev/partner/v1/api-keys/rotate" \
  -H "Authorization: Bearer <platform key>" \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "fc-..."}'

请求体

字段	类型	必填	描述
`apiKey`	string	是	要删除并替换的 API 密钥

响应

200 OK

{
  "apiKey": "fc-..."
}

字段	类型	描述
`apiKey`	string	新创建的 API 密钥

错误

状态	描述
`401`	未授权 - 平台密钥不正确或无效
`404`	无法识别 API 密钥 - 该密钥不存在，或并非通过你的集成创建
`500`	内部服务器错误 - Firecrawl 会监控此类错误

快速开始

在 Firecrawl Dashboard 中创建您的集成：登录后选择 Standard 或 Gateway，接受协议，然后复制您的平台密钥。集成类型创建后不便更改，请在接受协议前确认您的选择。随后，从您的服务器调用上述接口即可。对配置方式有疑问？请发送邮件至 help@firecrawl.com。如有更大规模的集成计划，请发送邮件至 partnerships@firecrawl.dev。

合作伙伴计划

为用户开通 Firecrawl 账户的平台可以申请加入 Firecrawl 合作伙伴计划。获批的合作伙伴可享受以下权益：就其引荐用户的付费使用获得收入分成、联合营销并入驻我们的合作伙伴名录、抢先体验新接口、与我们团队直接对接的技术支持渠道，以及为其用户提供更高的限额。该计划采用申请制，我们会在一周内回复。作为回报，合作伙伴需在其产品中展示“Powered by Firecrawl”，并链接到带有其 ?ref=<partner> 标记的 firecrawl.dev。收入分成仅适用于申请获批后您引荐的新付费客户，不追溯生效。分成涵盖每位客户使用自助式方案的第一年；Scale (扩展) 和企业版方案除外。所有合作伙伴均需经过我们团队的审核与批准。申请加入合作伙伴计划如果您撰写有关 Firecrawl 的内容或在内容中链接到 Firecrawl，联盟推广计划会更适合您。

​概述

​Gateway

​基础 URL

​身份验证

​安全要求

​预配账户的额度

​限制

​接口

​创建用户

​行为

​请求

​响应

​错误

​验证 API 密钥

​重要说明

​请求

​响应

​错误

​轮换 API 密钥

​请求

​响应

​错误

​快速开始

​合作伙伴计划

概述

Gateway

基础 URL

身份验证

安全要求

预配账户的额度

限制

接口

创建用户

行为

请求

响应

错误

验证 API 密钥

重要说明

请求

响应

错误

轮换 API 密钥

请求

响应

错误

快速开始

合作伙伴计划