# GPT基地 + 香蕉2.1 High {#section-1 .rd-guide-title}

先由 GPT Image 2.5 生成约 1K 原图，再由香蕉 2.0、香蕉 2.1 或香蕉 Pro 按原图重建为 1K / 2K / 4K。接口兼容 OpenAI Images，按张计费，三档同价。

## 1 快速开始 {#quickstart}

使用绑定 **`gpt基地+banana2.1 high 支持2k 4k` 分组（177）**的 API Key。示例生成一张 **2K 16:9** 图片，省略 `response_format`（默认返回图片链接 `url`），下载并打开；传入一张本地参考图时改为 **4K 图生图**。按分组价格计费，每次运行都会产生新的调用。示例使用 `gpt-image-2.5-banana2.1`；更快、更便宜可改用 `gpt-image-2.5-banana2`（香蕉 2.0），只需修改 `model`。

### 1.1 Python 3：完整流程 {#quick-python}

适用于 Windows、macOS 和 Linux。只使用 Python 标准库，无需安装 SDK。

将下面的代码保存为 `gpt-banana21-high-quickstart.py`，按提示输入 API Key：

- 文生图 2K 16:9：`python3 gpt-banana21-high-quickstart.py`
- 图生图 4K：`python3 gpt-banana21-high-quickstart.py reference.png`（上传一张本地 PNG / JPEG / WebP）

Windows 可用 `py -3` 替代 `python3`。生成通常需要 60--105 秒，请耐心等待；程序会打印文件路径和实际尺寸，并尝试用浏览器打开结果。

``` python
import base64
import getpass
import json
from pathlib import Path
import sys
from urllib.error import HTTPError
from urllib.request import Request, urlopen
import uuid
import webbrowser

BASE_URL = "https://yyds.seqnode.com/v1"
USER_AGENT = "YM2API-Quickstart/1.0"
# 不带参数：文生图 2K 16:9；带一个本地图片路径：图生图 4K（1:1）。
# 省略 response_format 时默认返回图片链接（url）；需要 Base64 时加 "response_format": "b64_json"。
# 更快、更便宜可把 model 改为 "gpt-image-2.5-banana2"（香蕉 2.0，$0.05/张）。
GENERATE = {
    "model": "gpt-image-2.5-banana2.1",
    "prompt": "雨后的城市街角咖啡馆，木质招牌写着'CAFE 1897'，暖色灯光，电影感。",
    "size": "2048x1152",
    "n": 1
}
EDIT = {
    "model": "gpt-image-2.5-banana2.1",
    "prompt": "保留参考图的主体、构图和文字，改成冬夜雪景，细节清晰。",
    "size": "4K",
    "n": "1"
}


def post(path, api_key, body, content_type):
    headers = {"Authorization": "Bearer " + api_key, "Content-Type": content_type, "User-Agent": USER_AGENT}
    with urlopen(Request(BASE_URL + path, data=body, headers=headers), timeout=300) as response:
        return json.load(response)


def multipart(fields, image_path):
    boundary = "----ym2api" + uuid.uuid4().hex
    chunks = []
    for name, value in fields.items():
        chunks.append(f'--{boundary}\r\nContent-Disposition: form-data; name="{name}"\r\n\r\n{value}\r\n'.encode("utf-8"))
    data = image_path.read_bytes()
    if data.startswith(b"\x89PNG\r\n\x1a\n"):
        mime, filename = "image/png", "reference.png"
    elif data.startswith(b"\xff\xd8\xff"):
        mime, filename = "image/jpeg", "reference.jpg"
    elif len(data) >= 12 and data[:4] == b"RIFF" and data[8:12] == b"WEBP":
        mime, filename = "image/webp", "reference.webp"
    else:
        raise ValueError("参考图需为 PNG、JPEG 或 WebP。")
    chunks.append(f'--{boundary}\r\nContent-Disposition: form-data; name="image"; filename="{filename}"\r\n'
                  f"Content-Type: {mime}\r\n\r\n".encode("utf-8") + data + b"\r\n")
    chunks.append(f"--{boundary}--\r\n".encode("utf-8"))
    return b"".join(chunks), "multipart/form-data; boundary=" + boundary


def main():
    api_key = getpass.getpass("输入 API Key：").strip()
    if not api_key:
        raise ValueError("请输入有效的 API Key。")
    if len(sys.argv) > 1:
        body, content_type = multipart(EDIT, Path(sys.argv[1]))
        result = post("/images/edits", api_key, body, content_type)
    else:
        body = json.dumps(GENERATE, ensure_ascii=False).encode("utf-8")
        result = post("/images/generations", api_key, body, "application/json; charset=utf-8")
    item = next(iter(result.get("data") or []), {})
    if item.get("url"):
        # 图片链接保留 1 小时；下载时不要携带 API Key。
        with urlopen(Request(item["url"], headers={"User-Agent": USER_AGENT}), timeout=120) as response:
            data = response.read()
    elif item.get("b64_json"):
        data = base64.b64decode(item["b64_json"], validate=True)
    else:
        raise ValueError("响应没有最终图片。请检查响应和使用记录，再决定是否重试。")
    if data.startswith(b"\x89PNG\r\n\x1a\n"):
        extension = ".png"
    elif data.startswith(b"\xff\xd8\xff"):
        extension = ".jpg"
    elif len(data) >= 12 and data[:4] == b"RIFF" and data[8:12] == b"WEBP":
        extension = ".webp"
    else:
        raise ValueError("返回数据不是可识别的 PNG、JPEG 或 WebP。")
    path = Path.cwd() / ("gpt-banana21-" + uuid.uuid4().hex + extension)
    with path.open("xb") as output:
        output.write(data)
    print(f"图片已保存：{path}（实际尺寸 {result.get('size', '未知')}）")
    if not webbrowser.open(path.as_uri()):
        print("请到以上路径手动打开图片。")


if __name__ == "__main__":
    try:
        main()
    except HTTPError as error:
        print(f"HTTP {error.code}：{error.read(2000).decode('utf-8', errors='replace')}")
        raise SystemExit(1)
    except Exception as error:
        print(f"运行失败：{error}")
        raise SystemExit(1)
```

[下载 Python 示例](gpt-banana21-high-quickstart.py)。如未自动打开结果，按输出路径手动打开。

### 1.2 PowerShell 7：完整流程 {#quick-powershell}

适合已有 PowerShell 7 的 Windows 用户。复制整段代码到终端，按提示输入 API Key。`$referenceImage` 留空时生成 2K 16:9；填写本地图片路径时上传该图并生成 4K。

``` powershell
$apiKey = Read-Host "输入 API Key" -MaskInput
if ([string]::IsNullOrWhiteSpace($apiKey)) { throw "请输入有效的 API Key。" }
# 留空：文生图 2K 16:9；填写本地图片路径（如 "C:\images\reference.png"）：图生图 4K（1:1）。
$referenceImage = ""
# 省略 response_format 时默认返回图片链接（url）；需要 Base64 时加 response_format = "b64_json"。
# 更快、更便宜可把 model 改为 "gpt-image-2.5-banana2"（香蕉 2.0，$0.05/张）。
$headers = @{ Authorization = "Bearer $apiKey"; "User-Agent" = "YM2API-Quickstart/1.0" }
if ([string]::IsNullOrWhiteSpace($referenceImage)) {
    $payload = @{
        model = "gpt-image-2.5-banana2.1"
        prompt = "雨后的城市街角咖啡馆，木质招牌写着'CAFE 1897'，暖色灯光，电影感。"
        size = "2048x1152"
        n = 1
    }
    $request = @{
        Uri = "https://yyds.seqnode.com/v1/images/generations"
        Method = "Post"
        Headers = $headers
        ContentType = "application/json; charset=utf-8"
        Body = [Text.Encoding]::UTF8.GetBytes(($payload | ConvertTo-Json -Depth 12))
        TimeoutSec = 300
        ErrorAction = "Stop"
    }
} else {
    $form = @{
        model = "gpt-image-2.5-banana2.1"
        prompt = "保留参考图的主体、构图和文字，改成冬夜雪景，细节清晰。"
        size = "4K"
        n = "1"
        image = Get-Item -LiteralPath $referenceImage -ErrorAction Stop
    }
    $request = @{
        Uri = "https://yyds.seqnode.com/v1/images/edits"
        Method = "Post"
        Headers = $headers
        Form = $form
        TimeoutSec = 300
        ErrorAction = "Stop"
    }
}
$result = Invoke-RestMethod @request
$item = $result.data | Select-Object -First 1
if ($item.url) {
    # 图片链接保留 1 小时；下载时不要携带 API Key。
    $temp = Join-Path $PWD ("gpt-banana21-" + [guid]::NewGuid().ToString("N") + ".download")
    Invoke-WebRequest -Uri $item.url -UserAgent "YM2API-Quickstart/1.0" -OutFile $temp -TimeoutSec 120 -ErrorAction Stop
    $bytes = [IO.File]::ReadAllBytes($temp)
    Remove-Item -LiteralPath $temp
} elseif ($item.b64_json) {
    $bytes = [Convert]::FromBase64String($item.b64_json)
} else { throw "响应中没有图片。请保留响应和使用记录排查。" }
# 根据文件头识别格式，不按 output_format 命名。
if ($bytes.Length -lt 12) { throw "返回的图片数据过短。请保留响应排查。" }
$hex = [BitConverter]::ToString($bytes, 0, 12).Replace("-", "")
$extension = if ($hex.StartsWith("89504E470D0A1A0A")) { ".png" }
    elseif ($hex.StartsWith("FFD8FF")) { ".jpg" }
    elseif ([Text.Encoding]::ASCII.GetString($bytes, 0, 4) -eq "RIFF" -and
        [Text.Encoding]::ASCII.GetString($bytes, 8, 4) -eq "WEBP") { ".webp" }
    else { throw "返回数据不是可识别的 PNG、JPEG 或 WebP。请保留响应排查。" }
$file = Join-Path $PWD ("gpt-banana21-" + [guid]::NewGuid().ToString("N") + $extension)
$stream = [IO.File]::Open($file, [IO.FileMode]::CreateNew)
try { $stream.Write($bytes, 0, $bytes.Length) } finally { $stream.Dispose() }
Write-Host "图片已保存：$file（实际尺寸 $($result.size)）"
Invoke-Item -LiteralPath $file -ErrorAction Continue
```

[下载 PowerShell 示例](gpt-banana21-high-quickstart.ps1)。

### 1.3 cURL：检查原始请求 {#quick-http}

以下命令适用于 Bash（Linux、macOS 或 Git Bash），只需输入 API Key。响应保存到 `response.json`，已有同名文件会被覆盖。

**文生图 2K 16:9（默认返回 url）：** 将下面内容保存为 UTF-8 的 `gpt-banana21-high-request.json`，也可[下载请求 JSON](gpt-banana21-high-request.json)。

``` json
{
  "model": "gpt-image-2.5-banana2.1",
  "prompt": "雨后的城市街角咖啡馆，木质招牌写着'CAFE 1897'，暖色灯光，电影感。",
  "size": "2048x1152",
  "n": 1
}
```

``` bash
read -rsp 'API Key: ' API_KEY; printf '\n'
curl --silent --show-error --fail-with-body --max-time 300 "https://yyds.seqnode.com/v1/images/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '@gpt-banana21-high-request.json' \
  --output response.json --write-out 'HTTP %{http_code}\n'
```

**图生图 4K，上传一张参考图：** 在 `reference.png` 所在目录运行，沿用上一段读取的 `API_KEY`（单独运行时先执行上一段的第一行）。让 cURL 自动生成 multipart 请求头，不要手动设置 `Content-Type`。

``` bash
curl --silent --show-error --fail-with-body --max-time 300 "https://yyds.seqnode.com/v1/images/edits" \
  -H "Authorization: Bearer $API_KEY" \
  -F "model=gpt-image-2.5-banana2.1" \
  -F "prompt=保留参考图的主体、构图和文字，改成冬夜雪景，细节清晰。" \
  -F "image=@reference.png" \
  -F "size=4K" \
  -F "n=1" \
  --output response.json --write-out 'HTTP %{http_code}\n'
unset API_KEY
```

HTTP 200 后，读取 `response.json` 中的 `data[0].url`，在 1 小时内下载。已安装 `jq` 时可直接运行：

``` bash
curl --fail --location --max-time 120 --output result.img "$(jq -r '.data[0].url' response.json)"
```

下载图片时不要携带 API Key。`result.img` 按文件头确认是 PNG 还是 JPEG 后再改扩展名。

## 2 接入信息与工作原理 {#access}

**Base URL：** `https://yyds.seqnode.com/v1`，与本站其他 OpenAI 兼容文档相同。

**鉴权：** `Authorization: Bearer YOUR_API_KEY`。Key 需在 [API Key 页面](/keys)创建并绑定分组 `gpt基地+banana2.1 high 支持2k 4k`（分组 ID 177）。分组由 Key 决定，不在请求体中填写 `group_id`。

### 2.1 生成流程 {#pipeline}

每次请求在服务端依次完成两步，客户端只需调用一次：

1. **GPT 原图：** 使用 GPT Image 2.5 按提示词和比例生成约 1K 的原图；图生图时参考你提供的全部参考图（包括 `https://` 链接）。
2. **香蕉重建：** 按所选模型使用香蕉 2.0（`gpt-image-2.5-banana2`）、香蕉 2.1（`gpt-image-2.5-banana2.1`）或香蕉 Pro（`gpt-image-2.5-banana-pro`），以第一步的原图为基础，重建为目标档位和比例的高质量画面。重建时还会收到：
    - 你的原始 `prompt`，用于把画面中出现的文字拼写正确；
    - 图生图时你上传的参考图（multipart 文件，或 `images[].image_url` 中的 `data:` Data URL），最多 6 张，缩小到最长边 1536 像素，用于让 Logo、文字、人脸和细节与原图一致。`https://` 远程参考图只用于第一步，不会传给重建步骤。

构图、主体和清晰文字基本保持。第二步是 **AI 重建，不是逐像素放大**，细节会被重新绘制。想要的文字请在提示词中用引号写明，详见[效果说明与已知限制](#limits)。

### 2.2 可用模型 {#models}

本分组提供三个模型，第一步均为 GPT Image 2.5，第二步按模型选择香蕉 2.0、2.1 或 Pro。`GET https://yyds.seqnode.com/v1/models`（使用同一鉴权头）返回这三个 id；其他模型名返回 400 `invalid_model`。

| 模型 | 第二步 | 价格（全分辨率同价） | 默认思考 |
| --- | --- | --- | --- |
| `gpt-image-2.5-banana2` | 香蕉 2.0（Nano Banana 2 / gemini-3.1-flash-image） | $0.05/张 | 不发送，可用 [`generationConfig`](#generation-config) 指定 |
| `gpt-image-2.5-banana2.1` | 香蕉 2.1（Nano Banana 2.1） | $0.06/张 | 请求 High，是否生效取决于上游渠道 |
| `gpt-image-2.5-banana-pro` | 香蕉 Pro（Nano Banana Pro / gemini-3-pro-image） | $0.065/张 | 不发送，可用 [`generationConfig`](#generation-config) 指定 |

2.1 默认请求 Thinking High，实际是否生效取决于所分配的上游渠道；2.0 和 Pro 默认不发送思考档位，可在 `generationConfig` 中指定。

2.0 通常更快、更便宜；本页示例使用 2.1，换用 2.0 只需修改 `model`。

## 3 接口与参数 {#endpoints}

| 方法与路径 | 用途 | 请求体 |
| --- | --- | --- |
| `POST /v1/images/generations` | 文生图 | JSON |
| `POST /v1/images/edits` | 图生图，参考图最多 15 张 | `multipart/form-data` 或 JSON |
| `GET /v1/models` | 查询可用模型 | 无 |

两个生成接口的公共参数：

| 参数 | 填写要求 | 说明 |
| --- | --- | --- |
| `model` | 必填 | `gpt-image-2.5-banana2`、`gpt-image-2.5-banana2.1` 或 `gpt-image-2.5-banana-pro`，见[可用模型](#models) |
| `prompt` | 必填 | 画面主体、场景和风格；图生图写编辑要求 |
| `size` | 可选 | `1K` / `2K` / `4K` 或 `宽x高`，规则见[尺寸与比例](#size)；省略为 1K 1:1 |
| `n` | 可选 | 只能为 `1` 或省略 |
| `response_format` | 可选 | 省略时返回 `url`（默认）；`b64_json` / `base64` 返回 Base64；`url` 返回链接。4K 建议使用 `url` |
| `quality` | 可选 | 可以传入，但不改变输出档位 |
| `generationConfig` | 可选 | 香蕉阶段参数，见 [generationConfig](#generation-config) |

### 3.1 文生图：JSON {#generations}

**接口：** `POST /v1/images/generations`，`Content-Type: application/json`。

``` json
{
  "model": "gpt-image-2.5-banana2.1",
  "prompt": "竖版音乐节海报，标题 SUMMER WAVE 2026，霓虹配色，排版清晰",
  "size": "2048x3072",
  "n": 1
}
```

`2048x3072` 为 2:3，最长边 3072，对应 2K 档。

### 3.2 图生图：上传文件 {#edits-multipart}

**接口：** `POST /v1/images/edits`，`multipart/form-data`。参考图使用 `image` 或 `image[]` 文件字段，每张图一个字段，最多 15 张；其余参数与文生图相同，以表单字段提交。前 6 张也会提供给香蕉重建步骤，用于还原文字、Logo、人脸等细节。

``` bash
curl --max-time 300 "https://yyds.seqnode.com/v1/images/edits" \
  -H "Authorization: Bearer $YM2API_KEY" \
  -F "model=gpt-image-2.5-banana2.1" \
  -F "prompt=保留图1的人物，采用图2的配色，白色背景" \
  -F "image[]=@reference-1.png" \
  -F "image[]=@reference-2.png" \
  -F "size=2048x2048" \
  -o response.json
```

### 3.3 图生图：图片 URL / Data URL {#edits-json}

**接口：** `POST /v1/images/edits`，JSON。参考图写入 `images[].image_url`，可为完整 Data URL 或公开 HTTPS 图片直链（链接需直接返回图片文件）。Data URL 参考图（最多 6 张）会同时提供给香蕉重建步骤；HTTPS 链接只用于 GPT 原图步骤。需要还原细节时优先使用 Data URL 或上传文件。本例显式请求 Base64 返回。

``` json
{
  "model": "gpt-image-2.5-banana2.1",
  "prompt": "保留图1的主体，采用图2的配色，白色背景",
  "images": [
    {"image_url": "https://YOUR_IMAGE_HOST/reference-1.png"},
    {"image_url": "data:image/png;base64,YOUR_REFERENCE_2_BASE64"}
  ],
  "size": "2048x2048",
  "n": 1,
  "response_format": "b64_json"
}
```

### 3.4 generationConfig：调整香蕉阶段（可选） {#generation-config}

`generationConfig` 为 Gemini 原生格式的对象，只合并到第二步（香蕉重建）的请求中，不影响第一步 GPT Image 2.5。JSON 请求直接传对象；multipart 请求在同名字段中传 JSON 字符串。

| 键 | 说明 |
| --- | --- |
| `thinkingConfig.thinkingLevel` | 思考档位，如 `"High"`。2.1 默认请求 Thinking High，实际是否生效取决于所分配的上游渠道；2.0 和 Pro 默认不发送，可用此键指定 |
| `temperature`、`topP`、`topK`、`seed` | 采样参数 |
| `imageConfig.imageSize` | `"1K"` / `"2K"` / `"4K"`，可代替 `size` 的档位 |
| `imageConfig.aspectRatio` | [支持的 10 种比例](#size-rules)之一，可代替 `size` 的比例 |

服务端规则：`responseModalities` 始终包含 IMAGE；`candidateCount` 被忽略，始终返回 1 张；`includeThoughts` 始终为 false。`imageConfig` 与 `size` 同时提供且不一致时返回 400（`conflicting_aspect_ratio` / `conflicting_image_size`）。JSON 无效、为数组或超过 16 KB 时返回 400 `invalid_generation_config`。

JSON 示例（2.1，Thinking High，temperature 0.7，2K 16:9，用 `imageConfig` 代替 `size`）：

``` json
{
  "model": "gpt-image-2.5-banana2.1",
  "prompt": "雨夜霓虹街道，招牌写着 \"OPEN 24H\"，电影感，细节清晰",
  "n": 1,
  "generationConfig": {
    "thinkingConfig": {
      "thinkingLevel": "High"
    },
    "temperature": 0.7,
    "imageConfig": {
      "imageSize": "2K",
      "aspectRatio": "16:9"
    }
  }
}
```

multipart 示例（2.0 开启思考，4K）：

``` bash
curl --max-time 300 "https://yyds.seqnode.com/v1/images/edits" \
  -H "Authorization: Bearer $YM2API_KEY" \
  -F "model=gpt-image-2.5-banana2" \
  -F "prompt=保留参考图的构图和文字，细节更清晰" \
  -F "image=@reference.png" \
  -F 'generationConfig={"thinkingConfig":{"thinkingLevel":"High"},"imageConfig":{"imageSize":"4K"}}' \
  -o response.json
```

### 3.5 不支持的用法 {#unsupported}

- 不支持流式返回（`stream`），传入会返回 400 `stream_not_supported`。
- 每次只生成 1 张；`n` 大于 1 会返回 400。需要多张时分多次请求。
- 不提供 Chat Completions、Responses、Messages 入口，只能使用上表中的 Images 接口。

## 4 尺寸、比例与实际输出 {#size}

### 4.1 size 的写法 {#size-rules}

- **`1K` / `2K` / `4K`：** 直接选择档位，比例为 1:1。
- **`宽x高`：** 例如 `2048x1152`。宽高用于推断比例和档位：最长边 ≤ 1600 为 1K；≤ 3200 为 2K；更大为 4K。单边上限 6000。
- **省略：** 1K 1:1。

支持的比例：1:1、3:2、2:3、4:3、3:4、5:4、4:5、16:9、9:16、21:9，允许约 3% 的误差。其他比例返回 400 `unsupported_aspect_ratio`，不会自动裁剪或拉伸。

| 想要的效果 | `size` 示例 |
| --- | --- |
| 1K 方图 | 省略，或 `1K`、`1024x1024` |
| 2K 横版 16:9 | `2048x1152` |
| 2K 竖版 2:3 | `2048x3072` |
| 4K 方图 | `4K` 或 `4096x4096` |
| 4K 横版 16:9 | `3840x2160` |
| 4K 竖版 9:16 | `2160x3840` |

### 4.2 实测输出像素 {#measured}

`size` 决定比例和档位，**实际像素以返回的图片为准**，不保证等于请求的宽高。以下为实测结果：

| 请求 | 实际输出 |
| --- | --- |
| 1K 1:1 | 1024×1024 |
| 2K 16:9（`2048x1152`） | 2752×1536 |
| 4K 1:1（`4096x4096`） | 4096×4096 |
| 4K 2:3 | 3392×5056 |
| 4K 3:2 | 5056×3392 |

需要精确尺寸时，下载后再自行缩放或裁剪。

## 5 读取响应与保存图片 {#response}

省略 `response_format` 或填 `"url"` 时的响应示例（链接为占位值）：

``` json
{
  "created": 1792242895,
  "data": [{"url": "https://img.yydsbest.com/YOUR_IMAGE_ID"}],
  "size": "2752x1536",
  "output_format": "png",
  "quality": "high"
}
```

- `data[0].url`：默认返回，本站图片链接，**保留 1 小时**，请及时下载。下载时不要携带 API Key。
- `data[0].b64_json`：显式填写 `response_format: "b64_json"`（或 `"base64"`）时返回 Base64，解码后保存。4K 的 Base64 响应可达 20--30 MB，4K 建议使用 `url`。
- `size`：实际输出像素。
- `output_format`：仅供参考，通常为 `jpeg`；经本站交付时文件可能是 PNG 编码。保存时按文件头判断：`89 50 4E 47` 为 PNG，`FF D8 FF` 为 JPEG。

快速开始的 Python / PowerShell 示例已包含下载、识别格式和保存步骤。

## 6 耗时、计费与超时 {#billing}

| 档位 | 常见耗时 |
| --- | --- |
| 1K | 约 60 秒 |
| 2K | 约 60--75 秒 |
| 4K | 约 90--105 秒 |

表中为 2.1 的常见耗时，2.0 通常更快。两步串行完成后才返回，耗时明显长于单次生图。客户端超时建议**不少于 300 秒**；超时后先查看使用记录，再决定是否重新提交，避免重复生成。

**计费：** 2.0 $0.05/张、2.1 $0.06/张、Pro $0.065/张（全分辨率同价），任一阶段失败不扣费。实际扣费以使用记录为准。

## 7 错误码 {#errors}

错误响应为 JSON，读取 `error.message`，有 `error.code` 时按下表处理。部分参数（如 `n`、宽高比）可能由网关先行校验，此时响应只有 `error.type`、`error.message` 和 `error.request_id`，没有 `code`，按 HTTP 状态和提示信息处理。

| HTTP | `error.code` | 原因与处理 |
| --- | --- | --- |
| 400 | `invalid_model` | 模型名不是 `gpt-image-2.5-banana2`、`gpt-image-2.5-banana2.1` 或 `gpt-image-2.5-banana-pro`，见[可用模型](#models) |
| 400 | `invalid_image_count` | `n` 不是 1；改为 1 或省略 |
| 400 | `stream_not_supported` | 去掉 `stream` |
| 400 | `invalid_image_size` | `size` 格式错误或单边超过 6000 |
| 400 | `conflicting_aspect_ratio` | `generationConfig.imageConfig.aspectRatio` 与 `size` 的比例不一致；只保留一处 |
| 400 | `conflicting_image_size` | `generationConfig.imageConfig.imageSize` 与 `size` 的档位不一致；只保留一处 |
| 400 | `invalid_generation_config` | `generationConfig` 不是有效 JSON 对象（含数组）或超过 16 KB |
| 400 | `unsupported_aspect_ratio` | 比例不在支持列表中；改用[支持的比例](#size-rules) |
| 400 | `missing_prompt` | `prompt` 为空 |
| 400 | `missing_image` | 调用 `/v1/images/edits` 但没有参考图 |
| 400 | `invalid_image_request` | 原图请求参数有误；按 `message` 修改 |
| 400 | `image_safety_rejected` | 未通过图片安全检查；调整提示词或参考图 |
| 413 | `image_too_large` | 上传的参考图过大；压缩后重试 |
| 429 | `image_channel_busy` | 渠道繁忙；稍后重试并降低并发 |
| 502 | `image_generation_failed` | GPT 原图生成失败；稍后重试 |
| 502 | `banana_rebuild_failed` | 香蕉重建失败；稍后重试 |
| 502 | `image_upstream_error` | 渠道暂时异常；稍后重试 |
| 504 | `image_generation_timeout` | 生成超时；先核对使用记录再重试 |

401 / 403 时检查 Bearer Key 是否正确、是否绑定 177 分组。排查时提供模型、请求时间、HTTP 状态和 `request_id`；不要把 API Key 放入截图或公开日志。

## 8 效果说明与已知限制 {#limits}

以下来自 GPT 原图与重建结果的对比测试：

- **适合：** 人像、动漫、排版海报和清晰文字。构图、人物身份、画风和可辨认的文字（中、日、英）基本保留，并更清晰。
- **把要的文字写进提示词：** 重建步骤会读取原始 `prompt`，用它把画面中的文字拼写正确。请用引号写明确切文字，例如：招牌上写着 "OPEN 24H"。
- **图生图细节：** 上传文件或 Data URL 参考图（前 6 张）会提供给重建步骤，Logo、文字、人脸和细节按参考图还原；`https://` 链接参考图不参与重建。
- **未写明的小字仍有风险：** 提示词中写明的文字风险已降低。原图中模糊的小字，如果提示词和参考图都无法确定，会保持模糊而不是编造；但提示词未提及的极小文字或数字（表盘、包装小字等）仍可能与原意不一致。
- **色调：** 整体可能轻微偏暖。
- **精密细节：** 产品外观、包装文字、标识等需要准确还原的内容，建议逐项核对；必要时直接使用[香蕉 2.1](group139-banana21-api.html)按目标档位生成。

[效果对比示例（6 组提示词，原图 / 插值 / 香蕉 2K / 4K）](compare/image2-banana21-v2/index.html)

[与 GPT Image 2.5 Flare / Sunburst 4K 对比（4 组提示词）](compare/banana-vs-flare-sunburst/index.html)

需要逐像素忠实放大时，本分组不适用。