桌面画布：独立单张计费
每次成功出图 1 张，扣 ¥0.02。支持 gpt-image-2 与 gpt-image-2.5-flare 的 g5 / image2 1k 分组，失败不收费。此模式独立于下方企业套餐。
01 / GET STARTED
接入准备
- 登录控制台，在“API Keys”创建程序专用的QYapi Key，完整值仅显示一次。
- 在“余额与费用”确认余额，在“接入说明”查看计费配置。
- 保留桌面程序现有的图片服务地址与 Key，加入下方预留、结果回报和查询操作。
- 先完成一组三图的生成与记账核对，再扩大使用。
桌面程序 → 图片服务商：发送参考图和提示词，接收图片。
桌面程序 → QYapi：发送任务编号、模型、分组及结果状态，记录费用。图片和图片服务商 Key 均不发送给QYapi。
02 / ACCESS
程序需要哪些配置
图片服务地址与 Key 用于生图；QYapi计费地址与 qy_ Key 用于账户记账。两个 Key 不可互换。
Authorization: Bearer YOUR_QYAPI_KEY Content-Type: application/json
以下所有计费操作均使用上述请求头。程序需要加入计费逻辑，仅把原来的生图 Key 或 URL 替换为QYapi配置，无法完成接入。
03 / ENDPOINT
QYapi计费地址
https://zqfibcyqyufycmprxvwl.supabase.co/functions/v1/image-usage
所有操作使用 POST application/json。该地址处理短时计费请求，不转发图片。网站提供账户、账单与充值管理，不提供通用生图 Base URL。
04 / GROUP DELIVERY
一组交付 → 回报结果 → 逐组结算
新任务统一使用 /functions/v1/image-package。旧 image-usage 的 reserve 已停用，返回 409 PACKAGE_REQUIRED，不会新增预留或发起生图。旧接口只保留余额查询和历史记录处理。
1. 核对约定并建立任务
先调用 quote 核对价格与启用状态，再以持久化的套餐编号、商品与店铺身份调用 open，携带 terms_version: 2。每组 ¥0.08，10组正常完成为 ¥0.80。
2. 登记每次图片请求
在套餐内调用 reserve 登记组号、图片角色和唯一请求编号。程序直接调用图片服务商并保存图片，以 complete 回报有效图片及校验信息。复用的印花图不再发起生成；每组由1张印花图和2张新增姿势图组成。
3. 按完成组结算
三张图片校验通过后，通过 settle_group 提交三图证据，按组扣费。重试结算使用原编号，不重复扣费。失败且上游确认未收费时，自动补缺图不加收费用；上游确实额外扣款并取得对应证据时，另列“补图”，每张 ¥0.02。扣款不明保留核查证据，不冒充成功扣费。
控制台费用类型只有“一组”和“补图”。迁移前的按张历史记录附有“历史按张记录”说明，原金额与财务状态保留。
05 / LOOKUP
查询余额与原任务
{ "action": "account" }
返回 balance_milli（总余额）、reserved_milli（预留）和 available_milli（可用）。billing.ready 表示当前账户与计费渠道配置就绪，不代表图片服务商实时可用。
{ "action": "status", "request_id": "image_request_0001" }
返回原任务状态、charged_milli 和 reserved_milli。查询不会生图或扣费。Key 只能访问所属账户的记录，QYapi不保存或提供图片下载。
06 / ERRORS
异常时如何处理
| 返回 | 程序处理 |
|---|---|
| 401 AUTH_REQUIRED | 停止提交，检查QYapi Key。 |
| 402 INSUFFICIENT_BALANCE | 预留未成功，不调用图片服务商，补充余额后再试。 |
| 400 INVALID_IMAGE_REQUEST / ROUTE_UNAVAILABLE | 检查模型、分组与编号，不继续生图。 |
| 409 REQUEST_ID_CONFLICT | 编号已对应另一模型或分组，检查本地任务记录。 |
| 409 JOB_ALREADY_FINALIZED | 已存在相反的最终结果，停止自动处理，查询原账单核对。 |
| 404 JOB_NOT_FOUND | 核对账户和编号；预留响应丢失时可用原参数与编号重试预留。 |
| 503 或网络中断 | 保留本地记录，恢复后重试同一计费操作，禁止据此再次生图。 |
07 / BILLING
扣费与充值
- 预留只减少可用余额，总余额尚未扣除。
- 桌面程序回报成功后，QYapi按该任务预留时锁定的价格结算一次。
- 未取得有效图片且上游未扣款时不收费；上游扣款不明时先释放预留、保持未扣费，单独核查。新规则下，精确请求编号对应的上游记录确认额外实扣时，另记¥0.02补图费；上游退款后退回对应费用。历史任务不追加新规则费用。
- 同一任务重复预留或重复提交相同结算不会重复记账；到期释放后若收到有效交付或已核实扣款，按同一编号补记一次，并重新检查余额。
金额单位为千分之一元：20 = ¥0.02。总余额 ¥100、无其他变动时，成功结算 10 张应剩 ¥99.80。可用余额 = 总余额 − 预留金额。
按组计费
每店每商品10组，每组交付“1张印花＋2张新姿势”。整套实际生成30张：10张印花复用为每组首图，另外生成20张姿势。每组三图验证齐全后结算¥0.08，完整10组¥0.80（40份套餐服务额度），并非40张API生成图片。四店正常完成合计¥3.20。
失败且上游未扣款可自动补缺图，不另外收费。正常补成功并纳入三图交付的请求仍包含在套餐中。额外上游实扣请求按¥0.02/次列为“补图”；同一实扣证据只结算一次，上游退款后自动退回。未知扣款不当作实扣。
套餐使用 /functions/v1/image-package，支持 quote、open、reserve、complete、settle_group、status、list、list_attempts、close。新套餐 open 必须携带 terms_version: 2。预留有效期10分钟，恢复生成时重新检查余额，不影响已完成组。关闭套餐释放未完成部分。
调用明细的财务状态只有“已扣费”和“未扣费”。上游核查单独显示：暂未证实的费用不扣款、不长期占款；24小时仍无证据自动结案并保留记录，不冒充已确认退款。可通过 provider_evidence 回报精确请求编号匹配的消费与退款记录，上游凭证始终留在桌面本地。
充值支持 ¥10、¥100、¥200、¥500、¥1,000 或自定义金额（最低 ¥10）。以支付结果核验后的到账记录为准。
查看余额与费用 →08 / KEY MANAGEMENT
管理程序凭证
QYapi Key 和图片服务商 Key 分别保存在桌面程序的操作系统凭据存储中，不写入公开源码、日志或截图。上游 Key 不需要上传QYapi云端。更换QYapi Key 不影响同一账户的余额和账单。
管理 API Keys →09 / INTEGRATION CHECK
接入检查
- 查询账户，确认余额、模型分组和价格。
- 先完成一组三图真实交付，核对可打开的本地结果、唯一结算流水与图片服务商的对应记录。
- 再核对约 10 次真实请求；检查无图退回、记账重试和程序中断恢复。
- 在公司实际程序和网络中逐级验证并发，分别检查出图、计费和日志。上游容量不能代替计费接口的容量验收。
网站和在线账本独立运行，无需 Codex 持续开启。程序必须保留计费调用及未完成任务记录，才能在直接生图时同步记账。