在实际业务开发中,同时接入 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. 参数分层架构:哪些参数适合统一封装?
在构建统一生图客户端时,建议将请求参数划分为三层体系,职责清晰分离:

| 参数分层 | 涉及字段与业务意图 | 封装与适配策略 |
|---|---|---|
| 请求基础层 | 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 载体中,所有扩展字段均位于请求体根节点。

对应的标准 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 数组的长度判断组图成功:
- 提示词防拼图:部分生图模型倾向于输出一张包含多宫格的分栏拼图,提示词中需明确声明“生成独立图片、非拼图分栏”。
- 内容哈希去重:部分并发生成或重试机制下,接口返回的多条记录可能指向相同 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 在执行耗时和成本上存在显著差异,生产环境需特别关注以下三点:
- 出图成功判断口径:
- 不要仅依赖 HTTP 200:必须检查响应体中
data数组非空,且每一项包含非空url或b64_json。 - 图片转储:API 返回的临时 URL 具备失效时限,后端应立即异步下载并将图片转存至自建对象存储(如 OSS / COS / S3)。
- 不要仅依赖 HTTP 200:必须检查响应体中
- 长连接与超时控制:
- 生图任务往往需要 10~60 秒,复杂任务甚至可能达数分钟。客户端必须设置充分的 HTTP 读超时(建议 $\ge 300$ 秒)。
- 关闭客户端自动重试:网络层单方面中断超时并不意味着模型服务已停机。盲目重试会导致多张图片并发生成及重复扣费。
- 架构异步解耦:
- 面向终端用户的 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,但生成的普通白底图违背了用户的核心任务诉求。