Developer Docs / Image Generation

使用 gpt-image-2 创建、编辑并保存图片结果

本文档按 OpenAI 兼容接口整理，示例 Base URL 使用 https://img.apixgo.com。 调用方应在自己的后端服务中发送请求，生成接口返回 base64 图片数据后，再解码保存为 PNG/JPEG/WebP 等文件。

Base URL https://img.apixgo.com
模型列表 GET /v1/models
生成图片 POST /v1/images/generations
编辑图片 POST /v1/images/edits

接口概览

gpt-image-2 适合文本生成图片、基于参考图编辑图片、批量生成多张候选图等场景。 生成接口使用 JSON 请求体；编辑接口需要上传图片文件，通常使用 multipart/form-data。

建议业务代码先调用 GET /v1/models 确认模型可用，再根据用户需求选择尺寸、 输出格式和生成数量。

后端调用原则

不要在浏览器端直接调用图片接口。API Key 应只存在于服务端环境变量、密钥管理服务或后端运行时中。

请求流程

  1. 确认模型

    调用 GET /v1/models，确认 gpt-image-2 当前可用。

  2. 构造请求

    生成图片用 JSON；编辑图片用表单上传 image 和提示词。

  3. 读取结果

    从 data[0].b64_json 读取 base64 图片内容。

  4. 保存文件

    解码 base64 后保存到本地、R2、S3 或业务素材库。

认证方式

所有接口使用 Bearer Token。请在你的用户控制台创建或复制 API Key，并放入请求头。

HTTP Header 
Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json
查询模型 
curl -X GET "https://img.apixgo.com/v1/models" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

请求参数

字段 类型 必填 说明
model string 是 固定使用 gpt-image-2。
prompt string 是 图片生成或编辑指令。建议写清主体、风格、构图、光线、比例和限制。
size string 否 图片尺寸。gpt-image-2 支持灵活尺寸，也可使用常见尺寸如 1024x1024。
n integer 否 生成图片数量。建议按业务需要控制数量，避免一次请求过大。
quality string 否 质量档位。可按网关实际支持情况使用 auto、high、medium 或 low。
output_format string 否 输出格式。常见取值包括 png、jpeg、webp。
image file / file[] 编辑时是 编辑接口中的输入图片。使用 multipart/form-data 上传。
mask file 否 局部编辑蒙版。是否支持以及格式要求以实际网关和上游能力为准。

尺寸建议

1024x10241536x10241024x1536 auto自定义尺寸

提示词建议

  • 明确主体、场景、用途和画面比例，例如“电商主图”“社媒海报”“写实产品摄影”。
  • 写清不要出现的内容，例如“不要文字水印、不要额外 logo、不要变形手指”。
  • 编辑图片时说明保留哪些元素、修改哪些区域、输出应保持什么风格。

生成示例

curl JSON 请求

POST /v1/images/generations 
curl -X POST "https://img.apixgo.com/v1/images/generations" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A clean studio product photo of a matte black wireless headphone, soft rim light, white background, premium e-commerce style",
    "size": "1024x1024",
    "quality": "high",
    "output_format": "png",
    "n": 1
  }'

Node.js 保存图片

Backend Example 
import fs from 'node:fs/promises';

const BASE_URL = 'https://img.apixgo.com';
const API_KEY = process.env.IMAGE_API_KEY;

const response = await fetch(`${BASE_URL}/v1/images/generations`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-image-2',
    prompt: 'A modern API documentation cover image, precise grid, teal accent, editorial style',
    size: '1536x1024',
    quality: 'high',
    output_format: 'png',
    n: 1,
  }),
});

const result = await response.json();
if (!response.ok) {
  throw new Error(`Image request failed: ${JSON.stringify(result)}`);
}

const imageBase64 = result.data?.[0]?.b64_json;
if (!imageBase64) {
  throw new Error(`No image returned: ${JSON.stringify(result)}`);
}

await fs.writeFile('gpt-image-2-output.png', Buffer.from(imageBase64, 'base64'));

编辑示例

编辑接口通常使用 multipart/form-data。适合改背景、替换局部元素、统一风格、 扩展画面或基于参考图生成变体。

POST /v1/images/edits 
curl -X POST "https://img.apixgo.com/v1/images/edits" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -F "model=gpt-image-2" \
  -F "image=@input.png" \
  -F "prompt=Keep the product unchanged, replace the background with a bright minimalist studio, soft shadow, no text" \
  -F "size=1024x1024" \
  -F "output_format=png"

如果你的网关暂未开放图片编辑接口，先使用生成接口；或联系服务端确认 /v1/images/edits 是否已映射到上游能力。

响应处理

图片接口通常返回数组，每个元素对应一张图片。GPT Image 模型的图片结果以 base64 字段读取。

典型响应 
{
  "created": 1780000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ]
}
成功取值 response.data[0].b64_json
保存方式 服务端解码 base64，并保存为目标格式文件。
多张图片 遍历 response.data，逐张保存。
前端展示 建议后端先保存为文件 URL，再返回给前端展示。

状态/错误码

状态或错误 含义 建议处理
401 API Key 缺失或错误。 检查 Authorization: Bearer <YOUR_API_KEY>。
403 权限、额度、分组或模型访问限制。 检查账号余额、令牌权限和 gpt-image-2 可用性。
400 prompt is required prompt 为空。 提交前校验提示词。
400 invalid model 模型名不可用或未映射。 调用 /v1/models，确认模型名和中转映射。
400 unsupported size 尺寸不被当前模型或网关支持。 改用 1024x1024、1536x1024、1024x1536 或 auto。
413 上传图片过大。 压缩输入图片，降低分辨率或文件体积。
429 请求过于频繁或额度不足。 加入重试退避，降低并发，检查额度。
5xx 服务端或上游暂时异常。 保留请求参数和错误响应，稍后重试或提交排查。

常见问题

  • 可以在前端直接调用图片 API 吗？
    不建议。前端代码会暴露 Key，应由后端代调并返回保存后的图片 URL。
  • 为什么没有返回 URL？
    GPT Image 模型常见返回方式是 b64_json。业务侧需要自己保存图片文件。
  • 生成多张图片怎么处理？
    设置 n 后遍历 data 数组，每个元素保存成一个文件。
  • 编辑接口和生成接口有什么区别？
    生成接口只需要文本提示词；编辑接口需要上传参考图，并用提示词描述要修改的内容。
  • 尺寸应该怎么选？
    通用场景先用 1024x1024；横图用 1536x1024；竖图用 1024x1536。
  • 中转站模型名不一样怎么办？
    以 /v1/models 返回和站内模型映射为准，把示例里的 gpt-image-2 替换成实际模型名。