欢迎使用 Flux Kontext API

Flux Kontext API 让您能够使用最先进的AI模型生成和编辑高质量图像。无论您是在构建应用、自动化工作流程还是创建内容,我们的API都为AI图像生成和编辑提供了简单可靠的访问方式。
生成的图像存储 14天 并在此期间后自动过期。

身份验证

所有API请求都需要通过Bearer Token进行身份验证。
1

获取您的API密钥

访问 API密钥管理页面 获取您的API密钥。
2

添加到请求头

在所有请求中包含您的API密钥:
Authorization: Bearer YOUR_API_KEY
请妥善保管您的API密钥,切勿公开分享。如果怀疑泄露,请立即在管理页面重置。

基本用法

1. 从文本生成图像

首先创建您的第一个文本转图像生成任务:
async function generateImage() {
  try {
    const response = await fetch('https://api.kie.ai/api/v1/flux/kontext/generate', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        prompt: '一幅宁静的山景,日落时湖泊倒映着橙色的天空',
        aspectRatio: '16:9',
        model: 'flux-kontext-pro'
      })
    });
    
    const result = await response.json();
    
    if (response.ok && result.code === 200) {
      console.log('任务已提交:', result);
      console.log('任务ID:', result.data.taskId);
      return result.data.taskId;
    } else {
      console.error('请求失败:', result.msg || '未知错误');
      return null;
    }
  } catch (error) {
    console.error('错误:', error.message);
    return null;
  }
}

generateImage();
响应:
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_flux_abc123"
  }
}

2. 编辑现有图像

使用文本提示修改现有图像:
async function editImage() {
  try {
    const response = await fetch('https://api.kie.ai/api/v1/flux/kontext/generate', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        prompt: '在天空中添加五颜六色的热气球',
        inputImage: 'https://example.com/landscape.jpg',
        aspectRatio: '16:9'
      })
    });
    
    const result = await response.json();
    
    if (response.ok && result.code === 200) {
      console.log('任务已提交:', result);
      console.log('任务ID:', result.data.taskId);
      return result.data.taskId;
    } else {
      console.error('请求失败:', result.msg || '未知错误');
      return null;
    }
  } catch (error) {
    console.error('错误:', error.message);
    return null;
  }
}

editImage();

3. 检查生成状态

使用返回的 taskId 监控进度:
async function checkStatus(taskId) {
  try {
    const response = await fetch(`https://api.kie.ai/api/v1/flux/kontext/record-info?taskId=${taskId}`, {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    });
    
    const result = await response.json();
    
    if (response.ok && result.code === 200) {
      const taskData = result.data;
      
      switch (taskData.successFlag) {
        case 0:
          console.log('任务生成中...');
          console.log('创建时间:', taskData.createTime);
          return taskData;
          
        case 1:
          console.log('任务生成成功!');
          console.log('结果图像:', taskData.response?.resultImageUrl);
          console.log('原始图像URL(10分钟有效):', taskData.response?.originImageUrl);
          console.log('完成时间:', taskData.completeTime);
          return taskData;
          
        case 2:
          console.log('创建任务失败');
          if (taskData.errorMessage) {
            console.error('错误信息:', taskData.errorMessage);
          }
          if (taskData.errorCode) {
            console.error('错误代码:', taskData.errorCode);
          }
          return taskData;
          
        case 3:
          console.log('生成失败 - 任务创建成功但生成失败');
          if (taskData.errorMessage) {
            console.error('错误信息:', taskData.errorMessage);
          }
          if (taskData.errorCode) {
            console.error('错误代码:', taskData.errorCode);
          }
          return taskData;
          
        default:
          console.log('未知状态:', taskData.successFlag);
          if (taskData.errorMessage) {
            console.error('错误信息:', taskData.errorMessage);
          }
          return taskData;
      }
    } else {
      console.error('查询失败:', result.msg || '未知错误');
      return null;
    }
  } catch (error) {
    console.error('查询状态失败:', error.message);
    return null;
  }
}

// 使用方法
const status = await checkStatus('task_flux_abc123');
状态值:
  • 0: 生成中 - 任务正在处理
  • 1: 成功 - 任务成功完成
  • 2: 创建任务失败 - 创建任务失败
  • 3: 生成失败 - 任务创建成功但生成失败

完整工作流程示例

以下是一个生成图像并等待完成的完整示例:
class FluxKontextAPI {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.kie.ai/api/v1/flux/kontext';
  }
  
  async generateImage(prompt, options = {}) {
    const response = await fetch(`${this.baseUrl}/generate`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        prompt,
        aspectRatio: options.aspectRatio || '16:9',
        model: options.model || 'flux-kontext-pro',
        enableTranslation: options.enableTranslation !== false,
        outputFormat: options.outputFormat || 'jpeg',
        ...options
      })
    });
    
    const result = await response.json();
    if (!response.ok || result.code !== 200) {
      throw new Error(`生成失败: ${result.msg || '未知错误'}`);
    }
    
    return result.data.taskId;
  }
  
  async editImage(prompt, inputImage, options = {}) {
    return this.generateImage(prompt, {
      ...options,
      inputImage
    });
  }
  
  async waitForCompletion(taskId, maxWaitTime = 300000) { // 最长等待5分钟
    const startTime = Date.now();
    
    while (Date.now() - startTime < maxWaitTime) {
      const status = await this.getTaskStatus(taskId);
      
      switch (status.successFlag) {
        case 0:
          console.log('任务生成中,继续等待...');
          break;
          
        case 1:
          console.log('生成成功完成!');
          return status.response;
          
        case 2:
          const createError = status.errorMessage || '创建任务失败';
          console.error('创建任务失败:', createError);
          if (status.errorCode) {
            console.error('错误代码:', status.errorCode);
          }
          throw new Error(createError);
          
        case 3:
          const generateError = status.errorMessage || '生成失败';
          console.error('生成失败:', generateError);
          if (status.errorCode) {
            console.error('错误代码:', status.errorCode);
          }
          throw new Error(generateError);
          
        default:
          console.log(`未知状态: ${status.successFlag}`);
          if (status.errorMessage) {
            console.error('错误信息:', status.errorMessage);
          }
          break;
      }
      
      // 等待3秒后再次检查
      await new Promise(resolve => setTimeout(resolve, 3000));
    }
    
    throw new Error('生成超时');
  }
  
  async getTaskStatus(taskId) {
    const response = await fetch(`${this.baseUrl}/record-info?taskId=${taskId}`, {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`
      }
    });
    
    const result = await response.json();
    if (!response.ok || result.code !== 200) {
      throw new Error(`查询状态失败: ${result.msg || '未知错误'}`);
    }
    return result.data;
  }
}

// 使用示例
async function main() {
  const api = new FluxKontextAPI('YOUR_API_KEY');
  
  try {
    // 文本转图像生成
    console.log('开始图像生成...');
    const taskId = await api.generateImage(
      '夜晚的未来主义城市景观,有霓虹灯和飞行汽车',
      { 
        aspectRatio: '16:9',
        model: 'flux-kontext-max',
        promptUpsampling: true
      }
    );
    
    // 等待完成
    console.log(`任务ID: ${taskId}。等待完成...`);
    const result = await api.waitForCompletion(taskId);
    
    console.log('图像生成成功!');
    console.log('结果图像URL:', result.resultImageUrl);
    console.log('原始图像URL(10分钟有效):', result.originImageUrl);
    
    // 图像编辑示例
    console.log('\n开始图像编辑...');
    const editTaskId = await api.editImage(
      '在天空中添加彩虹',
      result.resultImageUrl,
      { aspectRatio: '16:9' }
    );
    
    const editResult = await api.waitForCompletion(editTaskId);
    console.log('图像编辑成功!');
    console.log('编辑后图像URL:', editResult.resultImageUrl);
    
  } catch (error) {
    console.error('错误:', error.message);
  }
}

main();

高级功能

模型选择

根据您的需求选择合适的模型:
// 标准模型,平衡性能
const taskId = await api.generateImage('美丽的风景', {
  model: 'flux-kontext-pro'
});

// 增强模型,适用于复杂场景和更高质量
const taskId = await api.generateImage('复杂的建筑内部,有精细的细节', {
  model: 'flux-kontext-max'
});

宽高比选项

支持各种图像格式:
const aspectRatios = {
  'ultra-wide': '21:9',    // 电影显示器
  'widescreen': '16:9',    // 高清视频,桌面壁纸
  'standard': '4:3',       // 传统显示器
  'square': '1:1',         // 社交媒体帖子
  'portrait': '3:4',       // 杂志布局
  'mobile': '9:16',        // 智能手机壁纸
  'ultra-tall': '16:21'    // 移动应用启动画面
};

const taskId = await api.generateImage('现代办公空间', {
  aspectRatio: aspectRatios.widescreen
});

提示词增强

让AI优化您的提示词:
const taskId = await api.generateImage('日落', {
  promptUpsampling: true // AI会增强提示词以获得更好的结果
});

安全容忍度控制

调整内容审核级别:
// 用于图像生成(0-6)
const taskId = await api.generateImage('艺术概念', {
  safetyTolerance: 4 // 对艺术内容更宽松
});

// 用于图像编辑(0-2)
const editTaskId = await api.editImage('风格化改变', inputImage, {
  safetyTolerance: 2 // 平衡审核
});

使用回调

设置webhook回调以获得自动通知:
const taskId = await api.generateImage('数字艺术杰作', {
  aspectRatio: '1:1',
  callBackUrl: 'https://your-server.com/flux-callback'
});

// 您的回调端点将接收:
app.post('/flux-callback', (req, res) => {
  const { code, data } = req.body;
  
  if (code === 200) {
    console.log('图像准备就绪:', data.info.resultImageUrl);
  } else {
    console.log('生成失败:', req.body.msg);
  }
  
  res.status(200).json({ status: 'received' });
});

了解更多关于回调

设置webhook回调以在图像准备就绪时接收自动通知。

错误处理

常见错误场景及处理方法:

最佳实践

性能优化

  1. 使用回调:设置webhook回调而不是轮询以获得更好的性能
  2. 模型选择:对标准任务使用 flux-kontext-pro,对复杂场景使用 flux-kontext-max
  3. 提示词工程:使用详细、具体的提示词以获得更好的结果
  4. 图像预处理:确保输入图像可访问且经过优化
  5. 下载管理:及时下载图像,因为它们14天后会过期
  6. 翻译设置:如果您的提示词已经是英文,请设置 enableTranslation: false

重要限制

  • 语言支持:提示词仅支持英文(使用 enableTranslation: true 进行自动翻译)
  • 图像存储:生成的图像14天后过期
  • 原始图像URL:生成后仅10分钟有效
  • 安全容忍度:生成模式(0-6),编辑模式(0-2)
  • 输入图像:必须是公开可访问的URL

支持的参数

核心参数

参数类型描述默认值
promptstring必需。生成/编辑的文本描述-
aspectRatiostring输出图像宽高比16:9
modelstringflux-kontext-proflux-kontext-maxflux-kontext-pro
outputFormatstringjpegpngjpeg

可选参数

参数类型描述默认值
inputImagestring图像编辑模式的URL-
enableTranslationboolean自动翻译非英文提示词true
promptUpsamplingbooleanAI提示词增强false
safetyToleranceinteger内容审核级别2
callBackUrlstringWebhook通知URL-
uploadCnboolean使用中国服务器上传false
watermarkstring水印标识符-

下一步

支持

需要帮助吗?我们的技术支持团队随时为您提供帮助。 准备创建令人惊叹的AI图像了吗?从上面的示例开始,探索完整的API功能!