通用接口
鉴权
API Key 申请、使用、scope 与安全建议。
所有 /v1/* 接口都需要在请求头携带 API Key:
Authorization: Bearer sk-coke-xxxxxxxx- Key 前缀固定为
sk-coke-,长度 40 字符左右。 - 服务端只保存
prefix + last4 + hash(salt),不可逆查回明文。 - 一个账号可创建多个 Key,建议按"环境/项目"分别创建 (dev / staging / prod)。
创建 Key
到 www.cokeapi.com 控制台「密钥」页:
关闭对话框后明文再也无法找回。如果遗失,作废旧 Key 重新创建即可。
Scope (能力范围)
创建 Key 时可指定 scope,限制本 Key 能调用的接口范围:
| Scope | 允许的接口 |
|---|---|
chat | /v1/chat/* |
image | /v1/images/* |
video | /v1/video/* 与 /v1/videos/* |
* 或留空 | 全部 |
多个 scope 用逗号分隔,例:chat,image。
越权检查
请求头里的 Key 与请求路径不匹配时,返回:
{
"error": {
"type": "forbidden",
"code": 403101,
"message": "API Key scope 不包含此接口",
"trace_id": "..."
}
}安全建议
- 不要把 Key 提交到 Git。Web 应用让请求经自家后端,前端只通信自家后端。
- 按用途拆 Key:dev / staging / prod 分开,便于追溯泄漏来源、单独作废。
- 设置 RPM 与每日配额:即使 Key 泄漏,损失被限制在配额内。
- 定期轮换:建议每季度或团队成员变动时轮换 Key。
- 监控异常调用:控制台「密钥→用量统计」页有 QPS / 错误率曲线。