apimaxDocs
文档定价控制台
API 参考接入指南用户指南更新日志

图像系列

POST原生openai image格式(同步)

任务管理

错误码参考查询任务状态GET

账户管理

查询额度使用情况GET

文档 / 图像系列 / GPT Image / 同步

同步POSTgpt-image-2gpt-image-2.5-flaregpt-image-2.5-sunburstgpt-image-web

原生openai image格式(同步)

同步 OpenAI Image 接口：文生图使用 POST /v1/images/generations（JSON）；图生图与图片编辑使用 POST /v1/images/edits（multipart/form-data）。支持 quality 与透明背景参数。

POST/v1/images/generations
试一试
Bearer API KeyJSON服务端调用

GPT Image 2(gpt-image-2)图像编辑接口,兼容 OpenAI Images Edits 格式,通过 multipart/form-data 上传图片文件对原图进行编辑、扩展或局部重绘。本接口为同步调用:请求返回时即携带生成结果,无需轮询任务。

- 本接口与图像生成的区别:图像编辑为同步接口、以文件上传方式传图;图像生成为异步接口、以图片 URL方式传图。 - 返回的图像以 base64(b64_json)或临时 URL 形式直接返回,请及时保存。

文生图 / 图生图接口选择#

场景接口请求格式说明
文生图POST /v1/images/generationsapplication/json只提交文字提示词，直接生成图片
图生图 / 图片编辑POST /v1/images/editsmultipart/form-data上传一张或多张参考图，可配合提示词和遮罩进行编辑
只用文字生成图片选 `/v1/images/generations`；需要上传参考图选 `/v1/images/edits`。

/v1/images/generations 同步生图#

同步文生图接口遵循 OpenAI Images API 格式，提交 JSON 后直接返回生成结果。图像编辑仍使用下方的 /v1/images/edits multipart 接口。

POST /v1/images/generations

请求参数#

参数类型必填默认说明
modelstring是gpt-image-2模型名称，支持 gpt-image-2、gpt-image-2.5-flare、gpt-image-web、gpt-image-2.5-sunburst
promptstring是—描述要生成的图像
ninteger否1生成图片数量;实际返回以 data 为准,按实际成功张数计费
sizestring否auto图像尺寸,如 1024x1024、1536x1024、1024x1536 或 auto;也支持自定义尺寸(官方限制见下方「size 尺寸」)
qualitystring否autolow、medium、high；xhigh、max 仅 gpt-image-2.5-flare 与 gpt-image-2.5-sunburst 两个 2.5 模型支持
backgroundstring否autoauto、opaque 或 transparent
response_formatstring否b64_json响应格式兼容参数:b64_json(默认)或 url,详见下方 response_format 说明

透明背景#

将 background 设置为 transparent 即可输出透明背景,输出为 png 或 webp 格式。

请求示例#

bash
curl --request POST \
  --url https://api.apimax.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2",
    "prompt": "一只简洁的白色猫咪图标，背景透明",
    "size": "1024x1024",
    "quality": "medium",
    "background": "transparent"
  }'

response_format 响应格式(兼容参数)#

GPT Image 原生仅返回 base64 图像数据。为兼容 DALL·E 生态,平台额外支持 response_format 参数,/v1/images/generations 与 /v1/images/edits 两个接口均可使用:

取值行为
b64_json默认。返回 data[].b64_json base64 图像数据
url平台将生成的图片上传托管,以 data[].url 返回图片链接,响应中不再包含 b64_json
  • 参数缺省或传空时按 b64_json 处理;传入其他取值(如 binary)将返回 400 错误
  • url 指向平台托管的图片地址,请及时下载保存,避免链接失效

鉴权#

所有接口均需通过 Bearer Token 认证。请在 API Key 管理页面 创建你的 Key,并在请求头中添加:

text
Authorization: Bearer YOUR_API_KEY

/v1/images/edits 图生图与编辑#

POST /v1/images/edits

请求体为 multipart/form-data(不是 JSON)。核心字段:上传一张或多张原图 image,配合 prompt 描述如何编辑;可选地附带遮罩 mask 做局部重绘。

模式说明
整图编辑 / 风格改写只传 image + prompt,模型在原图基础上整体编辑
多图合成传多张 image[],模型融合多张参考图
局部重绘(inpainting)传 image + mask + prompt,仅重绘遮罩透明区域

请求参数(form fields)#

字段类型必填默认说明
modelstring是—模型名称，支持 gpt-image-2、gpt-image-2.5-flare、gpt-image-web、gpt-image-2.5-sunburst
imagefile是—待编辑的原图文件。多图用 image[] 重复字段
promptstring是—描述想要的编辑效果
maskfile否—局部重绘遮罩,带 alpha 通道的 PNG
ninteger否1生成图片数量;实际返回以 data 为准,按实际成功张数计费
sizestring否auto输出尺寸,如 1024x1024、1536x1024、auto
qualitystring否auto渲染质量 low/medium/high/auto；xhigh、max 仅 gpt-image-2.5-flare 与 gpt-image-2.5-sunburst 支持
backgroundstring否auto背景模式：auto（自动）、opaque（不透明）、transparent（透明）
response_formatstring否b64_json响应格式兼容参数:b64_json(默认)或 url,行为与 /v1/images/generations 相同

background 透明背景#

GPT Image 支持透明背景输出。将 background 设置为 transparent 即可,输出为 png 或 webp 格式。

bash
curl --request POST \
  --url https://api.apimax.ai/v1/images/edits \
  --header 'Authorization: Bearer <token>' \
  --form 'model=gpt-image-2' \
  --form 'image=@/path/to/input.png' \
  --form 'prompt=生成透明背景的产品图标' \
  --form 'background=transparent' \

image 原图#

  • 支持格式:.png、.jpg、.jpeg、.webp
  • 单图编辑用 image 字段;多图合成时用 image[] 重复字段上传多张
  • 文件以 multipart 二进制上传,而非 URL

mask 遮罩(局部重绘)#

  • 必须是带 alpha 通道的 PNG:透明像素(alpha < 255)= 需要重绘的区域,不透明像素 = 保留原图
  • 遮罩尺寸必须与原图完全一致(宽 × 高,单位像素)
  • 仅在同时上传 image 时生效

size 尺寸#

取值说明
auto由模型自动决定(默认)
1024x1024正方形
1536x1024横版
1024x1536竖版

除上表常用尺寸外,也支持自定义像素尺寸(宽x高,小写 x),需满足官方限制:

  • 宽、高均须为 16 的倍数
  • 单边像素范围 16 ~ 3840
  • 长宽比最大 1:3(横竖皆可,如 1024x3072 可以,1024x4096 不行)
  • 总像素(宽 × 高)须在 655,360 ~ 8,294,400 之间(约 0.65MP ~ 8.29MP,上限即 3840×2160 级别)

不满足上述限制的尺寸会被拒绝(400 参数错误)。

请求示例#

整图编辑(单图):

bash
curl --request POST \
  --url https://api.apimax.ai/v1/images/edits \
  --header 'Authorization: Bearer <token>' \
  --form 'model=gpt-image-2' \
  --form 'image=@/path/to/input.png' \
  --form 'prompt=把背景换成樱花盛开的春日公园' \
  --form 'size=1024x1024' \
  --form 'quality=high'

局部重绘(带遮罩):

bash
curl --request POST \
  --url https://api.apimax.ai/v1/images/edits \
  --header 'Authorization: Bearer <token>' \
  --form 'model=gpt-image-2' \
  --form 'image=@/path/to/input.png' \
  --form 'mask=@/path/to/mask.png' \
  --form 'prompt=把天空换成繁星点点的夜空'

多图合成:

bash
curl --request POST \
  --url https://api.apimax.ai/v1/images/edits \
  --header 'Authorization: Bearer <token>' \
  --form 'model=gpt-image-2' \
  --form 'image[]=@/path/to/a.png' \
  --form 'image[]=@/path/to/b.png' \
  --form 'prompt=把这两张图融合成一张电影海报'

Python(requests):

python
import requests

url = "https://api.apimax.ai/v1/images/edits"
headers = {"Authorization": "Bearer <token>"}
files = {
    "image": open("input.png", "rb"),
    "mask": open("mask.png", "rb"),
}
data = {
    "model": "gpt-image-2",
    "prompt": "把天空换成繁星点点的夜空",
    "size": "1024x1024",
}
resp = requests.post(url, headers=headers, files=files, data=data)
print(resp.json())

响应示例#

同步返回标准 OpenAI Images 格式,data[].b64_json 为生成图像的 base64 编码:

json
{
  "created": 1757156493,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "usage": {
    "input_tokens": 312,
    "output_tokens": 4160,
    "total_tokens": 4472,
    "input_tokens_details": {
      "text_tokens": 12,
      "image_tokens": 300
    }
  }
}

将 b64_json 解码即可得到图像二进制。图生图/局部重绘会因参考图产生额外的图像输入 token 消耗(见 usage.input_tokens_details.image_tokens)。

生成结果以 data 实际返回为准:个别图片可能生成失败,此时仅返回成功的图片,并按实际成功张数计费(例如 n=4 成功 2 张,则返回并计费 2 张)。

若请求指定 response_format=url,则每项返回 url 字段(平台托管的图片链接),且不再包含 b64_json:

json
{
  "created": 1757156493,
  "data": [
    {
      "url": "https://<storage-host>/img/image_xxxxxxxx.png"
    }
  ]
}

错误码#

状态码含义
400请求参数无效(缺少 image/prompt,遮罩与原图尺寸不一致,格式不支持等)
401身份验证失败,请检查 API 密钥
402账户余额不足,请充值后再试
403Token 无该模型访问权限
429请求过于频繁,请稍后再试
500服务器内部错误,请稍后重试

常见报错:

  • Invalid mask image format - mask image missing alpha channel:遮罩没有 alpha 通道(JPEG、不透明 PNG),请重新导出带透明区域的 PNG
  • Invalid mask image format - mask size does not match image size:遮罩与原图尺寸不一致,请调整到与原图完全相同的像素尺寸

下一步

全部文档
查询额度使用情况使用 API Key 查询当前令牌及所属用户的剩余 credits、已用 credits 和无限额度状态。错误码参考异步任务失败错误码完整列表与排错指南:8 个顶层 code 枚举 + 上游 upstream.code 详解 + 重试策略。GPT Image 2.5 图像生成GPT Image 2.5 系列图像生成，支持文生图、图生图与图像编辑。GPT Image 2 图像生成/v1/images/async-generationsNano Banana 2 图像生成Google Nano Banana 2(Gemini)异步图像生成,擅长多图融合、真人参考与文字渲染,支持思考推理级别。原生nano-banana格式(同步)Google Gemini Nano Banana 原生 generateContent 格式同步图像生成,支持文生图、图生图与 aspect_ratio/image_size 配置,直接返回 inline_data base64。
本页导航
概览文生图 / 图生图接口选择/v1/images/generations 同步生图请求参数透明背景请求示例responseformat 响应格式(兼容参数)鉴权/v1/images/edits 图生图与编辑请求参数(form fields)background 透明背景image 原图mask 遮罩(局部重绘)size 尺寸请求示例响应示例错误码下一步
API

POST /v1/images/generations