GPT-4o Image API 模型解析指南
快速结论
- 支持 prompt 文生图，适合营销、电商和创意视觉生产。
- 支持 reference_images（最多 5 张）进行图生图与风格约束。
- 支持 mask_url 做局部编辑，便于精修和定向修改。
核心能力
- 高质量文生图：通过统一接口快速生成可交付图像素材。
- 参考图一致性：通过 reference_images 提升风格和构图稳定性。
- 局部编辑能力：通过 mask_url 对指定区域进行细粒度改图。
适用场景
- 需要快速生成商品图、广告图、活动视觉等素材。
- 需要在已有图片基础上做风格统一或局部重绘。
不适用场景
- 需要长视频生成或时间序列镜头控制时。
- 需要复杂多轮逻辑推理对话时。
运行特性
- 统一走图片生成接口，结果通常以异步任务形式返回并通过任务状态查询。
- reference_images 最多 5 张，单张文件大小与格式需满足文档约束。
- mask_url 可选，用于局部编辑和替换。
最小请求示例
{
"model": "gpt-4o-image",
"prompt": "高质感产品广告图，柔和主光，极简背景，商业摄影风格",
"size": "1:1",
"n": 1
}
最小响应示例
{
"id": "task_img_xxxxxxxx",
"object": "generation.task",
"model": "gpt-4o-image",
"status": "queued",
"progress": 0,
"created_at": 1703884800,
"metadata": {}
}
关键参数
| 参数 | 类型 | 必填 | 默认值 | 范围 | 说明 |
|---|
| model | string | 是 | gpt-4o-image | - | 模型标识，必须使用 ToAPIs 提供值。 |
| prompt | string | 是 | - | - | 图片描述文本。 |
| size | string | 否 | 1:1 | 1:1 | 2:3 |
| n | integer | 否 | 1 | 1-4 | 单次请求生成张数。 |
| reference_images | file[] | 否 | - | max 5 | 参考图片数组，用于图生图与风格控制。 |
| mask_url | string | 否 | - | - | 遮罩图 URL，用于局部编辑。 |
常见错误
| HTTP | Code | 触发条件 | 修复建议 | 重试策略 |
|---|
| 400 | invalid_request_error | 字段缺失、类型错误或参数取值不在允许范围。 | 校验 model/prompt/size/n/reference_images/mask_url 参数。 | 修正请求体后重试。 |
| 401 | authentication_error | API Key 缺失或无效。 | 确认 Authorization 头和密钥权限。 | 修复鉴权后重试。 |
| 429 | rate_limit_exceeded | 请求频率、并发或当前额度命中上游限流策略。 | 先做指数退避重试，并检查当前请求节奏、并发设置和额度使用情况。 | 建议 1s/2s/4s + 抖动；连续触发时再收紧提交节奏。 |
FAQ
- GPT-4o Image 适合什么场景？
适合高频创意出图、品牌视觉扩展、以及在已有素材上进行局部编辑。
- 为什么图生图效果不稳定？
请检查 reference_images 质量与数量，并在 prompt 中明确保留元素和风格约束。
- 图像视频模型报错：invalid apitype: -1
这类错误通常说明接口走错了。图像和视频模型一般不走 chat 接口，而是按对应文档发起 HTTP 任务请求，并通过任务状态接口轮询结果。排查时建议先看用户的实际请求代码、请求地址和请求体。
- 用户进行生成图片/视频的任务时出现任务失败，但是扣款
先让用户提供任务日志或截图，重点看是否出现了输入或输出 token 统计。如果有这类 token 记录，大概率是用户把图片/视频模型走成了 chat 接口；这不是正确用法。图片和视频模型通常是异步任务接口，需要通过 HTTP 请求先提交任务，再拿到任务 ID 轮询状态，详细以对应文档为准。
相关 API
