调用生图api指南

生图API 调用指南

前置准备

`生图能力 模型属于 Image-2出图组、Image-2 Adobe原生4K渠道、Grok-Heavy号池组（使用grok-imagine-image-2.0模型） 分组，使用前需要创建相应的分组KEY。分组选择 Image-2出图组、Image-2 Adobe原生4K渠道、Grok-Heavy号池组 三者之一。

调用方式概览

OpenAI 官方文档将图片相关能力分为 Responses API、Images API、Chat Completions API 三类。对于 gpt-image-2，出图请优先使用 Images API。

API 名称 OpenAI 官方用途 gpt-image-2 使用建议 建议
Responses API 分析图片并作为输入；也可通过工具生成图片输出 不支持作为 gpt-image-2 的出图入口。需要出图请使用 Images API。 不支持
Images API 生成图片，也可上传图片作为输入进行编辑 支持文生图和图片编辑，是 gpt-image-2 的推荐调用方式。 推荐
Chat Completions API 分析图片输入，并生成文本或音频 不支持作为 gpt-image-2 的出图入口；size、quality、output_format 等参数不会按图片接口生效。 不支持

Images API 调用说明（推荐）

Images API 分为文生图和图片编辑/图生图两个接口：

  • 文生图：POST [https://api.api2cn.com/v1/images/generations](https://api.api2cn.com/v1/images/generations)
  • 图片编辑 / 图生图：POST [https://api.api2cn.com/v1/images/edits](https://api.api2cn.com/v1/images/edits)

💡 推荐用法：单纯生成图片使用 /v1/images/generations；如需上传参考图进行编辑/改图，使用 /v1/images/edits。

1. 文生图：/v1/images/generations

接口实例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
curl --location 'https://api.api2cn.com/v1/images/generations' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer 你的生图分组key' \
  --header 'Accept: */*' \
  --header 'Host: api.api2cn.com' \
  --header 'Connection: keep-alive' \
  --data '{
    "model": "gpt-image-2",
    "prompt": "一只橘猫戴着橙色围巾抱着水獭，温暖插画风格",
    "size": "3840x2160",
    "quality": "high",
    "output_format": "png",
    "response_format": "url",
    "n": 1
  }'

文生图参数说明

参数 类型 支持情况 说明
model string 支持 固定填写 gpt-image-2
prompt string 支持 图片描述提示词，建议写清楚主体、场景、风格、比例和文字内容
n integer 仅支持 1 只支持一次返回 1 张图，不支持 n: 2、n: 4 等多图请求
size string 支持 支持 auto 及符合限制的尺寸（如 1024x1024、1536x1024、1024x1536、1536x864、3840x2160）
quality string 支持 可选 low、medium、high、auto。草稿图用 low，正式出图用 high
response_format string 支持 可选 url、b64_json。默认建议用 url；b64_json 适合程序自行保存
output_format string 部分支持 推荐 png 或 jpeg，不建议使用 webp
output_compression integer 支持 仅在 output_format 为 jpeg 时使用，取值 0 到 100
background string 部分支持 建议使用默认值或 opaque，不支持 transparent
moderation string 支持 可选 auto、low。安全审核参数，不确定时保持默认即可
user string 支持 可选，用于标记终端用户或业务来源，普通调用可不传
stream boolean 不支持 请勿开启
partial_images integer 不支持 依赖 stream 的中间图返回能力，暂不支持
style string 不建议使用 旧模型常见参数，gpt-image-2 无需传递

2. 图片编辑 / 图生图：/v1/images/edits

/v1/images/edits 使用 multipart/form-data 格式上传图片。image 为二进制图片文件，prompt 写明修改需求。

接口实例

1
2
3
4
5
6
7
8
9
10
11
curl --location 'https://api.api2cn.com/v1/images/edits' \
  --header 'Authorization: Bearer 你的生图分组key' \
  --header 'Accept: */*' \
  --form 'model="gpt-image-2"' \
  --form 'prompt="把图片里的主体保留，在右上角加一枚红色小印章，印章上写 DEMO"' \
  --form 'image=@"/path/to/your-image.jpg"' \
  --form 'size="1024x1024"' \
  --form 'quality="high"' \
  --form 'output_format="png"' \
  --form 'response_format="url"'

图片编辑参数说明

参数 类型 支持情况 说明
model string 支持 固定填写 gpt-image-2
prompt string 支持 写清楚要保留什么、修改什么以及最终期望结果
image file 支持 必填，上传要编辑的图片二进制文件，建议一次上传 1 张
mask file 支持 可选，局部修改时上传 PNG 格式 mask；不传则默认整图编辑
n integer 仅支持 1 只支持一次返回 1 张图
size string 支持 同文生图，支持 auto 及符合限制的尺寸
quality string 支持 可选 low、medium、high、auto
response_format string 支持 可选 url、b64_json，默认推荐 url
output_format string 部分支持 推荐 png 或 jpeg，不建议使用 webp
output_compression integer 支持 仅在 output_format 为 jpeg 时使用，取值 0 到 100
background string 部分支持 建议使用默认值或 opaque，不支持 transparent
moderation string 支持 可选 auto、low（安全审核参数）
input_fidelity string 支持 可传 high，用于尽量保留原图的主体与细节
user string 支持 可选，普通调用可不传
stream boolean 不支持 请勿开启
partial_images integer 不支持 依赖 stream 的中间图返回能力，暂不支持

📌 局部修改提示：如需局部修改，可额外上传 mask（建议 PNG 图片），透明区域代表允许模型重点修改的位置；若不传 mask，模型将根据提示词对整张图进行编辑。

通用说明

1. 尺寸与质量

常用尺寸（Popular sizes）

  • 1024x1024：正方形
  • 1536x1024：横向
  • 1024x1536：纵向
  • 2048x2048：2K 正方形
  • 2048x1152：2K 横向
  • 3840x2160：4K 横向
  • 2160x3840：4K 纵向
  • auto：自动（默认）

尺寸限制（Size constraints）

  • 最大边长：必须 $\le 3840$ 像素
  • 整倍数要求：宽和高都必须是 16 的倍数
  • 宽高比限制：长边与短边比例不能超过 3:1
  • 总像素限制：介于 655,360 至 8,294,400 像素之间

质量选项（Quality options）

  • low：低质量
  • medium：中等质量
  • high：高质量
  • auto：自动（默认）

2. 参数选择建议

  1. 最简文生图：仅传 model 和 prompt，并把 n 设为 1。
  2. 提高清晰度：添加 "quality": "high"。
  3. 指定生成尺寸：添加 size 参数（如 "1024x1024" 或 "1536x1024"）。
  4. 获取图片链接：保留默认的 "response_format": "url"。
  5. 程序直接读取 Base64：设置 "response_format": "b64_json"。
  6. 批量生成限制：请勿将 n 设置为大于 1 的值，生成多张图片请使用循环单独发起请求。

3. 返回结果

默认返回（图片下载地址 url）

1
2
3
4
5
6
7
8
9
10
{
  "created": 1776923999,
  "data": [
    {
      "url": "https://XXXXXXXXXXXX/file_download/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "revised_prompt": "..."
    }
  ]
}

  • url 为生成的图片链接，直接访问即可下载。
  • revised_prompt 为模型实际使用前优化改写过的提示词，属于正常返回字段。

Base64 格式返回（b64_json）

请求中传入 "response_format": "b64_json" 时返回：

1
2
3
4
5
6
7
8
9
10
{
  "created": 1776923999,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...",
      "revised_prompt": "..."
    }
  ]
}

  • 此响应格式下不包含 url，需要客户端自行将 b64_json 字符串解码保存为图片文件。
  • 普通场景更推荐使用默认的 url 方式，更易于保存与分享。