> ## 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 for Platforms

> API 参考：供平台为其用户创建和管理 Firecrawl API 密钥

## 概述

借助 Firecrawl for Platforms，你的平台可以直接在自己的后端为用户创建和管理 Firecrawl API 密钥。这样，你的用户无需离开你的平台，即可通过 Firecrawl (面向 AI 智能体的上下文 API) 搜索、抓取网页并与网页交互。

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

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

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

集成类型需在创建集成时选定，之后不易更改，因此建议在接受协议前仔细比较这两种类型。概览请参见 [Firecrawl for Platforms 页面](https://www.firecrawl.dev/firecrawl-for-platforms)。

部分合作伙伴优惠会为开通的用户提供促销额度；如有，请参见 [Partner Credits](https://docs.firecrawl.dev/zh/partner-credits.md) 了解用户可获得的具体内容。

### Gateway

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

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

## 基础 URL

```
https://integrations.firecrawl.dev
```

## 身份验证

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

```bash theme={null}
Authorization: Bearer <platform key>
```

平台密钥与普通的 Firecrawl API 密钥不同。你可以在 [Firecrawl Dashboard](https://www.firecrawl.dev/app/partner-api) 的 Settings > Firecrawl for Platforms 中创建和撤销平台密钥。

## 安全要求

* **仅限服务器端**：平台密钥只能在服务器端代码中使用。切勿在前端代码、客户端 JavaScript 或移动应用中暴露平台密钥。
* **服务条款**：在调用 `POST /partner/v1/accounts` 之前，您的平台必须提示用户接受 Firecrawl 的[服务条款](https://www.firecrawl.dev/terms-of-service)。

## 预配账户的额度

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

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

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

## 限制

账户创建按集成进行限制，既限制每个集成可创建的账户总数，也限制创建速率。这些限制会随着贵组织与 Firecrawl 合作关系的深入而逐步提高，且不会影响你已创建的账户。对已开通的用户重复调用时，将返回现有账户，且不计入账户数量限制。为标准版账户提交的邮箱地址必须是你的用户能够正常收信的地址。

如果你已达到限制，或正在规划生产环境集成，请发送邮件至 [partnerships@firecrawl.dev](mailto:partnerships@firecrawl.dev)，并附上你的集成 ID 和预期用量。如果你的集成被 Firecrawl 暂停，请发送邮件至 [help@firecrawl.com](mailto:help@firecrawl.com)。

***

## 接口

### 创建用户

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

```
POST /partner/v1/accounts
```

#### 行为

对于 **Standard** 集成：

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

对于 **Gateway** 集成：

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

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

#### 请求

```bash cURL theme={null}
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`**

```json theme={null}
{
  "apiKey": "fc-...",
  "alreadyExisted": false
}
```

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

```json theme={null}
{
  "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`。请参见[限制](#limits) |
| `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 无法区分已删除的密钥与从未存在过的密钥。

#### 请求

```bash cURL theme={null}
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`**

```json theme={null}
{
  "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
```

#### 请求

```bash cURL theme={null}
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`**

```json theme={null}
{
  "apiKey": "fc-..."
}
```

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

#### 错误

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

***

## 快速开始

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

## 合作伙伴计划

为用户开通 Firecrawl 账户的平台可以申请加入 Firecrawl 合作伙伴计划。获批的合作伙伴可享受以下权益：就其引荐用户的付费使用获得收入分成、联合营销并入驻我们的合作伙伴名录、抢先体验新接口、与我们团队直接对接的技术支持渠道，以及为其用户提供更高的限额。该计划采用申请制，我们会在一周内回复。

作为回报，合作伙伴需在其产品中展示“Powered by Firecrawl”，并链接到带有其 `?ref=<partner>` 标记的 firecrawl.dev。

收入分成仅适用于申请获批后您引荐的新付费客户，不追溯生效。所有合作伙伴均需经过我们团队的审核与批准。

[申请加入合作伙伴计划](https://www.firecrawl.dev/firecrawl-for-platforms/partner-program?source=docs)

如果您撰写有关 Firecrawl 的内容或在内容中链接到 Firecrawl，[联盟推广计划](https://www.firecrawl.dev/affiliates)会更适合您。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.