基本概念

API 密钥

API 密钥是你访问 Smartoken 网关的凭证，与 OpenAI key 同形态。它绑定到具体用户，不可恢复（DB 里只存哈希）。建议为每个项目 / 环境单独建一把密钥，方便排查与作废。

密钥有「启用 / 停用」两种状态，停用后该密钥的所有请求都会被拒。控制台 → API Keys 里可以随时吊销。

模型与 Slug

每个模型有一个唯一的 slug（如 deepseek/deepseek-chat），调用时通过 model 字段指定。slug 是稳定的对外名称：背后挂的具体上游渠道、版本可以由运营动态调整，调用方无需改代码。

模型分两类：

LLM（chat completion）：走 /v1/chat/completions 或 /v1/responses，按 token 计费（输入价 + 输出价 + 可选缓存读取价）。
文生图（text-to-image）：走 /v1/images/generations，按张计费。
文生视频（text-to-video）：走 /v1/videos/generations，按分辨率 × 时长（秒）计费。

完整模型列表见模型市场，无需登录即可查看。

余额与计费

账户余额分两部分：

付费余额（paid balance）：Stripe 充值 / 代金券兑换都会进这部分。
赠送余额（gift balance）：管理员手动赠送，仅对「礼物可用」的模型有效。

扣费按实际 token 用量计算（输入 / 输出 / 缓存读取分别计），单位是 µUSD（百万分之一美元）：


# LLM（按 token）
成本 = 输入_tokens × 输入单价 / 1_000_000
     + 输出_tokens × 输出单价 / 1_000_000
     + 缓存读_tokens × 缓存读单价 / 1_000_000

# 文生图（按张）
成本 = 张数 × 每张单价

# 文生视频（按分辨率 × 时长秒数）
成本 = 该分辨率每秒单价 × duration

计费时机：成功的请求结尾立即扣款；上游 5xx / timeout 不计费；上游 4xx 一律退款；流式中途断开按已返回部分计费。

渠道与容灾

一个模型 slug 背后可以挂多个「渠道」（上游 endpoint），按挂载优先级排序。运营在管理后台维护，对你透明。

网关会按优先级逐个尝试：上游 5xx / 超时 / 连接失败 → 自动 failover 到下一个；任意一次 4xx → 返回客户端（视为业务错误，不重试）；全部失败 → 503。对你的代码意义：通常不需要自己实现重试。

网关后台有熔断机制：某个渠道连续失败若干次自动熔断，5 分钟冷却后半开探测，避免持续打挂的上游拖累整体延迟。

代金券

代金券是由运营生成的 16 位字符串（如 A1B2C3D4E5F6G7H8），用户可在 Billing 页面输入兑换为付费余额。可以指定有效期与白名单（仅指定用户可用）。