SUPER-RESOLUTION IMAGE

超分生图

使用 gpt-image-2-superres、gpt-image-2.5-flare-superres、gpt-image-2.5-sunburst-superres 和 Gemini 超分生图模型生成 1K、2K、4K 图片，了解参考图、质量参数和编辑限制。

最后验证：2026-09-15

RootFlowAI 的超分生图分组提供 1K、2K、4K 输出，适合需要更大成品尺寸、更多可见细节或后续排版裁切的场景。该分组提供目标像素尺寸的超分输出，不宣传为原生 2K/4K 采样：文件尺寸达到目标像素，不等于上游使用了同等尺寸的原生采样画布。

创建 API Key 时选择对应分组：

GPT 模型选择 GPT 超分生图
Gemini 模型选择 Gemini 超分生图

两个分组协议完全独立。GPT 使用 OpenAI Images API；Gemini 使用原生 generateContent API，不能混用请求格式。

可用模型

分组	对外模型	协议	输出档位
GPT 超分生图	`gpt-image-2-superres`	OpenAI Images	1K / 2K / 4K
GPT 超分生图	`gpt-image-2.5-flare-superres`	OpenAI Images	1K / 2K / 4K
GPT 超分生图	`gpt-image-2.5-sunburst-superres`	OpenAI Images	1K / 2K / 4K
Gemini 超分生图	`gemini-3-pro-image-preview-superres`	Gemini `generateContent`	1K / 2K / 4K
Gemini 超分生图	`gemini-3.1-flash-image-preview-superres`	Gemini `generateContent`	1K / 2K / 4K

gpt-image-2.5-flare-superres 和 gpt-image-2.5-sunburst-superres 是两个对外模型名，当前都调用 Pandatk 的 gpt-image-2.5 上游模型。

GPT 超分生图

质量参数

gpt-image-2-superres、gpt-image-2.5-flare-superres 和 gpt-image-2.5-sunburst-superres 当前都以统一的 medium 策略生成。接口接受常见的 quality 参数，用于兼容 OpenAI Images 客户端，但参数不会切换实际质量档位：

请求参数	实际策略	说明
不传 `quality`	medium	默认策略
`quality=high`	medium	接受参数，实际仍为 medium
`quality=medium`	medium	接受参数，实际仍为 medium
`quality=low`	medium	接受参数，实际仍为 medium

上述三个公开模型都接受 low、medium、high 参数。其他 quality 值会直接返回 400，不会改走其他模型或其他渠道。传入的 quality 只用于接口兼容，不代表上游质量档位发生变化。

文生图

curl https://api.rootflowai.com/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
  -d '{
    "model": "gpt-image-2.5-flare-superres",
    "prompt": "高端腕表广告，黑色背景，金属机芯细节清晰，棚拍光线",
    "quality": "high",
    "size": "2048x2048",
    "n": 1
  }'

size 直接使用像素格式。以下正方形和横图尺寸已验证可用：

档位	正方形示例	横图示例
1K	`1024x1024`	`1536x1024`
2K	`2048x2048`	`2048x1152`
4K	`2880x2880`	`3840x2160`

成功后返回 OpenAI Images 格式，图片会保存到 RootFlowAI CDN：

{
  "created": 1786437000,
  "data": [
    {
      "url": "https://cdn.rootflowai.com/images/2026-09-15/example.png"
    }
  ]
}

响应通常从 data[0].url 读取图片 URL。usage 可能不存在，调用方不要依赖它一定返回。

注意：部分正方形输出的 URL 后缀和 CDN Content-Type 为 image/png，但下载后的文件头实际可能是 JPEG。需要判断文件类型时，请检查响应头或文件头，不要只根据 URL 后缀判断。

参考图生成

参考图生成使用 /v1/images/generations 的 JSON image 数组。参考图可以是公网图片 URL，也可以是带 MIME 类型的 Data URI：

curl https://api.rootflowai.com/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
  -d '{
    "model": "gpt-image-2.5-sunburst-superres",
    "prompt": "保留参考图中的主体和整体构图，只把背景改成深色高级棚拍风格",
    "quality": "high",
    "size": "2048x2048",
    "n": 1,
    "image": ["https://example.com/reference.png"]
  }'

参考图生成已在 GPT 超分的两个 Pandatk 上游模型（gpt-image-2 和 gpt-image-2.5）上验证。两个 GPT-Image-2.5 公开别名共享 gpt-image-2.5 上游，因此使用相同的参考图请求格式。它属于参考图引导生成，不保证未修改区域逐像素不变。

本地编辑与蒙版

当前 GPT 超分模型不支持需要上游处理图片像素的本地编辑或蒙版合成。对上述 GPT 超分公开模型发送 /v1/images/edits 并附带 mask 时，接口会返回 400，错误信息为 mask compositing is disabled because the VPS does not process image pixels。

因此，超分模型不要使用本地 multipart/form-data 蒙版编辑流程；需要使用参考图时，请改用上面的 /v1/images/generations + image 数组方式。

Gemini 超分生图

Gemini 分组保留原生协议。模型名位于 URL 中，分辨率通过 generationConfig.imageConfig.imageSize 指定。

文生图

curl "https://api.rootflowai.com/v1beta/models/gemini-3-pro-image-preview-superres:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: sk-xxxxxxxxxxxxxxxx" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "高端腕表广告，黑色背景，金属机芯细节清晰，棚拍光线" }
        ]
      }
    ],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {
        "aspectRatio": "1:1",
        "imageSize": "4K"
      }
    }
  }'

imageSize 支持 1K、2K、4K。常用比例包括 1:1、3:2、2:3、4:3、3:4、16:9、9:16；Flash 模型还支持 8:1、4:1、1:4、1:8 等长图比例。

Gemini 原生响应中的图片位于 candidates[].content.parts[].inlineData.data，内容是 base64。该分组不把响应转换为 OpenAI Images URL：

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "iVBORw0KGgoAAA..."
            }
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 202,
    "candidatesTokenCount": 2000,
    "totalTokenCount": 2202
  }
}

参考图

把参考图作为原生 inlineData part 与提示词一起发送。单次请求最多建议使用 14 张参考图：

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "保持产品结构，只替换背景和灯光" },
        {
          "inlineData": {
            "mimeType": "image/png",
            "data": "BASE64_IMAGE_DATA"
          }
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"],
    "imageConfig": {
      "aspectRatio": "1:1",
      "imageSize": "2K"
    }
  }
}

超时与失败处理

1K/2K 通常需要几十秒，4K 可能需要数分钟，客户端完整请求超时建议设置为 900 秒。
生图请求可能已经进入上游队列。连接中断、网关超时或未知响应时，不要自动重试，以免产生重复任务和重复计费。
quality=low、medium、high 目前只是兼容参数，不能用来判断实际质量档位或 token 消耗。
内容审核错误不会自动降级到旧渠道或其他模型。
Gemini Pro 4K 曾观察到临时不可用错误；业务侧应把失败明确返回给用户，不要静默切换模型。