Skip to main content

​
接口说明

端点： POST https://geekapis.com/v1/images/generations 调用此接口，通过 GPT-Image-2 模型根据文字描述（及可选参考图）生成图像。接口采用异步任务模式——请求成功后立即返回一个任务对象，需通过 GET https://geekapis.com/v1/images/generations/{task_id} 轮询任务状态，直到 status 变为 completed 后获取图像结果。 支持三种使用模式：
  • 文生图：仅提供 prompt，由模型创作图像
  • 单图参考：提供 1 张参考图 + prompt，在参考图风格基础上生成
  • 多图参考：提供多张参考图（最多 16 张）+ prompt，融合多图生成
重要变更：image_urls / reference_images 字段不再支持 base64 数据。请先调用上传图片接口将本地图片上传并获取公网 URL，再传入本接口。

​
请求参数

​
认证

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

​
Body 参数

​
model
string
required
图像生成模型名称。固定填写 gpt-image-2。示例："gpt-image-2"
​
prompt
string
required
图像生成的文字描述。支持中英文，建议详细描述场景、风格、构图和光线。最长 32,000 个字符（OpenAI GPT Image 模型官方上限）。
​
size
string
输出图像的宽高比。默认值："1:1"。可用值取决于所选 resolution（详见下方尺寸对照表）：
  • 1K / 2K：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（共 13 种）
  • 4K：仅支持 16:9、9:16、2:1、1:2、21:9、9:21（共 6 种）
也可传入 "auto"，由服务端根据 prompt 内容自动选择最合适的比例。
​
resolution
string
输出分辨率档位。默认值："1K"。
  • 1K — 1024 基准，速度最快，适合日常预览与快速迭代
  • 2K — 2048 基准，适合海报、高清展示场景
  • 4K — 3840 基准，仅支持 6 种宽高比
​
n
integer
单次请求生成的图像数量。默认值：1。
​
response_format
string
返回格式。默认值："url"。固定返回图片 URL，推荐始终使用 "url"。
​
reference_images
string[]
参考图 URL 数组，用于图生图（推荐字段）。
  • 仅支持公网可访问的 HTTP / HTTPS URL（不支持 base64）
  • 支持 PNG / JPG 格式，单张 ≤ 50MB
  • 最多 16 张
  • 可使用上传图片接口获取 URL
​
image_urls
string[]
向后兼容字段，等同于 reference_images。系统会自动将其归一化为 reference_images 处理。新业务推荐直接使用 reference_images。
4K 分辨率仅支持 6 种宽高比：16:9、9:16、2:1、1:2、21:9、9:21。若使用其他比例搭配 4K，请求将报错。

​
代码示例

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": "生成一张未来城市夜景海报，霓虹灯，电影感构图",
    "n": 1,
    "size": "1:1",
    "resolution": "1K",
    "response_format": "url"
  }'

​
响应示例

200 OK
{
  "id": "task_img_abc123def456",
  "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 时间戳）

​
尺寸对照表

比例1K 像素尺寸2K 像素尺寸4K 像素尺寸
1:11024 × 10242048 × 2048不支持
3:21536 × 10242048 × 1360不支持
2:31024 × 15361360 × 2048不支持
4:31024 × 7682048 × 1536不支持
3:4768 × 10241536 × 2048不支持
5:41280 × 10242560 × 2048不支持
4:51024 × 12802048 × 2560不支持
16:91536 × 8642048 × 11523840 × 2160
9:16864 × 15361152 × 20482160 × 3840
2:12048 × 10242688 × 13443840 × 1920
1:21024 × 20481344 × 26881920 × 3840
21:92016 × 8642688 × 11523840 × 1648
9:21864 × 20161152 × 26881648 × 3840

​
错误码说明

HTTP 状态码错误类型说明
400Bad Request请求参数有误，如 size 与 resolution 组合不合法
401UnauthorizedAPI Key 无效或未提供
422Unprocessable Entity参数格式正确但取值不合法（如 base64 图片被拒绝）
429Too Many Requests请求频率超限，请稍后重试
500Internal Server Error服务端异常，请重试或联系支持