Skip to main content

​
接口说明

端点： POST https://geekapis.com/v1/images/generations 图像编辑模式与文生图使用相同端点——只需在请求中加入 image_urls 字段，系统即自动切换为编辑模式。支持以下三种典型用法：
  • 图生图（多参考图融合）：提供 1–16 张参考图 + prompt，生成融合多图风格或内容的新图
  • 局部重绘（inpainting）：额外提供 mask_url，精确控制图像中需重新绘制的区域
  • 风格迁移：以参考图为样本，配合详细 prompt 生成指定风格的高清图像
接口采用异步任务模式，请求成功后立即返回任务对象，需通过 GET https://geekapis.com/v1/images/generations/{task_id} 轮询状态。
编辑模式与生成模式完全兼容，无需切换端点。在标准生成请求基础上加入 image_urls（以及可选的 mask_url）即可启用编辑模式。

​
请求参数

​
认证

所有请求须在 Header 中携带 Bearer Token： 
Authorization: Bearer YOUR_API_KEY
前往 API Key 管理页面 获取您的密钥。

​
Body 参数

​
model
string
required
图像生成模型名称。固定填写 gpt-image-2。
​
prompt
string
required
描述期望的编辑效果。示例："把背景换成星空，保持主体人物不变" 或 "将两张参考图融合成赛博朋克风格插画海报"
​
image_urls
string[]
required
参考图 URL 数组（触发编辑模式的关键字段）。
  • 最多 16 张
  • 须为公网可访问的稳定 URL（HTTP / HTTPS）
  • 支持 PNG / JPG 格式，单张 ≤ 50MB
  • 可使用上传图片接口获取 URL
​
mask_url
string
遮罩图 URL，用于局部重绘（inpainting）。
  • 须为 PNG 格式，且包含 Alpha 通道
  • 透明区域（alpha = 0） 为待重绘区域；不透明区域 保持原图内容不变
  • 尺寸须与 image_urls 中第一张参考图完全一致
​
size
string
输出图像宽高比。默认值："1:1"。支持 13 种比例，也可传 "auto"：1:1 · 3:2 · 2:3 · 4:3 · 3:4 · 5:4 · 4:5 · 16:9 · 9:16 · 2:1 · 1:2 · 21:9 · 9:21
​
resolution
string
分辨率档位。默认值："1K"。
  • 1K — 1024 基准（默认）
  • 2K — 2048 基准
  • 4K — 3840 基准，仅支持 6 种比例（16:9 / 9:16 / 2:1 / 1:2 / 21:9 / 9:21）
​
quality
string
图片质量。默认值："high"。
  • low — 快速省成本，适合草稿预览
  • medium — 平衡速度与质量
  • high — 最高精度（默认）
​
n
integer
生成图像数量，范围 1–10。默认值：1。
​
output_format
string
输出文件格式。默认值："png"。支持 "png" / "jpeg"。注意：不支持 "webp" 格式（Azure OpenAI 后端限制）。
​
output_compression
integer
JPEG 压缩强度，范围 0–100（0 不压缩，100 最大压缩）。默认值：100。仅对 output_format: "jpeg" 生效。
遮罩图格式要求：mask_url 指向的图片必须是含 Alpha 通道的 PNG 文件。透明像素（alpha = 0）标记为重绘区域，不透明像素标记为保留区域。遮罩尺寸必须与第一张参考图的原始尺寸完全匹配。

​
代码示例

curl --request POST \
  --url https://geekapis.com/v1/images/generations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2",
    "prompt": "将两张参考图融合成赛博朋克风格插画海报",
    "image_urls": [
      "https://example.com/input-a.png",
      "https://example.com/input-b.png"
    ],
    "size": "1:1",
    "quality": "high",
    "n": 1
  }'

​
响应示例

200 OK
{
  "id": "tsk_img_01KPTXXXXXXXXXXXXXXX",
  "object": "generation.task",
  "model": "gpt-image-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1703884800,
  "metadata": {}
}

​
响应字段说明

字段类型说明
idstring任务唯一标识符，用于轮询结果
objectstring固定为 "generation.task"
modelstring本次使用的模型名称
statusstring任务状态：queued / in_progress / completed / failed
progressinteger完成进度（0–100）
created_atinteger任务创建时间（Unix 时间戳）

​
错误码说明

HTTP 状态码错误类型说明
400Bad Request参数有误，如 image_urls 超过 16 张，或 size + resolution 组合不合法
401UnauthorizedAPI Key 无效或未提供
422Unprocessable Entity参数值不合法（如传入 base64 数据被拒绝，或遮罩图尺寸不匹配）
429Too Many Requests请求频率超限，请稍后重试
500Internal Server Error服务端异常，请重试或联系支持