跳转到主要内容
POST
/
api
/
v1
/
gpt4o-image
/
generate
生成4o图像
curl --request POST \
  --url https://api.kie.ai/api/v1/gpt4o-image/generate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "filesUrl": [
    "https://example.com/image1.png",
    "https://example.com/image2.png"
  ],
  "prompt": "A beautiful sunset over the mountains",
  "size": "1:1",
  "callBackUrl": "https://your-callback-url.com/callback",
  "isEnhance": false,
  "uploadCn": false,
  "nVariants": 1,
  "enableFallback": false,
  "fallbackModel": "FLUX_MAX"
}'
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task12345"
  }
}

Authorizations

​
Authorization
string
header
required

所有接口都需要通过 Bearer Token 方式进行认证。

获取 API Key:

  1. 访问 API Key 管理页面 获取您的 API Key

使用方式: 在请求头中添加： Authorization: Bearer YOUR_API_KEY

注意事项：

  • 请妥善保管您的 API Key，不要泄露给他人
  • 如果怀疑 API Key 泄露，请立即在管理页面重置

Body

application/json
​
size
enum<string>
required

（必填）图片尺寸比例，必须是支持的格式之一

可用选项:
1:1,
3:2,
2:3
Example:

"1:1"

​
fileUrl
string<uri>
deprecated

（可选，即将废弃）文件URL，例如图片的URL。如果提供fileUrl，4o image可能会基于该图片进行创作。该参数将在未来被废弃，请使用filesUrl替代。

Example:

"https://example.com/image.png"

​
maskUrl
string<uri>

（可选）蒙版图片URL。你可以提供一个蒙版（mask）来指示图像应该在哪些区域进行编辑。蒙版中黑色的部分将被替换或修改，其他区域使用白色填充。你可以使用文字描述你希望最终编辑后的图像是什么样子，或者具体想要修改哪些内容。蒙版图片必须与编辑的图片具有相同的格式和尺寸（小于25MB）。当filesUrl包含超过1张图片时，此参数不可用。蒙版图片的尺寸必须与filesUrl中的图片保持一致。

示例： 蒙版示例

上图中，左侧是原始图片，中间是蒙版图片（白色区域表示要保留的部分，黑色区域表示要修改的部分），右侧是最终生成的图片。

Example:

"https://example.com/mask.png"

​
filesUrl
string<uri>[]

（可选）文件URL列表，例如图片URL列表。最多支持5张图片。支持的文件格式：.jfif、.pjpeg、.jpeg、.pjp、.jpg、.png、.webp

Example:
[
  "https://example.com/image1.png",
  "https://example.com/image2.jpg"
]
​
prompt
string

（可选）提示词，用于描述你希望4o image生成的内容。fileUrl/filesUrl和prompt至少需要提供一个

Example:

"A beautiful sunset over the mountains"

​
callBackUrl
string<uri>

用于接收4o图像生成任务完成更新的URL地址。可选但推荐在生产环境中使用。

  • 系统将在4o图像生成完成时向此URL发送POST请求，包含任务状态和结果
  • 回调包含生成的图像URL和任务信息，支持所有变体
  • 您的回调端点应能接受包含图像生成结果的JSON载荷的POST请求
  • 详细的回调格式和实现指南，请参见 4o图像生成回调
  • 或者，您也可以使用获取4o图像详情接口来轮询任务状态
Example:

"https://your-callback-url.com/callback"

​
isEnhance
boolean

（可选）提示增强选项，默认值为 false。在大多数情况下，启用此功能是不必要的。但是，对于生成 3D 图像等特定场景，启用它可以产生更精细的效果。谨慎使用。

Example:

false

​
uploadCn
boolean

（可选）指定图片上传的服务器区域。设置为 true 时使用中国大陆服务器，false 时使用海外服务器。可根据您的地理位置选择最优的上传节点以获得更好的上传速度。

Example:

false

​
nVariants
enum<integer>

（可选）生成图片的变体数量。仅接受值 1、2 或 4。默认值为 1。根据官网政策变动，将来可能会有变动。

可用选项:
1,
2,
4
Example:

1

​
enableFallback
boolean

（可选）是否启用托底机制。当设置为 true 时，如果官方 GPT-4o 图像生成服务不可用或出现异常，系统将自动切换到备用模型（如 Flux 等）进行图像生成，以确保任务的连续性和可靠性。默认值为 false。

Example:

false

​
fallbackModel
enum<string>
default:FLUX_MAX

（可选）指定托底模型。当 enableFallback 为 true 时生效，用于选择在主模型不可用时使用哪个备用模型来生成图片。可选值：GPT_IMAGE_1 或 FLUX_MAX。默认值为 FLUX_MAX。

可用选项:
GPT_IMAGE_1,
FLUX_MAX
Example:

"FLUX_MAX"

Response

请求成功

​
code
enum<integer>

响应状态码

  • 200: 成功 - 请求已成功处理
  • 400: 格式错误 - 参数不是有效的 JSON 格式
  • 401: 未授权 - 缺少身份验证凭据或凭据无效
  • 402: 积分不足 - 账户没有足够的积分执行此操作
  • 404: 未找到 - 请求的资源或端点不存在
  • 422: 参数错误 - 请求参数未通过验证检查
  • 429: 超出限制 - 已超过对此资源的请求限制
  • 455: 服务不可用 - 系统当前正在进行维护
  • 500: 服务器错误 - 在处理请求时发生意外错误
    • 构建失败 - 人声移除生成失败
  • 550: 连接被拒绝 - 任务因队列已满而被拒绝，可能是由于源站点问题导致。请联系管理员确认。
可用选项:
200,
400,
401,
402,
404,
422,
429,
455,
500,
550
​
msg
string

当 code != 200 时的错误信息

Example:

"success"

​
data
object