FLUX.1 Kontext Max API 怎么用？5 分钟跑通第一张图

TL;DR

• 它是什么：Black Forest Labs 出品的 FLUX.1 Kontext Max，文生图和单图编辑共用一个模型 ID。已在 HiAPI 上线，打开模型页 输入提示词就能生成，新用户注册送 200 积分，约合 1.4 张图。
• 多少钱：每张 $0.0715（143 积分），文生图和编辑同价，$10 能出约 139 张；失败任务退回预扣。
• API 怎么调：POST https://api.hiapi.ai/v1/tasks，model 写 flux-1-kontext-max，拿到 taskId 后轮询或等回调，从 data.output[0].url 下载结果。

FLUX.1 Kontext Max 上线后，常被问到两件事：改图能不能只动一处，接进自己的产品要多久。先看能力，再走两条上手路线。

FLUX.1 Kontext Max 是什么，新在哪？

• 一个模型 ID 管两种任务。 input 里不传图就是文生图，传了 input_image 就是编辑，代码不用分两套。
• 编辑按“改什么、留什么”执行。 材质与风格、增删元素、配色与光线、画面文字都能改；提示词里没提到的部分尽量保持原样。
• 六种画幅，编辑时还能沿用原图比例。 aspect_ratio 可选 21:9、16:9、4:3、1:1、3:4、9:16；编辑时留空就按原图比例输出，像素按 32 的倍数微调，1280×720 会变成 1328×752。
• 输出 jpeg 或 png，每张约 100 万像素。 prompt 上限 4,000 字符，中文提示词会自动翻成英文再生成。

文生图，16:9。完整提示词就是下面 curl 里的那条，可原样复制。

用这个提示词生成 →

两条上手路线：在线试用，还是 API？

先看效果走在线试用，要接进产品走 API。两条路用的是同一个模型、同一套价格。

在线试用（约 1 分钟）

1. 打开 FLUX.1 Kontext Max 模型页，或点上图下方的链接，提示词会自动填好。
2. 注册或登录，新账号自带 200 积分。
3. 选 16:9，点生成。
4. 满意就下载；想改图，在同一页上传原图再写编辑提示词。

API 接入（约 5 分钟）

1. 在 HiAPI 控制台 创建 API Key（sk-...）。
2. POST /v1/tasks 创建任务，响应里拿到 data.taskId。
3. 用 GET /v1/tasks/{taskId} 查询或等 callback.url 通知，data.status 变成 success 后从 data.output[0].url 下载图片。

每张 $0.0715，$10 能出约 139 张，够把提示词调到满意。完整参数见 中文文档。

第一张图：curl 版

创建任务：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1-kontext-max",
    "input": {
      "prompt": "A quiet reading corner by a tall window at golden hour: a linen armchair, a stack of art books and a ceramic cup on a walnut side table, warm afternoon light, soft shadows, editorial interior photography.",
      "aspect_ratio": "16:9",
      "output_format": "jpeg",
      "prompt_upsampling": false
    }
  }'

返回的任务 ID 在 data.taskId：

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

查询结果：

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

必填的只有 prompt。output_format 默认 jpeg，prompt_upsampling 默认关闭，safety_tolerance 默认 2（0 最严格）。

第一张图：Python 版

创建、轮询、下载一次写完，换上自己的 Key 就能跑：

import requests, time

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY"}

payload = {
    "model": "flux-1-kontext-max",
    "input": {
        "prompt": "A quiet reading corner by a tall window at golden hour: a linen armchair, a stack of art books and a ceramic cup on a walnut side table, warm afternoon light, soft shadows, editorial interior photography.",
        "aspect_ratio": "16:9",
    },
}

task_id = requests.post(API, headers=HEADERS, json=payload, timeout=30).json()["data"]["taskId"]

while True:
    data = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if data["status"] in ("success", "fail"):
        break
    time.sleep(2)

if data["status"] == "success":
    image_url = data["output"][0]["url"]
    with open("flux-1-kontext-max.jpg", "wb") as f:
        f.write(requests.get(image_url, timeout=60).content)
else:
    print(data.get("error"))

编辑模式：加一个 input_image 就够

在 input 里加上 input_image，同一个请求就从文生图变成编辑。下面把上面那张阅读角当原图，只换扶手椅、加一盏落地灯：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1-kontext-max",
    "input": {
      "prompt": "Change the linen armchair to a deep forest-green velvet armchair, add a slim brass floor lamp beside it, and keep the window, books, cup, table and afternoon light unchanged.",
      "input_image": "https://static.hiapi.ai/admin-assets/flux-1-kontext-max/2026/10/26/1793005013365-132a4d4eb55e0852-f-t2i-golden.jpg"
    }
  }'

input_image 收一张公网可访问的图片 URL。编辑时不写 aspect_ratio，输出沿用原图比例；要多图融合，选 GPT Image 2 图片编辑，支持 1–16 张参考图。

编辑提示词怎么写：先说要改什么，再列要留什么

1. 改动写成一句明确指令。 把对象和新状态写具体：linen armchair 换成 deep forest-green velvet armchair。
2. 保留项逐个点名。 窗户、书、杯子、桌子、午后光线，原图里在意什么就写什么，用 keep ... unchanged 收尾。
3. 相关改动可以放在一句里。 换椅子的同时加一盏黄铜落地灯，模型会一起处理；互不相关的修改分开提交，结果更好核对。
4. 改画面文字时连排版一起保。 比如把海报上的 KYOTO 改成 OSAKA，同时说明版式、留白、字体风格保持原样。
5. 中文可以直接写。 系统会先翻成英文再生成，提示词控制在 4,000 字符以内。

上线前注意这 4 件事

1. 服务端用回调。 在请求体里加 "callback": {"url": "https://yourapp.com/webhook", "when": "final"}，任务到终态自动通知，省掉轮询。
2. 超时不要重复 POST。 每次创建都会新建任务并单独计费，先存 taskId，重试前在自己系统里去重。
3. 产物链接会过期。 data.output[0].url 是临时链接，拿到就下载，转存到自己的存储。
4. 像素按 32 的倍数对齐。 编辑时留空 aspect_ratio，原图比例不变、像素微调到 32 的倍数，1280×720 输出 1328×752；指定比例则按该比例裁切或补边。

常见问题

文生图和编辑要换模型吗？ 不用。同一个 flux-1-kontext-max，传不传 input_image 决定走哪条路，价格也一样。

一次能传几张参考图？ 一张。要多图融合，选 GPT Image 2 图片编辑，支持 1–16 张参考图。

中文提示词能用吗？ 能。提示词上限 4,000 字符，中文会自动翻成英文后生成。

编辑后画幅会变吗？ 不写 aspect_ratio 就沿用原图比例，像素按 32 的倍数微调；写了就按指定比例裁切或补边。

任务失败会扣费吗？ 按成功输出的图片张数计费，每次请求返回 1 张，失败任务退回预扣。

把上面阅读角的提示词复制到 FLUX.1 Kontext Max 模型页，选 16:9，点一次生成，先看它怎么处理光线和材质，再决定要不要接进项目。