Black Forest Labs

FLUX.1 Kontext Max

flux-1-kontext-max

Kontext 系列的旗舰图像编辑版本，擅长按自然语言指令做局部修改，提示词遵循和画面文字排版更强，适合品牌视觉与分镜批量产出

flux-1-kontext-max

试用 flux-1-kontext-max

输入

作品灵感

查看全部作品

输出

image

填写参数并生成，结果会显示在这里。

价格

flux-1-kontext-max 每张

单价	$0.0715

定位简介

FLUX.1 Kontext Max 是 Black Forest Labs 推出的图像生成与编辑模型，通过 HiAPI.ai 统一接口调用。它支持文生图与单图编辑：提供原图时按提示词改动指定内容、保留其余部分；省略原图则按提示词生成新图。相较系列内低阶版本，它在提示词遵循度和画面内文字排版上更强，适合需要精确控制编辑范围、保持画面一致性的开发者与内容生产团队。

核心亮点

局部编辑保留未指定区域——只需用提示词说明要改的颜色、物体、背景或风格，其余画面内容尽量维持原样。
系列内提示词遵循与文字排版最强——作为 Kontext 系列最高档版本，复杂编辑意图的执行和画面内文字呈现更准确、干净。
文生图与图生图共用一套参数——同一接口下切换是否传入原图，即可在全新生成与基于原图编辑之间选择。
宽高比与审核强度可调——支持六种输出比例、jpeg/png 格式，以及 0 到 2 级的内容审核宽松度。

能力说明

自然语言局部编辑：传入单张原图与提示词，模型只改动描述涉及的部分，未提及的区域保持不变，适合在已有素材上快速迭代。

文生图生成：不传原图时按提示词生成全新图像，可用同一接口完成从零出图与后续编辑的衔接。

画面内文字处理：系列内文字排版表现最好，适合在图像中生成或修改文案并保持可读性与整洁度。

比例与格式控制：编辑时留空比例沿用原图，指定后按目标比例裁切或补边；输出可选 jpeg 或 png，便于直接对接下游流程。

提示词改写开关：可选择开启提示词上采样以补充细节与创意，或关闭以确保严格按原文生成。

适用场景

营销团队修改已有品牌素材——输入成品海报或横幅并指明替换的颜色、物体或背景，得到可直接投放的变体图。
设计者调整画面内文案——在既有视觉稿上按提示词替换文字与排版，产出可用于广告位或社媒的成图。
分镜与多场景内容生产——以同一风格底图逐张编辑，得到镜头连贯、风格统一的系列画面用于故事板。
产品图局部替换——上传产品照片并指定更换背景或配色，产出电商详情页与展示页所需的成品图。

限制与选型建议

仅支持单张原图输入，无法通过多图参考维持角色一致性；定位以图像编辑与指定区域修改为主，纯文生图不是其主要优势。作为闭源托管模型，无法本地部署，也不适合需要自行掌控推理环境的场景。按张计费，大批量高频编辑时成本需纳入评估；若只需简单颜色或背景调整等日常编辑，可考虑同系列更低档版本以控制开销。

近期更新

查看更新日志 →

参数变更 flux-1-kontext-max 参数与价格更新
模型上新 flux-1-kontext-max 上线

提交生成任务

POST https://api.hiapi.ai/v1/tasks

请求头

Authorizationstring必填

账号 API Key，所有请求必填。示例：Bearer YOUR_HIAPI_API_KEY。获取 API Key

Content-Typestring可选

请求体固定按 JSON 解析；如携带，仅接受 application/json（可带 charset），其他取值返回 415。示例：application/json。

Idempotency-Keystring可选

幂等键，最长 255 字节。同账户同键的重试只创建一次任务，重放返回首次 taskId。

幂等键

网络超时或客户端自动重试时，同键只创建一次任务、不会重复扣费（幂等范围 = API Key 所属账户）。建议用业务侧唯一标识做键（如 "order-42"）；同键重放返回首次 taskId，键在首次提交 24 小时后过期。详细的场景矩阵见统一异步接口介绍页。

请求体

modelstring必填

当前固定值：flux-1-kontext-max

routestring可选

当前固定值：default

inputobject必填

flux-1-kontext-max 和线路 default 的业务参数对象，见下方参数表。

promptstring必填minLength 1maxLength 4000

描述要生成的图片内容；使用原图时需说明哪些部分要修改、哪些要保留。支持中文或英文，非英文提示词会先自动翻译为英文再生成。

input_imagestring可选

可选的原图地址，仅支持单张。提供后在该图基础上按提示词进行编辑；省略时按提示词生成全新图片。

aspect_ratiostring可选

输出图片的宽高比。编辑时留空则沿用原图比例（实际像素按 32 的倍数微调），指定后按该比例裁切或补边；文生图时留空由模型自行选择画幅。

可选项：21:916:94:31:13:49:16

output_formatstring可选默认值: "jpeg"

输出文件格式，可选 jpeg 或 png，默认 jpeg。

可选项：jpegpng

safety_toleranceinteger可选默认值: 2

内容审核的严格程度，取值 0 到 2，0 最严格、2 最宽松；文生图与编辑两种模式均提供 0–2，默认 2。

可选项：012

prompt_upsamplingboolean可选默认值: false

是否开启提示词自动改写以增加细节与创意，开启后耗时略长；需要严格按原文生成时应关闭，默认 false。

callbackobject可选

终态通知配置；为空则不回调，由调用方自行查询。详见下方回调说明。

回调（Webhook）

创建任务时提供 callback.url，任务终态时 HiAPI 主动 POST 通知你的服务，可免去轮询。回调请求体与任务详情数据结构同构；签名校验、投递重试与幂等说明见统一异步接口介绍页的回调说明。

urlstring必填

callback 存在时必填；任务终态后向该 URL 发起 POST，须为合法 http(s) URL。

whenstring可选默认值: "final"

当前仅支持 final，即 success / fail 均回调。

可选项：final

storagestring可选默认值: "temp"

产物存储档位：temp（默认，保留约 7 天）或 persistent（长期保存，按大小计费）。余额不足或超出存储上限会静默降级为 temp；实际生效档位见任务详情响应。

可选项：temppersistent

请求示例

# 提交异步任务，成功立即返回 taskId（不等待生成完成）
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "flux-1-kontext-max",
  "input": {
    "prompt": "…",
    "output_format": "jpeg",
    "safety_tolerance": 2,
    "prompt_upsampling": false
  }
}'

const res = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "flux-1-kontext-max",
    input: {
      "prompt": "…",
      "output_format": "jpeg",
      "safety_tolerance": 2,
      "prompt_upsampling": false
    }
  }),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } }

import os, requests

res = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "flux-1-kontext-max",
        "input": {
          "prompt": "…",
          "output_format": "jpeg",
          "safety_tolerance": 2,
          "prompt_upsampling": False
        }
    },
)
print(res.json())  # { code, message, data: { taskId } }

200 OK

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR"
  }
}

400 Bad Request

{
  "code": 400,
  "message": "invalid request",
  "data": null,
  "error_code": "INVALID_REQUEST"
}

获取任务详情

GET https://api.hiapi.ai/v1/tasks/:id

响应字段

taskIdstring必填

任务 ID，前缀固定 tk-hiapi-。

modelstring必填

解析后的模型全名。用 route 参数提交的任务返回 base@线路（如 gpt-image-2/text-to-image@ext）；否则与创建时传入的模型名一致。

routestring可选

仅当任务用显式 route 参数提交时出现，回显提交时的原值。

statusstring必填

任务状态。

状态枚举

queued 已入队，尚未开始。 handling 处理中。 archiving 处理完成，产物准备中。 success 终态：完成，产物可用（返回 output）。 fail 终态：失败（返回 error）。提交后按 status 判断：success 或 fail 为终态，其余为非终态，建议按 1~3 秒间隔轮询直至终态。成功终态后从 output[].url 下载产物，并在 expireAt 前完成下载或转存；需要长期保留时在创建任务时使用 storage: "persistent"。

creatednumber必填

任务创建时间（Unix 秒）。

completednumber必填

进入终态的 Unix 秒；非终态固定为 0。

outputarray可选

仅 status == success 时出现。产物列表，始终为数组，同一任务可能同时返回多个 type（如 video + first_frame）。

Array [ object ]

数组元素

urlstring必填

资源 URL，可直接下载。

typestring必填

当前可能值：video、image、audio、first_frame、last_frame、thumbnail，后续可能会扩展。

expireAtnumber必填

资源可访问截止时间（Unix 秒）；过期前请完成下载或转存。

errorobject可选

仅 status == fail 时出现。

codestring必填

业务错误码。

messagestring必填

错误描述。

响应示例

成功

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "happyhorse-1-0",
    "status": "success",
    "created": 1777282033,
    "completed": 1777282099,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
        "type": "video",
        "expireAt": 1777886899
      }
    ]
  }
}

处理中（非终态）

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "archiving",
    "created": 1777282033,
    "completed": 0
  }
}

失败

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": {
      "code": "TASK_FAILED",
      "message": "task failed"
    }
  }
}