> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pioneer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 如何使用 Pioneer API 对请求进行身份验证

> 从 Pioneer 账户生成 API 密钥,然后在每个请求的 X-API-Key 头中包含该密钥。无需 OAuth 或令牌刷新。

Pioneer API 的每个请求都必须包含 API 密钥。Pioneer 使用一种简单的基于请求头的身份验证方案:将您的密钥放入 `X-API-Key` 头中即可开始使用。无需刷新令牌或管理 OAuth 流程。

## 生成 API 密钥

1. 登录 [pioneer.ai](https://pioneer.ai)。
2. 前往 **Settings → API Keys**。
3. 点击 **Create key**,为其命名,并复制密钥值。

<Warning>
  您只能在创建后立即查看完整密钥。Pioneer 不会存储密钥值,因此请在关闭对话框前复制它。如果丢失密钥,请撤销并重新生成一个。
</Warning>

## 在请求中传递密钥

在每个请求的 `X-API-Key` 头中包含您的 API 密钥。以下示例展示了使用 curl、Python 和 JavaScript 发起相同推理调用的方法。

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.pioneer.ai/inference \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model_id": "fastino/gliner2-base-v1",
      "text": "Apple launched the iPhone in San Francisco.",
      "schema": {"entities": ["organization", "product", "location"]}
    }'
  ```

  ```python Python theme={null}
  import requests

  headers = {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  response = requests.post(
      "https://api.pioneer.ai/inference",
      headers=headers,
      json={
          "model_id": "fastino/gliner2-base-v1",
          "text": "Apple launched the iPhone in San Francisco.",
          "schema": {"entities": ["organization", "product", "location"]}
      }
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.pioneer.ai/inference", {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model_id: "fastino/gliner2-base-v1",
      text: "Apple launched the iPhone in San Francisco.",
      schema: { entities: ["organization", "product", "location"] }
    })
  });
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

<Tip>
  请将 API 密钥存储在环境变量中(例如 `PIONEER_API_KEY`),而不是硬编码在源代码里。切勿将 API 密钥提交到版本控制系统。将 `.env` 文件加入 `.gitignore`,并在生产环境中使用密钥管理服务。
</Tip>

## 身份验证错误

| 状态码                    | 含义                                             |
| ---------------------- | ---------------------------------------------- |
| `401 Unauthorized`     | 缺少 `X-API-Key` 头或密钥无效。请检查是否发送了该请求头,以及密钥是否已被撤销。 |
| `402 Payment Required` | 您的账户积分不足。请升级套餐或前往 **Settings → Billing** 添加积分。 |

其他所有错误代码都记录在 [API 参考错误页面](/cn/api-reference/errors)中。

## 通过 API 管理现有 API 密钥

请从 Pioneer 控制面板的 **Settings -> API Keys** 中创建新的 API 密钥。出于安全考虑,使用 API 密钥进行身份验证的请求不能创建其他 API 密钥;`POST /create-api-key` 仅限控制面板会话使用,当通过 `X-API-Key` 调用时将返回 `403 Forbidden`。

您可以使用现有密钥以编程方式列出和撤销现有密钥。

**列出现有密钥**

```bash theme={null}
curl https://api.pioneer.ai/list-api-keys \
  -H "X-API-Key: YOUR_API_KEY"
```

**撤销密钥**

```bash theme={null}
curl -X DELETE https://api.pioneer.ai/delete-api-key \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key_id": "key_id_to_revoke"}'
```

<Note>
  撤销是即时且永久的。使用被撤销密钥的任何请求都会收到 `401` 错误。如果需要不中断的访问,请在撤销现有密钥前先创建替换密钥。
</Note>

## 安全建议

<Warning>
  定期轮换 API 密钥,尤其是在共享环境或 CI/CD 流水线中使用时。为每个集成使用单独的密钥,这样您就可以撤销单个密钥,而不会影响其他服务。
</Warning>

* 为每个环境(开发、预发布、生产)使用一个密钥。
* 如果怀疑密钥已泄露,请立即撤销。
* 避免将密钥作为查询参数传递。始终使用 `X-API-Key` 头。
* 在生产环境中,请从密钥管理服务中获取密钥,而不是从烘焙进容器镜像的环境变量中读取。