R524809
147 lines
8.3 KiB
Markdown
147 lines
8.3 KiB
Markdown
# 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`）
|
||
|
||
```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`）本期不接，留作后续选项。
|