KIE.AI
Chinese
  • English
  • Chinese
Chinese
  • English
  • Chinese
Support
Chinese
  • English
  • Chinese
MarketVeo3.1 APISuno API4o Image API
Flux Kontext APIRunway APILuma APIFile Upload APICommon API
MarketVeo3.1 APISuno API4o Image API
Flux Kontext APIRunway APILuma APIFile Upload APICommon API
  1. 4o Image API
  • 4o Image API 快速开始
  • 4o 图片生成回调
  • 生成4o图像
    POST
  • 获取4o图像详情
    GET
  • 获取直接下载URL
    POST
Chinese
  • English
  • Chinese
Support
Chinese
  • English
  • Chinese
MarketVeo3.1 APISuno API4o Image API
Flux Kontext APIRunway APILuma APIFile Upload APICommon API
MarketVeo3.1 APISuno API4o Image API
Flux Kontext APIRunway APILuma APIFile Upload APICommon API
  1. 4o Image API

4o 图片生成回调

当4o Image任务完成后,系统会向您提供的回调URL发送POST请求通知结果
当您向4o Image API提交图片生成任务时,可以使用 callBackUrl 参数设置回调URL。任务完成时,系统将自动向您指定的地址推送结果。

回调机制概述#

回调机制消除了轮询API获取任务状态的需要。系统会主动向您的服务器推送任务完成结果。
Webhook 安全性:为确保回调请求的真实性和完整性,我们强烈建议您实现 webhook 签名验证。请参阅我们的 Webhook 校验指南 了解详细实现步骤。

回调时机#

系统将在以下情况发送回调通知:
4o 图片生成任务成功完成
4o 图片生成任务失败
任务处理过程中发生错误

回调方式#

HTTP方法: POST
内容类型: application/json
超时设置: 15秒

回调请求格式#

任务完成时,系统将以下格式向您的 callBackUrl 发送POST请求:
成功回调
失败回调
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task12345",
    "info": {
      "result_urls": [
        "https://example.com/result/image1.png"
      ]
    }
  }
}

状态码说明#

参数说明#

参数类型必需描述
codeinteger是回调状态码,表示任务处理结果
msgstring是状态消息,提供更详细的状态描述
data.taskIdstring是任务ID,与您提交任务时返回的taskId一致
data.infoobject否图片生成结果信息,成功时返回
data.info.result_urlsarray否生成的图片URL列表,成功时返回可访问的下载链接

状态码详情#

状态码描述
200成功 - 图片生成完成
400参数错误 - filesUrl 参数中的图片内容违反内容政策、图片尺寸超过最大限制、无法处理提供的图片文件、内容被 OpenAI 标记为违反内容政策
451下载失败 - 无法从提供的 filesUrl 下载图片
500服务器错误 - 请稍后重试、获取用户令牌失败、生成图片失败、GPT 4O 编辑图片失败

回调接收示例#

以下是常用编程语言接收回调的示例代码:
Node.js
Python
PHP

最佳实践#

回调URL配置建议
1.
使用HTTPS: 确保回调URL使用HTTPS协议以保证数据传输安全
2.
验证来源: 在回调处理中验证请求来源的合法性
3.
幂等处理: 同一taskId可能收到多次回调,确保处理逻辑是幂等的
4.
快速响应: 回调处理应尽快返回200状态码以避免超时
5.
异步处理: 复杂的业务逻辑应异步处理以避免阻塞回调响应
6.
图片处理: 图片下载和处理应在异步任务中进行,避免阻塞回调响应
重要提醒
回调URL必须是公开可访问的地址
服务器必须在15秒内响应,否则将被认为超时
如果连续3次重试失败,系统将停止发送回调
请确保回调处理逻辑的稳定性,避免因异常导致回调失败
生成的图片URL可能有时效性,建议及时下载保存
注意内容政策合规,避免违规内容导致生成失败

故障排查#

如果您未收到回调通知,请检查以下内容:
网络连接问题
服务器响应问题
内容格式问题
图片处理问题

替代方案#

如果您无法使用回调机制,也可以使用轮询方式:
轮询查询结果
使用获取4o图片详情端点定期查询任务状态。我们建议每30秒查询一次。
Previous
4o Image API 快速开始
Next
生成4o图像
Built with