把「充值」做成一个不需要注册的流程

注册流程每多一步，转化就掉一截。对于「我想花 20 块钱试试」这种冲动型需求，游客购卡几乎是唯一可行的设计。

游客购卡的完整链路

选套餐 → 创建订单 → 支付宝支付 → 验签回调 → 发放 Key。每一步都要幂等，失败要能恢复。

兑换码是预付凭证，游客卡是订单交付产物，两者的失败模式不一样。

兑换失败通常是「码不存在 / 已使用 / 过期」；游客购卡失败可能是「支付未确认 / 凭证过期 / 目标 Key 已停用」。

订单恢复链接要安全

凭证放在 URL fragment 里，服务端只存摘要。恢复链接是用户唯一的凭据，泄露等于泄露 Key。

一个常见的坑是：运营调整了套餐价格，结果已经创建但未支付的订单也跟着变了。

游客也需要查用量的入口

低敏感度的查询凭证让用户能自己看进度，而不是每次都来问客服。

网关的用量查询页应该一次性回答这三个问题，而不是让用户提工单。

同时要保证续费时已用量的保留逻辑是对的：今天已用的部分不该被覆盖。

发卡之后要给清晰的下一步

完整 Key 怎么复制、Base URL 是多少、怎么验证连通性——这三件事一次说清楚，能消掉大部分「不知道怎么用」的咨询。

任何客户端接入，先把这三样固定下来：Base URL、模型 ID、Key。

模型 ID 不要从文档里抄，要用你的 Key 实际查一次 /v1/models 拿到真实可用的那个。

实操：用查询凭证查用量，不必把完整 Key 交给前端。

查询入口是游客用户使用过程中最常打开的页面。

# 查询凭证是一段 10 位字符串，权限远低于完整 API Key。
curl "https://aiminis.info/api/v1/query-key/quota?key=QRY1234567"

# 返回里包含：今日剩余额度、每日额度、有效期、状态，
# 以及最近 100 条调用明细（默认每页 10 条）。
# 浏览器端还会把最近用过的查询凭证存在 Cookie 里，方便下次直接看。

几个容易踩的坑

• 价格用浮点数存储，累加后账目对不上。
• 套餐改了之后已创建的订单也跟着变，用户看到的和付的不一样。
• 续费时没保留今日已用量，等于凭空多给了一份额度。
• 奖励金被撤销但已经被抵扣，产生了资损。

小结

把配置项和凭据都外置，是成本最低、收益最持久的一个工程习惯。

文中的配置和示例都能在 https://aiminis.info/ 直接跑一遍，接入文档在 https://aiminis.info/docs/api-integration。