认证与 Public API Key - 灵感开放平台

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

Authorization: Bearer <PUBLIC_API_KEY>

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

{
  "code": 200,
  "data": {},
  "request_id": "req_xxx"
}

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

{
  "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 到期或被删除后，调用立即失败。

服务端使用

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'],
  }),
});

安全要求

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

使用环境变量或专业密钥管理系统保存密钥。
不要在错误日志中记录完整 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`	当前环境的开放接口认证能力不可用。

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