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

# 认证与 Public API Key

> 正确保存和发送成员级 Public API Key

除生成素材的临时公开地址外，所有开放 API 请求都需要成员级 Public API Key：

```http theme={null}
Authorization: Bearer <PUBLIC_API_KEY>
```

所有 JSON 响应都会携带 `request_id`。成功响应使用统一结构：

```json theme={null}
{
  "code": 200,
  "data": {},
  "request_id": "req_xxx"
}
```

错误响应中的 `error.code` 是 HTTP 状态码，`error.type` 是稳定的错误类别，不会为每个字段错误无限新增枚举：

```json theme={null}
{
  "error": {
    "code": 400,
    "type": "invalid_request_error",
    "message": "请求参数无效",
    "param": "size",
    "details": {"received": "7:5"}
  },
  "request_id": "req_xxx"
}
```

## 密钥归属

* 一把 Public API Key 只绑定一个组织成员，不绑定整个组织。
* 成员可以创建多把 Key，用于区分不同工具或业务系统。
* 调用使用该成员当前分配的上游密钥；更换上游密钥后，现有 Public API Key 自动跟随。
* 成员未分配有效上游密钥时，接口返回 `409 CREDENTIAL_NOT_ASSIGNED`，不会使用组织默认密钥。
* 成员或组织停用、Key 到期或被删除后，调用立即失败。

## 服务端使用

```javascript theme={null}
const response = await fetch('https://api.ch88.cn/v1/open/product-analysis', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LINGGAN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    product_name: '保湿精华液',
    image_urls: ['https://example.com/product.png'],
  }),
});
```

## 安全要求

<Warning>
  不要把 Public API Key 放入浏览器 JavaScript、小程序包、桌面应用安装包、公开 Git 仓库、截图或日志中。无法保证密钥不被提取的客户端，应通过自己的服务端调用灵感 API。
</Warning>

* 使用环境变量或专业密钥管理系统保存密钥。
* 不要在错误日志中记录完整 `Authorization` 请求头。
* 为不同工具创建不同 Key，发生泄露时只删除受影响的 Key。
* 设置合理过期时间，并在到期前完成轮换。
* 完整明文只在创建成功时显示一次，平台无法再次展示原值。

## 认证失败

| HTTP 状态 | 错误码                            | 含义                     |
| ------- | ------------------------------ | ---------------------- |
| `401`   | `PUBLIC_API_KEY_REQUIRED`      | 缺少 Bearer 密钥。          |
| `401`   | `PUBLIC_API_KEY_INVALID`       | 密钥错误、过期或已删除。           |
| `403`   | `PUBLIC_API_KEY_FORBIDDEN`     | 密钥所属成员或组织已停用。          |
| `409`   | `CREDENTIAL_NOT_ASSIGNED`      | 成员未分配有效上游密钥。           |
| `409`   | `CREDENTIAL_DECRYPTION_FAILED` | 已分配的上游密钥暂时不可用，需要管理员处理。 |
| `503`   | `AUTH_UNAVAILABLE`             | 当前环境的开放接口认证能力不可用。      |

<Note>
  账号密码只用于管理后台登录，绝不能代替 Public API Key 调用开放接口。
</Note>