当您向 Flux Kontext API 提交图像生成或编辑任务时，可以通过 callBackUrl 参数设置回调地址。任务完成后，系统会自动将结果推送到您指定的地址。

​
回调机制概述

回调机制避免了您需要轮询 API 查询任务状态，系统会主动推送任务完成结果到您的服务器。

​
回调时机

系统会在以下情况发送回调通知：
  • 图像生成或编辑任务成功完成
  • 图像生成或编辑任务失败
  • 任务处理过程中发生错误

​
回调方式

  • HTTP 方法: POST
  • 内容类型: application/json
  • 超时设置: 15 秒
  • 重试机制: 失败后重试 3 次，间隔分别为 1 分钟、5 分钟、15 分钟

​
回调请求格式

任务完成后，系统会向您的 callBackUrl 发送 POST 请求，格式如下： 
{
  "code": 200,
  "msg": "BFL 图像生成成功。",
  "data": {
    "taskId": "task12345",
    "info": {
      "originImageUrl": "https://example.com/original.jpg",
      "resultImageUrl": "https://example.com/result.jpg"
    }
  }
}

​
状态码说明

​
code
integer
required
回调状态码，表示任务处理结果：
状态码说明
200成功 - 图像生成成功
400失败 - 您的提示词被网站标记为违反内容政策
500失败 - 内部错误，请稍后重试
501失败 - 图像生成任务失败
​
msg
string
required
状态消息，提供详细的状态描述
​
data.taskId
string
required
任务 ID，与您提交任务时返回的 taskId 一致
​
data.info.originImageUrl
string
原始图像 URL，有效期为 10 分钟。仅在成功时存在。
​
data.info.resultImageUrl
string
生成图像在我们服务器上的 URL。仅在成功时存在。

​
回调接收示例

以下是用流行编程语言接收回调的示例代码： 
const express = require('express');
const fs = require('fs');
const https = require('https');
const app = express();

app.use(express.json());

app.post('/flux-image-callback', (req, res) => {
  const { code, msg, data } = req.body;
  
  console.log('收到 Flux 图像生成回调:', {
    taskId: data.taskId,
    status: code,
    message: msg
  });
  
  if (code === 200) {
    // 任务成功完成
    console.log('Flux 图像生成成功完成');
    
    const { taskId, info } = data;
    const { originImageUrl, resultImageUrl } = info;
    
    console.log(`原始图像 URL: ${originImageUrl}`);
    console.log(`生成图像 URL: ${resultImageUrl}`);
    console.log('注意：原始图像 URL 有效期为 10 分钟');
    
    // 下载生成的图像
    if (resultImageUrl) {
      downloadFile(resultImageUrl, `flux_result_${taskId}.jpg`)
        .then(() => console.log('生成图像下载成功'))
        .catch(err => console.error('生成图像下载失败:', err));
    }
    
    // 下载原始图像（如果需要）
    if (originImageUrl) {
      downloadFile(originImageUrl, `flux_original_${taskId}.jpg`)
        .then(() => console.log('原始图像下载成功'))
        .catch(err => console.error('原始图像下载失败:', err));
    }
    
  } else {
    // 任务失败
    console.log('Flux 图像生成失败:', msg);
    
    // 处理特定错误类型
    if (code === 400) {
      console.log('内容政策违规 - 请调整提示词');
    } else if (code === 500) {
      console.log('内部错误 - 请稍后重试');
    } else if (code === 501) {
      console.log('生成任务失败 - 可能需要调整参数');
    }
  }
  
  // 返回 200 状态码确认收到回调
  res.status(200).json({ status: 'received' });
});

// 辅助函数：下载文件
function downloadFile(url, filename) {
  return new Promise((resolve, reject) => {
    const file = fs.createWriteStream(filename);
    
    https.get(url, (response) => {
      if (response.statusCode === 200) {
        response.pipe(file);
        file.on('finish', () => {
          file.close();
          resolve();
        });
      } else {
        reject(new Error(`HTTP ${response.statusCode}`));
      }
    }).on('error', reject);
  });
}

app.listen(3000, () => {
  console.log('回调服务器运行在端口 3000');
});

​
最佳实践

​
回调 URL 配置建议

  1. 使用 HTTPS: 确保回调 URL 使用 HTTPS 协议，保证数据传输安全
  2. 验证来源: 在回调处理中验证请求来源的合法性
  3. 幂等处理: 同一个 taskId 可能收到多次回调，确保处理逻辑是幂等的
  4. 快速响应: 回调处理应尽快返回 200 状态码，避免超时
  5. 异步处理: 复杂的业务逻辑应异步处理，避免阻塞回调响应
  6. 及时下载: 原始图像 URL 只有 10 分钟有效期，收到成功回调后应及时下载

​
重要提醒

  • 回调 URL 必须是公网可访问的地址
  • 服务器必须在 15 秒内响应，否则会被认为是超时
  • 连续 3 次重试失败后，系统将停止发送回调
  • 原始图像 URL 10 分钟后过期 - 收到回调后请及时下载
  • 请确保回调处理逻辑的稳定性，避免因异常导致回调失败
  • 需要处理多种错误状态码（400, 500, 501），实现完整的错误处理
  • 注意内容政策违规问题，及时调整提示词

​
故障排查

如果没有收到回调通知，请检查以下几点：

​
替代方案

如果无法使用回调机制，您也可以使用轮询方式：

轮询查询结果

使用获取图像详情接口定期查询任务状态，建议每 30 秒查询一次。