鉴权

API Key 格式#

API Key(控制台中显示为「子密钥」)格式:

sk-gpushare-{64 字符十六进制}

例: sk-gpushare-0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

总长度 76 字符(sk-gpushare- 前缀 12 字符 + 64 位十六进制)。写 Key 校验 / secret-scanning 正则时按这个长度配置。

原始 Key 服务端以 AES-256-GCM 加密存储,可以在控制台 Key 详情页随时重新查看(reveal)。只有早期创建的少数 hash-only 老 Key 不支持 reveal——丢了就重建一把。

同一把 Key 通用于全部对外端点: 四个聊天协议端点、图像 / 视频 / Embedding API、知识库 API & MCP。

创建 / 管理 Key#

访问 model.dflop.top/dashboard/keys:

1. Create Key —— 命名(必填) + 可选 allowed_models 白名单 + 可选过期时间
2. 随时查看 —— Key 详情页可 reveal 原始 Key(服务端加密存储)
3. 查看用量 —— 历史调用日志(model / token / 费用逐条可查)
4. 撤销 —— 任何 Key 可立即 disable 或删除

Key 的可配置项#

Key 上没有预算配置。 预算在账户余额(所有 Key 共享,见下文 余额与计费)。Key 级的隔离手段只有 allowed_models / expires_at / enabled,用于权限隔离与审计,不是预算隔离。

4 种鉴权方式#

Gateway 按以下优先级查找 Key,任一种生效(命中即停):

x-api-key → x-goog-api-key → ?key= → Authorization: Bearer

1. x-api-key Header (推荐)#

curl https://api.dflop.top/v1/messages \
  -H "x-api-key: sk-gpushare-xxx" \
  ...

Anthropic SDK / Claude Code 默认走这条。最直白,也最不易被中间层吞掉。

2. x-goog-api-key Header#

curl https://api.dflop.top/v1beta/models/gemini-2.5-flash:generateContent \
  -H "x-goog-api-key: sk-gpushare-xxx" \
  ...

Google genai SDK 的默认 header —— Gemini SDK 用户无需任何改造直接可用,且 header 值不会进 URL access log,没有泄漏问题。

3. ?key= Query Param#

curl "https://api.dflop.top/v1beta/models/gemini-2.5-flash:generateContent?key=sk-gpushare-xxx" \
  ...

Gemini REST 风格的替代写法。不推荐手写 —— Key 会出现在 access log / browser history,有泄漏风险。

4. Authorization: Bearer Header#

curl https://api.dflop.top/v1/chat/completions \
  -H "Authorization: Bearer sk-gpushare-xxx" \
  ...

OpenAI SDK 默认走这条。

例外: GET /v1/models 只接受 Authorization: Bearer 和 x-api-key 两种 header,不支持 ?key=。

推荐做法#

用 env var 不要硬编码#

# ~/.bashrc
export PLATFORM_API_KEY=sk-gpushare-xxx

client = OpenAI(
    api_key=os.environ["PLATFORM_API_KEY"],
    base_url="https://api.dflop.top/v1",
)

余额与计费(统一钱包)#

本平台采用 预付费账户钱包,不是 post-pay。

计费模型#

预算在账户余额(USD 钱包),所有 API Key 共享同一余额。Key 本身没有独立预算池——Key 只是访问凭证。

• 体验额度: 注册即送 $0.30,足够跑通全部入门示例
• 充值: 主站 dflop.top/dashboard/billing (Stripe,最低 $1;与 model.dflop.top 同账号 SSO,共享同一余额)
• 查询: 控制台 dashboard 实时显示余额与各 Key 用量明细

计费单位按端点类型:

每次 chat 请求 gateway 做两步:

1. Pre-charge —— 按最坏情况估算成本,跟账户余额比对,超了返回 402,不发上游
2. Settle —— turn 结束后按真实 token 用量扣减账户余额,并写入用量日志

Pre-charge 如何估算#

Pre-charge 用 worst-case 口径:

• 输入 ≈ messages JSON 字节数 ÷ 4
• 输出按 max_tokens 计满;不传 max_tokens 时按模型的 default_max_tokens 计满(部分长输出模型高达 32768)

估算值 > 余额即 402,即使真实用量远小于余额。余额紧张时显式传一个较小的 max_tokens 即可通过 pre-charge。另外 settle 阶段不再做 gate,并发请求竞态下余额可能轻微变负(下次请求会被拒)。

余额耗尽#

返回 HTTP 402 Payment Required。OpenAI 形状 (/v1/chat/completions 等):

{"error": {"message": "quota exceeded: used 0.00 of 0.00 USD", "type": "insufficient_quota", "code": "quota_exceeded"}}

• 余额 ≤ 0 时在鉴权阶段就直接 402,不会等到 pre-charge
• /v1/messages 返回 Anthropic 形状 (type: "billing_error",无 code 字段),/v1beta 返回 Gemini 形状 (status: "RESOURCE_EXHAUSTED"),三协议对照见 错误处理

修复: 到 dflop.top/dashboard/billing 充值。新建 Key 不能解决额度问题 —— 所有 Key 共享同一余额,余额耗尽时所有 Key 同时 402。

多 Key 策略#

Key 是凭证不是预算池,多把 Key 的价值在权限隔离 + 审计归因:

安全建议#

1. 永远不要 把 Key 写进 git 仓库 / 截图 / Slack 消息
2. 用 direnv / 1Password CLI / Doppler 注入 env var
3. 怀疑泄漏立即在控制台撤销
4. 服务端代码用环境变量,不要从前端发起调用 (会暴露 Key)
5. 浏览器端必须调用时,做后端代理转发
6. Key 可在控制台随时 reveal,意味着控制台账号本身的安全同样关键 —— 保护好 SSO 账号

CSRF / Origin#

本网关 endpoints 不强制 Origin / CSRF token —— 全靠 Key 鉴权。所以 Key 泄漏 = 完全暴露。

(model.dflop.top 控制台自身用 cookie + CSRF token,但那是单独的管理面板鉴权,不影响 gateway API)