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 的隔离账号记账链路测试；测试成功回报使用标记清楚的测试证据。

桌面画布的实际上游图生图、下载保存、断网恢复，还需接入后端到端验收。