¥0.02 / 张 · 独立单张模式 · 当前企业套餐继续保留
QYapi 桌面画布 · 独立单张计费接入文档
版本：single_image_v1，2026-10-16
一、适用范围
自由单张图生图，每次请求生成 1 张；成功保存一张有效新图，扣 ¥0.02。
仅支持当前启用的 gpt-image-2 / g5 与 gpt-image-2.5-flare / g5（image2 1k）。
每次以 quote 返回的路线为准。路线停用或价格不再为 ¥0.02 时拒绝新预留，不自动换贵渠道。
参考图、复用图、失败未出图不收费。现有企业套餐、历史单价与已扣金额保持原规则。
这是独立计费接口，不是生图代理。桌面程序仍须直接调用已有上游的图生图地址与上游 Key；QYapi Key 只用于下方计费操作。QYapi 不接收提示词、图片文件或上游 Key。
二、接口和鉴权
POST https://zqfibcyqyufycmprxvwl.supabase.co/functions/v1/image-single
Authorization: Bearer YOUR_QYAPI_KEY
Content-Type: application/json
使用控制台创建的 qy_ Key。建议通过桌面应用主进程/后端发起请求，勿把 Key 写入网页、日志或源码。
三、一次完整调用
0. 查询可用单价
{"action":"quote"}
返回 routes、price_milli=20、price_cny="0.02"、images_per_request=1。
金额内部单位为千分之一元：20 = ¥0.02，1000 = ¥1。
1. 本地先持久化唯一 request_id，再预留 ¥0.02
{"action":"reserve","request_id":"canvas_20261012_000001","model":"gpt-image-2","group":"g5","image_count":1}
request_id 为 8–80 位字母、数字、下划线或短横线。同一账号下不可跨模型复用。
成功返回 job_id、status="reserved"、reserved_for_job_milli=20、available_milli。
预留不是实际扣费；余额不足返回 HTTP 402，不要发起上游生图。
重复 reserve 使用相同 request_id，不重复占用额度。
2. 在实际请求上游前领取一次提交权
{"action":"claim","request_id":"canvas_20261012_000001"}
仅当 submit_upstream=true 才可提交上游生成。后续重复 claim 返回 false。
桌面程序须持久化提交状态；领取后断线/崩溃不能凭 false 盲目再提交。
如上游支持幂等键，使用同一个 request_id。可查询上游任务时优先查询。
上游图生图参数由其接口定义；设定 n=1，使用与计费声明匹配的模型和分组。
QYapi 的 g5 是计费分组标识，不代表所有上游都接受同名参数。
3. 下载、校验并保存一张有效输出图后回报成功
{"action":"complete","request_id":"canvas_20261012_000001","outcome":"succeeded","image_count":1,"image_sha256":"输出图片原始字节的64位小写SHA256","provider_request_id":"真实上游请求或任务编号"}
示例中的 SHA256 占位文字必须替换为真实摘要。上游编号支持字母数字及 _.:-，1–200 字符。
返回 status="settled"、charged_images=1、charged_milli=20。
重复回报相同编号及摘要不会再次扣款；同一个上游结果不能换 request_id 再扣一次。
上游若没有稳定的请求/任务编号，需要先与上游确认取值方式，不能随机伪造编号来重复结算。
成功证据由桌面程序回报；计费服务校验字段与幂等性，并未独立下载图片或核实上游生成。
4. 明确失败且没有有效输出
{"action":"complete","request_id":"canvas_20261012_000001","outcome":"failed"}
返回 status="released"、charged_images=0、charged_milli=0，释放该请求预留。
已明确失败的编号不能再改为成功；重新生成请使用新 request_id。
如果仅是网络超时、尚不能确认上游结果，使用 uncertain，不要过早报 failed。
5. 结果暂时不确定
{"action":"complete","request_id":"canvas_20261012_000001","outcome":"uncertain"}
不扣费，保留短期预留；默认预留期限 10 分钟，由后台/后续请求清理。
超时释放不是认定生成失败。之后若查到有效图片，可对原编号补报成功，按原 ¥0.02 扣一次；当时可用余额不足则返回 402，需充值后重报。
6. 查询
{"action":"status","request_id":"canvas_20261012_000001"}
返回状态、已计费张数、费用、预留及可用余额。只允许查询本账号记录。
调用日志会保留 single_ 前缀的请求编号；成功单张进入用量分析和最近七天统计。
四、重试和异常约定
请求超时：先查 status，计费请求重试沿用原 request_id；成功回报沿用原摘要和上游编号。
确实重新生图：新 request_id，重新预留和 claim；只有新图成功才扣 ¥0.02。
本模式不收失败补损，不把重试自动计入原套餐，不按三图或四图套餐收费。
需要 N 张时拆成 N 个独立单张任务，不提交 image_count=N。
401：Key 无效/未登录；403：账号尚未开放使用权限；402：可用余额不足。
404 JOB_NOT_FOUND：本账号无该请求。
409 SINGLE_ROUTE_UNAVAILABLE：当前 ¥0.02 路线不可用，不能切换贵渠道。
409 RECEIPT_CONFLICT / DUPLICATE_PROVIDER_RESULT：证据冲突或结果已计费，停止重复结算并核查。
503：计费暂不可用，保留本地任务与证据，退避重试，勿重新触发上游生成。
五、验收范围
已通过独立数据库并发、幂等、失败释放、权限隔离、历史流程兼容与逐张统计测试。
已通过正式 HTTP API 的隔离账号记账链路测试；测试成功回报使用标记清楚的测试证据。
桌面画布的实际上游图生图、下载保存、断网恢复，还需接入后端到端验收。