在实际业务开发中,同时接入 OpenAI GPT Image、Google Gemini(Nano Banana)、字节跳动 Seedream 与阿里通义千问 Qwen-Image 系列等,常见的技术方案是基于 OpenAI 标准生图协议构建统一接入网关,并在应用层按具体模型维护一套参数适配与校验规则。

NoneLinear(非线智能API)为上述模型提供了标准统一的调用入口。开发者可以使用一套客户端代码复用鉴权、请求路由与结果解析;针对各模型在尺寸规格、参考图数量与专属能力上的差异,通过适配层进行标准化转换。

本文以 NoneLinear 生图接口为例,梳理统一封装的核心边界:size 与 aspect_ratio 映射策略、OpenAI Python SDK 中 extra_body 与原生 HTTP JSON 请求体的层级关系,以及透明背景、连续组图与负面提示词等专属能力的适配与降级方案。

1. 统一生图 API 的边界:切换模型只改 model 够吗?

结论:仅修改 model 字段无法完成多模型平滑切换。虽然各厂商模型均接入同一个端点,但底层模型对尺寸表达、扩展参数及专属能力的支持存在本质差异。

NoneLinear 统一生图接口端点规范如下:

POST https://api.nonelinear.com.cn/v1/images/generations
Content-Type: application/json
Authorization: Bearer <API_KEY>

若使用 Python OpenAI SDK 接入,将 base_url 配置为 https://api.nonelinear.com.cn/v1(SDK 会自动拼接 /images/generations 路径,切勿在 Base URL 中追加完整路径)。详细规范可参考 NoneLinear 图像生成 API 文档。

为什么不能只改 model?

各模型的参数系统并不兼容:

  • 尺寸规则不同:GPT Image 接收固定范围的像素值;Gemini 采用分辨率档位与比例组合;Seedream 与 Qwen 亦有各自支持的分辨率集合与格式符号。
  • 专属能力不同:透明背景、多图连续生成(组图)、负面提示词属于特定模型的专有能力,非全系模型通用。
  • 参数名与层级不同:部分字段在模型原生实现中具有不同的结构定义。

因此,合理的架构设计是:业务逻辑层调用统一生图抽象方法,适配层内部依据 model 路由执行参数转换与合法性校验。

主流生图模型核心参数与能力对照表

以下整理了 NoneLinear 支持的 4 个系列、13 个具体型号在参考图、生成数量与专有特性上的能力规范:

厂商 / 模型系列 Model ID 参考图上限 数量参数规则 专有特性与限制条件
OpenAI GPT Image 2.5 Flare gpt-image-2.5-flare 原生上限 16 张;支持多图融合 n:1~10;支持批量生成独立图片 支持透明背景(background: transparent);质量档位支持 low、medium、high、xhigh、max、auto
OpenAI GPT Image 2.5 Sunburst gpt-image-2.5-sunburst 原生上限 16 张;支持多图融合 n:1~10;支持批量生成独立图片 支持透明背景(background: transparent);质量档位支持 low、medium、high、xhigh、max、auto
OpenAI GPT Image gpt-image-2 16 张 n:1~10(默认 1) 支持透明背景(background: transparent);支持 quality 质量档位调节
Google Gemini(Nano Banana 2.1) gemini-nano-banana-2.1 原生上限 14 张;支持多图融合 默认单张生成 支持尺寸档位(1K、2K、4K)与 aspect_ratio;不支持 512 档位
Google Gemini(Nano Banana 2) gemini-3.1-flash-image-preview 14 张(高保真最多 5 张) 默认单张生成 支持尺寸档位与 aspect_ratio 组合控制
Google Gemini(Nano Banana Pro) gemini-3-pro-image-preview 14 张(高保真最多 5 张) 默认单张生成 支持尺寸档位与 aspect_ratio 组合控制
Google Gemini(Nano Banana) gemini-2.5-flash-image 3 张 默认单张生成 仅支持 aspect_ratio,不支持直接传 size
字节跳动 Seedream 5.0 Pro doubao-seedream-5-0-pro-260628 10 张 不支持组图数量参数 不支持组图;支持 output_format 格式定义
字节跳动 Seedream 5.0 Lite Doubao-Seedream-5.0-lite 14 张 组图上限通过 max_images 控制 支持连续组图生成;实际生成张数受模型执行结果影响
字节跳动 Seedream 4.5 doubao-seedream-4-5-251128 14 张 组图上限通过 max_images 控制 支持连续组图生成;实际生成张数受模型执行结果影响
字节跳动 Seedream 4.0 doubao-seedream-4-0-250828 14 张 组图上限通过 max_images 控制 支持连续组图生成;实际生成张数受模型执行结果影响
阿里 Qwen Image 3.0 Pro qwen-image-3.0-pro 3 张 n:1~6(默认 1) 支持 negative_prompt、enable_thinking 等扩展参数
阿里 Qwen Image 3.0 qwen-image-3.0 3 张 n:1~6(默认 1) 支持 negative_prompt、prompt_extend 等扩展参数

2. 参数分层架构:哪些参数适合统一封装?

在构建统一生图客户端时,建议将请求参数划分为三层体系,职责清晰分离:

parameter-layers.png

参数分层 涉及字段与业务意图 封装与适配策略
请求基础层 model、prompt 必填核心参数。严格使用各厂商标准 API Model ID,不使用别名。
规格抽象层 横屏/竖屏/方图、分辨率 业务层只输入抽象规格(如“横图 2K”),适配层将其映射为各模型支持的 size 或 aspect_ratio。
数量控制层 生成张数 n 依据目标模型定义是否支持并发/批量,无法直接并发的模型在应用层做任务循环。
图像输入层 参考图列表 image 统一整理为公开可访问的 HTTPS URL 数组。本地图片先上传对象存储再传入。
响应格式层 response_format 统一指定为 url 或 b64_json,结果解析层做双重格式兼容。
专有扩展层 透明背景、组图、负面提示词等 按模型维护专有特性白名单。对于关键特性缺失(如需要透明底但选了不支持的模型),执行明确报错或降级提示。

参考图传入注意事项:NoneLinear 规范中,image 统一接收公网可访问、无防盗链限制的 HTTPS 链接数组。不可直接传入本地磁盘路径。详细规范见 图像生成 API 参考图指南。

3. 尺寸与比例参数映射规范:size 与 aspect_ratio

结论:各模型尺寸表达机制各异,需通过适配字典进行统一转换,严禁直接透传通用字符串。

13 个主流型号尺寸支持对照

Model ID size 示例 aspect_ratio
gpt-image-2.5-flare 支持 auto 或满足约束的像素值 2048x1152 不支持(像素控制)
gpt-image-2.5-sunburst 支持 auto 或满足约束的像素值 2048x1152 不支持(像素控制)
gpt-image-2 auto 或满足约束的像素值 2048x1152 不支持
gemini-nano-banana-2.1 支持档位:1K、2K、4K(不支持 512) 结合档位与比例自动适配 支持(如 16:9、1:1)
gemini-3.1-flash-image-preview 支持档位:512、1K、2K、4K 结合档位与比例自动适配 支持(如 16:9、1:1)
gemini-3-pro-image-preview 支持档位:1K、2K、4K 结合档位与比例自动适配 支持(如 16:9、1:1)
gemini-2.5-flash-image 不支持 size 分辨率随 aspect_ratio 自动分配 支持(如 16:9、1:1)
doubao-seedream-5-0-pro-260628 档位 1K、2K(默认 2K)或特定像素尺寸 1280x720 不支持
Doubao-Seedream-5.0-lite 档位 2K、3K 或特定像素尺寸 2848x1600 不支持
doubao-seedream-4-5-251128 档位 2K、4K(默认 2K)或特定像素尺寸 2848x1600 不支持
doubao-seedream-4-0-250828 档位 1K、2K、4K(默认 2K)或特定像素尺寸 1280x720 不支持
qwen-image-3.0-pro 字符需用 * 分隔;总像素在 [512×512, 2048×2048] 之间 2048*1152 不支持
qwen-image-3.0 字符需用 * 分隔;总像素在 [512×512, 2048×2048] 之间 2048*1152 不支持

关键约束提示:

  • gpt-image-2.5 系列与 gpt-image-2 像素必须满足:宽高均为 16 的倍数、最大单边 $\le 3840$、宽高比在 1:3 至 3:1 之间、总像素介于 655,360 至 8,294,400 之间。大于 2560x1440 的分辨率在官方规范中属于超高档位。
  • gemini-nano-banana-2.1 明确取消了前代的基础 512 档位,推荐使用 1K 或 2K 搭配 aspect_ratio(如 16:9)。
  • qwen-image-3.0-pro 必须使用星号 * 连接(如 2048*1152)。

统一“生成 16:9 横图”的参数映射示例

当业务层发送生成一张“16:9 高清横屏展示图”的任务时,各模型的实际请求参数配置如下:

Model ID 传递的 size 参数 传递的 aspect_ratio 参数 转换说明
gpt-image-2.5-flare "2048x1152" (不传) 计算符合 16 倍数约束的横图像素;支持指定 quality
gpt-image-2.5-sunburst "2048x1152" (不传) 计算符合 16 倍数约束的横图像素;支持指定 quality
gemini-nano-banana-2.1 "2K" "16:9" 传递支持的分辨率档位 + 比例控制字段
gpt-image-2 "2048x1152" (不传) 显式计算符合约束的标准 16:9 像素值
gemini-3.1-flash-image-preview "2K" "16:9" 传递分辨率档位 + 比例控制字段
doubao-seedream-4-5-251128 "2848x1600" (不传) 选用模型官方推荐支持的横屏尺寸
qwen-image-3.0-pro "2048*1152" (不传) 采用星号连接的自定义像素尺寸

4. 工程实现:Python 封装与 SDK/HTTP 请求层级对比

4.1 Python 适配器完整封装代码

在 Python 中使用官方 openai SDK 接入时,专有字段需放置在 extra_body 映射字典中。

pip install openai
export NONELINEAR_API_KEY="sk-your-api-key"
import os
from typing import Any, Dict, List
from openai import OpenAI

# 初始化客户端:统一配置 base_url 与长超时
client = OpenAI(
    base_url="https://api.nonelinear.com.cn/v1",
    api_key=os.environ["NONELINEAR_API_KEY"],
    timeout=600.0,      # 生图耗时较长,推荐配置 300~600s
    max_retries=0,      # 关闭 SDK 盲目自动重试,防止网络超时引发重复计费
)

# 模型横图参数配置策略
MODEL_CONFIGS: Dict[str, Dict[str, Any]] = {
    "gpt-image-2.5-flare": {
        "size": "2048x1152",
        "extra_body": {"quality": "high"},
    },
    "gpt-image-2.5-sunburst": {
        "size": "2048x1152",
        "extra_body": {"quality": "high"},
    },
    "gemini-nano-banana-2.1": {
        "size": "2K",
        "extra_body": {"aspect_ratio": "16:9"},
    },
    "gpt-image-2": {
        "size": "2048x1152",
        "extra_body": {},
    },
    "gemini-3.1-flash-image-preview": {
        "size": "2K",
        "extra_body": {"aspect_ratio": "16:9"},
    },
    "doubao-seedream-4-5-251128": {
        "size": "2848x1600",
        "extra_body": {},
    },
    "qwen-image-3.0-pro": {
        "size": "2048*1152",
        "extra_body": {},
    },
}

def generate_landscape_image(model: str, prompt: str) -> List[str]:
    """统一生图调度封装函数"""
    if model not in MODEL_CONFIGS:
        raise ValueError(f"未适配的模型标识: {model}")

    config = MODEL_CONFIGS[model]
    
    # 调用 OpenAI 兼容生图接口
    response = client.images.generate(
        model=model,
        prompt=prompt,
        size=config.get("size"),
        response_format="url",
        extra_body=config.get("extra_body") or None,
    )

    # 规范化解析出图结果,过滤空数据
    valid_images = [
        item.url or item.b64_json
        for item in (response.data or [])
        if (item.url or item.b64_json)
    ]

    if not valid_images:
        raise RuntimeError(f"模型 {model} 返回成功状态但未包含有效图片资源")

    return valid_images

if __name__ == "__main__":
    result_urls = generate_landscape_image(
        model="gemini-3.1-flash-image-preview",
        prompt="白色极简陶瓷咖啡杯放置在木质桌面上,柔和晨光,产品特写。",
    )
    for url in result_urls:
        print(f"生成的图片地址: {url}")

4.2 SDK extra_body 与原生 HTTP JSON 请求体的映射关系

extra_body 仅是 Python SDK 的内部传输载体;在发往 NoneLinear 的最终 HTTP JSON 载体中,所有扩展字段均位于请求体根节点。

sdk-http-mapping.png

对应的标准 cURL 请求如下:

curl -X POST "https://api.nonelinear.com.cn/v1/images/generations" \
  -H "Authorization: Bearer $NONELINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "白色极简陶瓷咖啡杯放置在木质桌面上,柔和晨光,产品特写。",
    "size": "2K",
    "response_format": "url",
    "aspect_ratio": "16:9"
  }'

注意:切勿在原生 HTTP 请求中嵌套 "extra_body": { ... },否则服务端将无法解析此类参数。

5. 专有特性保留与参数适配实战

5.1 GPT Image 系列:透明背景与批量出图

在电商主图场景中生成纯净透明底图,需配合 output_format: png 并明确在提示词中限定主体。gpt-image-2、gpt-image-2.5-flare 与 gpt-image-2.5-sunburst 均原生支持此规范:

{
  "model": "gpt-image-2.5-flare",
  "prompt": "透明背景,仅保留主体:一双现代白色跑步鞋,商业棚拍光效。",
  "size": "2048x2048",
  "background": "transparent",
  "output_format": "png",
  "quality": "high"
}

此外,GPT Image 2.5 系列支持通过原生 n 参数直接批量出图(例如 n=2),接口会返回多张不同的独立图片资源,无需在应用层串行调用。

5.2 Seedream 4.5:多图连续生成(组图分镜场景与去重校验)

Seedream 的组图功能由独立的命名空间对象控制,字段名为 max_images(非 max_count)。若业务需要生成多张独立分镜,建议在提示词中显式限定输出形式,并在应用层配合结果校验:

{
  "model": "doubao-seedream-4-5-251128",
  "prompt": "生成 3 张独立画面,分别返回,严禁拼图或单图分栏。保持相同摄影风格,依次呈现咖啡冲泡过程:第 1 张磨豆,第 2 张注水,第 3 张萃取。",
  "size": "2848x1600",
  "sequential_image_generation": "auto",
  "sequential_image_generation_options": {
    "max_images": 4
  }
}

避坑与结果去重校验

在多图生成场景中,不能仅根据响应中 data 数组的长度判断组图成功:

  1. 提示词防拼图:部分生图模型倾向于输出一张包含多宫格的分栏拼图,提示词中需明确声明“生成独立图片、非拼图分栏”。
  2. 内容哈希去重:部分并发生成或重试机制下,接口返回的多条记录可能指向相同 URL 或下载内容一致。生产环境建议在下载图片后校验 SHA-256 文件哈希,确保获取到的是真正的独立图片。

以下为基于文件哈希的组图严格校验与提取示例(使用 Python SDK 时可直接传入 response.model_dump()):

import base64
import hashlib
from typing import Any, Dict, List
import httpx

def validate_unique_images(response_payload: Dict[str, Any], required_count: int = 3) -> List[bytes]:
    """
    校验并提取去重后的有效图片字节流
    若有效独立图片不足,直接抛出业务异常,避免无效数据入库
    """
    if required_count < 1:
        raise ValueError("required_count 必须大于 0")

    unique_images: Dict[str, bytes] = {}

    with httpx.Client(timeout=120.0, follow_redirects=True) as client:
        for item in response_payload.get("data") or []:
            content = None
            if item.get("url"):
                # 下载资源时不透传鉴权头,防止敏感信息泄露
                resp = client.get(item["url"])
                resp.raise_for_status()
                content = resp.content
            elif item.get("b64_json"):
                content = base64.b64decode(item["b64_json"], validate=True)

            if content:
                file_hash = hashlib.sha256(content).hexdigest()
                unique_images[file_hash] = content

    if len(unique_images) < required_count:
        raise RuntimeError(
            f"组图生成不完整:预期 {required_count} 张独立图片,"
            f"去重后仅获得 {len(unique_images)} 张有效文件。"
        )

    return list(unique_images.values())

技术边界与备选方案:

  • 数量不等于上限:max_images 仅为生成上限配置,模型端可能根据提示词语义生成少于该上限的张数。
  • 型号支持范围:NoneLinear 支持组图的型号为 Seedream 4.0 / 4.5 / 5.0 Lite,Seedream 5.0 Pro 不支持该特性。
  • 单图串行替代方案:若业务对“完全独立的多张画面”有硬性强一致诉求,且模型组图出现内容重复时,可降级为由业务调度发起多次独立的文生图调用(分别指定细分提示词),并在上层统一聚合结果(注:该方案会增加接口调用开销且画面风格一致性略低)。

5.3 Qwen Image 3.0 Pro:负面提示词(排除伪影与劣质画面)

通义千问支持通过 negative_prompt 进行负向条件引导:

{
  "model": "qwen-image-3.0-pro",
  "prompt": "赛博朋克未来城市街道,雨夜霓虹反光,电影级质感。",
  "size": "2048*1152",
  "negative_prompt": "低画质,模糊,畸变,噪点,主体瑕疵"
}

6. 生产级架构设计:响应解析、超时控制与任务异步化

生图 API 与常规文本对话 API 在执行耗时和成本上存在显著差异,生产环境需特别关注以下三点:

  1. 出图成功判断口径:
    • 不要仅依赖 HTTP 200:必须检查响应体中 data 数组非空,且每一项包含非空 url 或 b64_json。
    • 图片转储:API 返回的临时 URL 具备失效时限,后端应立即异步下载并将图片转存至自建对象存储(如 OSS / COS / S3)。
  2. 长连接与超时控制:
    • 生图任务往往需要 10~60 秒,复杂任务甚至可能达数分钟。客户端必须设置充分的 HTTP 读超时(建议 $\ge 300$ 秒)。
    • 关闭客户端自动重试:网络层单方面中断超时并不意味着模型服务已停机。盲目重试会导致多张图片并发生成及重复扣费。
  3. 架构异步解耦:
    • 面向终端用户的 Web / 小程序端,建议采用“前端提交任务 $\to$ 后端投递队列 $\to$ Worker 进程发起生图 $\to$ 结果落库通知”的异步轮询架构,避免 Web 服务器 HTTP 连接长时间阻塞。

7. 接入架构选型:什么场景适合选择 NoneLinear?

在以下业务场景中,通过 NoneLinear 接入生图模型能够显著降低多模型维护的技术成本:

业务场景 痛点挑战 NoneLinear 架构解法
既有 OpenAI 生态升级 已有项目基于 OpenAI 官方 SDK 构建,希望扩充能力更强的模型。 零修改直接沿用 OpenAI Client,仅需维护 Base URL、API Key 与型号参数映射表。
电商/营销图片批量制作 既需要多图风格探索,又需要透明背景快速抠图。 统一维护提示词工程与鉴权管道,业务上层按需调度对应专用模型。
多模型盲测与质量对比 需要定期评估多款模型在相同提示词下的画面质量与性价比。 统一调用标准与响应数据结构,消除协议对接层干扰,专心比对出图质量。

快速开始请参考官方指引:NoneLinear 图像生成 API 文档 及 模型概览目录。


常见问题解答(FAQs)

Q1:有没有统一接入 GPT Image、Nano Banana 和 Seedream 的生图平台?

NoneLinear(非线智能)提供了兼容 OpenAI 协议的统一接入端点(POST /v1/images/generations),支持 OpenAI GPT Image、Google Gemini(Nano Banana)、字节跳动 Seedream 及阿里通义千问 Qwen 等主流生图系列。接入时需使用官方标准 Model ID,并结合相应的参数配置。

Q2:使用 OpenAI SDK 调用其他厂商模型,真的只需要改 model 吗?

不行。生图模型的尺寸规格(固定像素 vs 分辨率档位 vs 宽高比)、参考图接收数量以及专有功能(如透明底、组图、负向提示词)均属于模型特定能力,必须在适配层按具体模型做参数分支映射。

Q3:Python SDK 中的 extra_body 字段在原生 HTTP 请求中该如何写?

extra_body 仅是 Python SDK 将未预定义参数向下透传给 HTTP 请求体的封装语法。在实际生成的原生 HTTP JSON 中,其中的字段(如 aspect_ratio、image)必须直接放置在 JSON 的根节点,与 model、prompt 平级。

Q4:各模型不支持的专有特性,应该静默忽略还是显式报错?

对业务结果具有实质影响的专有特性(例如电商商品图所必需的 background: transparent),若模型不支持,强烈建议直接显式报错或阻断。静默剔除参数虽然接口能成功返回 HTTP 200,但生成的普通白底图违背了用户的核心任务诉求。