01 / GET STARTED
快速开始
图片调用及 API Key 创建尚未开放。账户与费用查询可正常使用；接口开通后按以下流程接入。
02 / ACCESS
鉴权
计费接口使用启源账户访问令牌或启源 API Key，放入 Authorization: Bearer <TOKEN> 请求头。网页使用当前登录会话；桌面程序使用该账户签发的 Key。
令牌只用于启源账户鉴权。图片生成的凭证与请求方式由所选图片渠道决定。
03 / ENDPOINT
服务地址
https://zqfibcyqyufycmprxvwl.supabase.co/functions/v1/image-usage
此地址处理余额预留与结算，不返回生成图片。桌面程序发起图片请求并取得结果后，使用相同任务编号确认结算。
04 / REQUESTS
预留与结算
一次请求对应一张图片。先预留额度，得到 job_id 后再发起生图。request_id 使用 8–100 位字母、数字、下划线或连字符，同一次请求重试时保持不变。
预留额度
{
"action": "reserve",
"model": "gpt-image-2",
"group": "g5",
"request_id": "image_request_0001"
}模型和分组必须匹配已开通的渠道。价格由服务端读取，客户端不能指定扣费金额。
确认结果
{
"action": "complete",
"job_id": "预留接口返回的任务 UUID",
"outcome": "settled"
}settled：已收到有效图片，结算预留金额。released：明确生成失败，释放预留额度。uncertain：结果不明，保留额度等待核对。
超时不能直接视为失败。重试结果确认时沿用原 job_id，避免新建重复图片任务。
05 / RESPONSE
返回结构
预留成功返回任务编号、状态及单张费用：
{ "job_id": "任务 UUID", "status": "reserved", "price_milli": 50 }结算返回任务状态、账户总余额及预留金额：
{ "status": "settled", "balance_milli": 9950, "reserved_milli": 0 }金额以千分之一元为单位，50 表示 ¥0.05；以上数值仅解释字段含义。
06 / ERRORS
常见错误
| 状态码 | 错误 | 处理方式 |
|---|---|---|
| 401 | AUTH_REQUIRED | 检查登录状态或 Key。 |
| 402 | INSUFFICIENT_BALANCE | 补充余额后再请求。 |
| 400 | ROUTE_UNAVAILABLE | 检查模型与分组。 |
| 409 | REQUEST_ID_CONFLICT | 同一编号不可用于不同请求。 |
| 409 | JOB_ALREADY_FINALIZED | 任务已有最终结果，请核对日志。 |
| 503 | IMAGE_USAGE_NOT_READY | 调用服务尚未开放。 |
07 / BILLING
计费说明
可用余额 = 总余额 − 预留金额。预留不是最终扣款；成功后只结算一次，明确失败后释放预留。统计消耗只累计已结算金额。
同一模型不同分组可能价格不同，以请求时服务端确定的价格为准。充值订单以支付确认到账为准，返回成功页面不等于到账。
查看余额与费用 →08 / SECURITY
保护账户凭证
不要将密钥放在公共网页、截图或公开仓库中。只在受控环境保存；需要更换时先停用旧 Key。控制台完整密钥仅在创建时展示一次。
账户安全设置 →