RightAPI（gpt-image / nano-banana）调用方式排查报告

2026-08-20 · 状态：待确认（确认后再改代码）结论先行：是调用方式不对。现行代码把参考图用 multipart 传给未在文档中的 /v1/images/edits 端点；该中转已于 2026-07-14 全面切换"统一异步模式"，文档中的正确用法是 /v1/images/generations + JSON image（data-URI 数组）+ async: true 提交任务，再轮询 /v1/tasks/{task_id} 取图。实测：文档路径下 gpt-image-2、 gpt-image-2-vip、nano-banana-2-lite 全部逐像素保真；现行 edits 路径要么 502、要么出图但参考图未生效（商品按文字重造）。

1. 现行代码怎么调的（generator.py `_rightapi_request`）

# 有参考图（套图流程必然有）→ multipart POST /v1/images/edits
files = [("image[]", ("ref-1.png", data, mime)), ...]
data  = {"model", "prompt", "size": "2048x2048", "quality": "high",
         "output_format": "jpeg", "n": 1, "input_fidelity": "high"}
resp = client.post(f"{base}/v1/images/edits", files=files, data=data)
# 期望同步响应 data[0].b64_json / data[0].url，无任务轮询

问题：

/v1/images/edits 不在文档接口列表里（文档只有：图片生成、Gemini 生成、任务查询）；
参考图用 multipart image[] 传输——新管道只认 JSON body 里的 image（data-URI 数组）；
未带 "async": true，也没有任务轮询逻辑；
quality / output_format / input_fidelity 均不在文档参数表中。

2. 文档的正确用法（docs.rightapi.ai，2026-07-14 更新）

2.1 提交：POST `/v1/images/generations`（OpenAI Images 兼容，异步）

{
  "model": "gpt-image-2",            // 或 nano-banana 系列等
  "prompt": "...",
  "n": 1,
  "size": "1:1",                     // 比例 1:1 / 16:9 / 9:16 / 4:3，或像素串 "1024x1024"
  "async": true,                     // 固定带
  "image": ["data:image/png;base64,..."]   // 参考图：data-URI 数组（保真关键）
}

响应（立即返回）：

{"task_id": "task_xxx", "status": "processing", "progress": 0, "message": "..."}

2.2 轮询：GET `/v1/tasks/{task_id}`（站点级，不带 /draw 前缀）

进行中：{"id","task_id","object","model","status":"in_progress","progress":0~2,"created_at"}
完成：{"created": ..., "data": [{"url": "https://...jpeg"}]} ——实测完成响应没有 status: "completed" 字段（与文档描述不符），完成判定 = 响应里出现 data；结果只有 url（未见 b64_json）。
progress 基本不动（一直 0~2），只能当装饰，不能当进度条依据。

2.3 其他要点

Gemini 原生端点 /v1beta/models/{model}:generateContent（contents/parts + inline_data， generationConfig.imageConfig 支持 aspectRatio / imageSize）——nano-banana 系列可走，但非必需（generations 端点同样支持传参考图），本期可不做；
imageSize："1K"/"2K"/"4K"，仅 nano-banana / gpt-image vip 模型可用；
文档域名示例为 www.right.codes/draw，实测现有配置 rightapi.ai/draw 仍通（提交与任务查询都可用，rightapi.ai/v1/tasks/... 实测正常）。

3. 实测证据（2026-08-20，受控对照实验）

测试图：程序生成的特征图形——白底 + 青色杯身 + 红色横条纹 + 三颗黄色五角星 + 右侧把手。提示词："把背景替换成纯绿色，保持图中那个青色杯子完全不变……"。保真判定 = 逐项核对杯身/条纹/星星/把手是否原样（我人工查看生成图）。

#	路径	模型	结果
A	文档路径 generations + image[] + async	nano-banana-2-lite	✅ 保真完美，仅背景变绿
C	文档路径 generations + image[] + async	gpt-image-2	✅ 保真完美，仅背景变绿
D	文档路径 generations + image[] + async	gpt-image-2-vip（官逆）	✅ 保真完美，仅背景变绿
B	现行代码 edits + multipart image[]	nano-banana-2-lite	❌ 502 Bad Gateway（间隔 90s 重试仍 502；同期 generations 路径正常）

用户今日实测（11:08–11:16，本地任务表，同一鲨鱼玩偶参考图）：

套图	模型（路径）	结果
7bd57ffa	gpt-image-2-vip（现行 edits）	⚠️ 出图，但鲨鱼被重新设计（眼睛/鱼鳍/比例全变）
ee36e92f	nano-banana-2（现行 edits）	⚠️ 同上，商品被重造
42c37fa2	wan2.6-image（DashScope，正常链路）	⚠️ 鲨鱼同样有漂移（另一层问题，见 §5）

探针产物（供复核）：/tmp/rightapi-probe/（ref.png / gen-async-lite.png / gen-async-0.png）。

4. 根因分析

参考图从未真正送达模型：edits + multipart 是旧同步模式的调用方式；中转 7-14 切到统一异步管道后，multipart 参考图不被解析 → 模型只收到 prompt 文字 → 按文字（含标题/风格词）重新合成商品 → "不是原商品"必现。gpt 与 google 全中，因为它们共用这一条错误链路。
端点本身进入半废弃状态：今天 edits 已对 lite 模型直接 502（两次、间隔 90s），对 gpt-image-2-vip / nano-banana-2 尚能返回（用户 11 点实测出图）——属于残留兼容，随时可能全断。之前代码里"同 key 分钟级冷却 502"的注释，与该端点的不稳定状态吻合。
提示词层面的修复（上一轮 gpt/google 家族重写）方向正确但没治病根：参考图没到模型，提示词写得再保真也没用。证据：同一套提示词组件，走文档路径（探测 A/C/D）保真完美。

5. 顺带观察：通义今日也有漂移（不在本次修复范围）

wan2.6-image 走 DashScope 正常链路（参考图确实送达）仍重造了鲨鱼——这是主体参考模型能力/提示词层面的问题（wan2.6-image 是参考遵循较弱的一档），与本次 RightAPI 调用方式无关，建议后续单独评估（比如套餐默认模型换成 wan2.7-image-pro 或 qwen-image-3.0-pro，两者参考遵循更强）。

6. 修复方案（确认后实施）

只改 server/services/generator.py 的 RightAPI provider，提示词层不动：

统一走 /v1/images/generations（有无参考图都走它；无参考图就不带 image 字段）：

body = {"model": model, "prompt": prompt, "n": 1,
        "size": size, "async": True}
if refs:
    body["image"] = [data_uri, ...]      # data-URI 数组（≤2 张，沿用现选图逻辑）
resp = post(f"{base}/v1/images/generations", json=body)
task_id = resp.json()["task_id"]

新增任务轮询：GET {origin}/v1/tasks/{task_id}（origin = base 去掉 /draw）； 3s 起步、逐步加到 10s，上限沿用 poll_max_wait（600s，gpt 高质量单张 1–5 分钟）；完成判定 = data 出现（不能依赖 status == "completed"）；失败态 = status 为 failed/error/cancelled；然后下载 data[0].url。
参数清理：删 quality / output_format / input_fidelity（均非文档参数； input_fidelity 的探测-降级机制整体移除）。size 改传像素串 "1536x2048"（3:4）/ "2048x2048"（1:1）——比例枚举里没有 3:4，像素串是文档允许的写法。
重试保留：提交/轮询遇到 429/5xx/超时，沿用 60→120→240s 退避（rightapi_max_retries）。
配置：RIGHTAPI_BASE_URL 保持 https://rightapi.ai/draw 不变；rightapi_image_quality 配置项删除（或停用）。

预计工作量：_rightapi_request 重写约 60 行 + 轮询函数 30 行，其余层（提示词分发、任务执行器、前端）零改动。

7. 上线前待确认项

3:4 像素串 1536x2048 是否被接受——探测只验证了 size: "1:1"（文档说像素串合法，但建议改完后先出 1 张 Ozon 规格图验证）；
nano-banana / nano-banana-2 / nano-banana-pro 三个型号未逐一实测（同族接口一致， lite / gpt 系已验证通路，风险低）；
是否启用 imageSize（2K/4K，仅 nano-banana 与 gpt-image vip 支持）——默认不传，需要高清再说；
Gemini 原生端点（:generateContent）本期不接，留作后续选项。

8.3 KiB Raw Blame History Unescape Escape