全面掌握 gpt-image-2 接口：文生图与图生图 API 接入实战指南

在当前的 AI 浪潮中，将强大的图像生成能力无缝集成到业务系统中已成为许多开发者的核心需求。为了帮助大家更高效地完成对接，本文将系统性地梳理 GPT-image-2 模型的 API 接入流程，涵盖文生图、图生图（参考图）接口的详细说明、返回格式解析，以及系统内字段到 API 字段的精准映射关系。

本文转载自积木AI文档，中转站：https://ai.yiqiu.dev/register?aff=RJwe

一、在线画布直观演示

在进入硬核的代码调用前，我们可以先通过在线画布了解该模型的实际表现：

二、核心 API 接口调用说明

1. 文生图接口 (Text-to-Image)

当您的业务场景 不需要提供参考图 时，请直接调用此接口进行文字生成图片的操作。

请求端点：POST https://txt.com/v1/images/generations

Content-Type：application/json

鉴权方式： Authorization: Bearer

请求体示例：

{
"model": "gpt-image-2",
"prompt": "一只坐在窗边的橘猫，电影感光影",
"background": "auto",
"quality": "auto",
"size": "1024x1024",
"output_format": "png"
}

核心参数解析：

参数	类型	必填	默认值	说明
model	string	是	gpt-image-2	图片模型 ID。
prompt	string	是	-	图片生成提示词。
background	string	否	auto	系统固定传 auto。
quality	string	否	auto	可选值：auto、high。
size	string	否	auto	详见下方“尺寸列表”。
output_format	string	否	png	系统固定传 png。
n	number	否	-	生成数量，系统侧按 1-10 处理；大于 1 时才需传参。

支持的尺寸列表 (size)：

auto：自动适配
1024x1024：常规方形
1536x1024：常规横版
1024x1536：常规竖版
2048x2048：2K 方形
2048x1152：2K 横版
3840x2160：4K 横版
2160x3840：4K 竖版

注意：系统已兼容部分比例写法（如 16:9 会自动转换为 2048x1152），但建议直接传入英文小写 x 格式的精确尺寸（例如 1024x1024，切勿写成 1024×1024）。

2. 图生图 / 参考图接口 (Image-to-Image)

当业务场景 需要参考图 辅助生成时，请务必切换至此接口。切记不要将参考图放进文生图接口的 JSON body 中。

请求端点： POST https://txt.com/v1/images/edits

Content-Type： multipart/form-data

鉴权方式： Authorization: Bearer

前端表单数据 (FormData) 构建示例：

const formData = new FormData();
formData.append('model', 'gpt-image-2');
formData.append('prompt', '保持主体不变，改成水彩插画风格');
formData.append('background', 'auto');
formData.append('quality', 'auto');
formData.append('size', '1024x1024');
formData.append('output_format', 'png');
formData.append('image[]', imageBlob, 'reference-1.png');

cURL 调用示例（单张参考图）：

curl https://txt.com/v1/images/edits 
-H "Authorization: Bearer" 
-F "model=gpt-image-2" 
-F "prompt=保持主体不变，改成水彩插画风格" 
-F "background=auto" 
-F "quality=auto" 
-F "size=1024x1024" 
-F "output_format=png" 
-F "image[]=@reference-1.png"

如果您需要传入多张参考图，只需在请求中多次追加 -F "image[]=@您的图片路径" 即可。

三、响应结构与返回格式解析

接口具备灵活的返回能力，支持输出图片直链 url 或 Base64 编码 b64_json。开发者在处理返回值时应兼容这两种字段。

URL 返回示例：

{
"data": [
{
"url": "https://example.com/generated.png"
}
]
}

Base64 返回示例：

{
"data": [
{
"b64_json": "..."
}
]
}

四、系统内字段映射关系速查

为了方便对接内部系统，以下整理了内部系统字段到标准化 API 字段的映射逻辑：

系统字段	API 字段	处理逻辑说明
prompt	prompt	提示词直接透传。
model	model	默认锁定 gpt-image-2。
aspectRatio	size	系统会在底层先将比例转换为标准尺寸像素。
count / n	n	生成数量控制。
referenceImages	image[]	检测到此字段时，自动路由至 /images/edits 接口。
uploadedImages	image[]	系统先提取图片 URL，将其转储后作为参考图上传处理。

五、最佳实践与推荐调用策略

针对日常研发和业务诉求，我们总结了以下几条黄金调用法则：

接口路由明确化： 无参考图一律走 /v1/images/generations；有参考图务必走 /v1/images/edits。
尺寸参数自动化： 不确定具体需要多大尺寸时，直接传入 size: "auto"。
常用版式尺寸： 建议将方形设定为 1024x1024，横版海报设定为 2048x1152，竖版海报使用 2160x3840。
质量与格式控制： 追求极高精细度时传 quality: "high"，输出格式固定锁死 output_format: "png"。

六、开发者常见错误排查指南

在联调过程中，如果遇到阻碍，可以优先排查以下几个高频错点：

参数乱入误区： 经常有开发者把 image 参数直接丢进了文生图的 JSON body 中。重申一遍，带图必须用 multipart/form-data 走编辑接口。
乘号输入法错误： 尺寸必须是纯英文字符组合（如 1024x1024），千万不要使用全角或特殊乘号（如 1024×1024）。
生成数量超限： n 参数单次限制在 1-10 之间。日常调试建议保持为 1，确认提示词效果后再放大数量。
解析返回值异常： 服务端可能返回 url 也可能返回 b64_json，前端逻辑必须要做好双重兼容。
401 未授权报错： 请检查请求头中是否遗漏了 Authorization: Bearer ，并将正确替换为您专属的 sk- 令牌。