跳转到主要内容
POST
/
api
/
v1
/
flux
/
kontext
/
generate
生成或编辑图像
curl --request POST \
  --url https://api.kie.ai/api/v1/flux/kontext/generate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "A serene mountain landscape at sunset with a lake reflecting the orange sky",
  "enableTranslation": true,
  "aspectRatio": "16:9",
  "outputFormat": "jpeg",
  "promptUpsampling": false,
  "model": "flux-kontext-pro"
}
'
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task12345"
  }
}

​
使用模式

  1. 文本到图像生成
    • 提供 prompt 和 aspectRatio
    • 模型将根据文本描述生成新图像
  2. 图像编辑
    • 提供 prompt 和 inputImage
    • 您可以选择性地提供 aspectRatio。
      • 如果提供，输出将被裁剪或填充以匹配此比例。
      • 如果省略，将保持原始图像的比例。
    • 模型将根据提示编辑输入图像

​
重要说明

  • 生成的图像将在14天后过期
  • 提示仅支持英文
  • 根据您的需求选择合适的模型：
    • flux-kontext-pro：适用于大多数用例的标准模型
    • flux-kontext-max：适用于复杂场景的增强模型

授权

​
Authorization
string
header
必填

所有 API 都需要通过 Bearer Token 进行认证。

获取 API Key：

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

使用方法： 添加到请求头： Authorization: Bearer YOUR_API_KEY

注意：

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

请求体

application/json
​
prompt
string
必填

描述所需图像或编辑的文本提示词。生成和编辑模式都需要。

  • 应该详细且具体
  • 对于图像编辑，描述所需的更改
  • 对于图像生成，描述完整的场景
  • 重要：仅支持英文
示例:

"A serene mountain landscape at sunset with a lake reflecting the orange sky"

​
enableTranslation
boolean

是否启用自动翻译功能。

  • 由于 prompt 仅支持英文，当此参数为 true 时，系统会自动将非英文的提示词翻译成英文
  • 如果您的提示词已经是英文，可设置为 false
  • 默认值：true
示例:

true

​
uploadCn
boolean

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

示例:

false

​
inputImage
string<uri>

编辑模式的输入图像 URL。编辑现有图像时需要。

  • 必须是有效的图像 URL
  • 图像必须能被 API 服务器访问
示例:

"https://example.com/input-image.jpg"

​
aspectRatio
enum<string>
默认值:16:9

输出图像的长宽比。适用于文本到图像生成和图像编辑两种模式。

对于文本到图像生成，输出图像将遵循指定的长宽比。

对于图像编辑，如果提供了aspectRatio参数，编辑后的图像将遵循该比例。如果未提供，图像将保持其原始长宽比。

支持的长宽比：

比例格式类型常见用途
21:9超宽屏电影显示、全景视图
16:9宽屏高清视频、桌面壁纸
4:3标准传统显示器、演示文稿
1:1正方形社交媒体帖子、头像
3:4竖版杂志版面、人像照片
9:16手机竖屏智能手机壁纸、故事

注意：如果未指定，默认比例为"16:9"。

可用选项:
21:9,
16:9,
4:3,
1:1,
3:4,
9:16
​
outputFormat
enum<string>
默认值:jpeg

输出图像格式

可用选项:
jpeg,
png
​
promptUpsampling
boolean
默认值:false
  • 如果为 true，将对提示词进行增强处理
  • 可能会增加处理时间
​
model
enum<string>
默认值:flux-kontext-pro

用于生成的模型版本。

可用选项：

模型描述
flux-kontext-pro性能平衡的标准模型
flux-kontext-max具有高级功能的增强模型

注意：对于需要更高质量和细节的复杂任务，请选择 flux-kontext-max

可用选项:
flux-kontext-pro,
flux-kontext-max
​
callBackUrl
string<uri>

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

  • 系统将在图像生成或编辑完成时向此URL发送POST请求，包含任务状态和结果
  • 回调包含生成的图像URL和任务信息，支持文本生成图像和图像编辑两种操作模式
  • 您的回调端点应能接受包含图像结果的JSON载荷的POST请求
  • 详细的回调格式和实现指南，请参见 图像生成/编辑回调
  • 或者，您也可以使用获取图像详情接口来轮询任务状态
示例:

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

​
safetyTolerance
enum<integer>
默认值:2

图像生成模式： 输入和输出的审核级别。值范围从 0（最严格）到 6（更宽松）。

图像编辑模式： 输入和输出的审核级别。值范围从 0（最严格）到 2（平衡）。

默认值：2

可用选项:
0,
1,
2,
3,
4,
5,
6
示例:

2

​
watermark
string

要添加到生成图像的水印标识符。

  • 可选
  • 如果提供，将在输出图像上添加水印
示例:

"your-watermark-id"

响应

请求成功

​
code
enum<integer>

响应状态码

  • 200: 成功 - 请求已成功处理
  • 401: 未授权 - 认证凭据缺失或无效
  • 402: 积分不足 - 账户没有足够的积分执行操作
  • 404: 未找到 - 请求的资源或端点不存在
  • 422: 验证错误 - 请求参数验证失败.请求参数不正确，请检查参数。
  • 429: 请求限制 - 已超过该资源的请求限制
  • 455: 服务不可用 - 系统正在进行维护
  • 500: 服务器错误 - 处理请求时发生意外错误 服务器错误 - 安全容忍级别超出范围，应为 0-2 或 0-6
  • 501: 生成失败 - 图像生成任务失败
  • 505: 功能禁用 - 请求的功能当前已禁用
可用选项:
200,
401,
402,
404,
422,
429,
455,
500,
501,
505
​
msg
string

当 code != 200 时的错误信息

示例:

"success"

​
data
object