跳转到内容
HiAPI Docs
HiAPI
在线试用 获取 API Key
中文
English 中文

FLUX.1 Kontext Max API

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

图片、视频和音频模型通过统一异步接口 POST /v1/tasks 调用，区别只在 input 字段（见下方 input 参数）。

模型概览

模型名称 flux-1-kontext-max
类型 文生图 / 图片编辑
接口 POST /v1/tasks
价格 见 HiAPI 定价

FLUX.1 Kontext Max 同时支持文生图与单图编辑：写提示词生成新图，或上传一张原图按指令修改，并保持主体、文字与风格一致。

生产建议

生产环境建议
  • 生产环境建议在请求体顶层传 callback.url，让 HiAPI 在任务进入终态时主动通知你的服务，减少无效轮询。
  • GET /v1/tasks/:id 更适合本地调试、低频任务，或作为回调失败后的补偿查询。
  • 产物 URL 有有效期，拿到结果后请及时转存到自己的存储。

适用场景

定向图片编辑

上传一张原图，只改材质、配色、元素或文字，未提到的部分尽量保持。

input_imageprompt
从提示词生成画面

不传原图，用一段描述生成完整场景，并选择六种画幅之一。

promptaspect_ratio
海报与文字排版

替换标题、文案或主色，同时保持版式、字体位置和画面结构。

promptoutput_format

请求参数

model string 必填

固定填 flux-1-kontext-max。

示例 flux-1-kontext-max
input object 必填

业务参数对象。

prompt string 必填

描述要生成的画面；使用原图时，描述要修改和要保留的内容。可使用中文或英文，最多 4000 个字符。

input_image string 可选

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

示例 https://static.hiapi.ai/admin-assets/flux-1-kontext-max/2026/10/26/1793005013365-132a4d4eb55e0852-f-t2i-golden.jpg
aspect_ratio enum 可选

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

可选值: 21:916:94:31:13:49:16
output_format enum 可选

输出图片格式。

默认 jpeg 可选值: jpegpng
prompt_upsampling boolean 可选

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

默认 false 示例 true
safety_tolerance enum 可选

内容审核严格程度：0 最严格，2 最宽松。文生图与编辑两种模式统一提供 0–2。

默认 2 可选值: 012
callback object 可选

可选回调配置。设置后，任务进入终态时 HiAPI 会通知你的服务。

url string 必填

传入 callback 时必填；接收任务终态通知的 HTTPS 地址。

示例 https://your-domain.com/hiapi/callback
when enum 可选

回调触发时机。使用 final。

默认 final 可选值: final

用例示例

从提示词生成一张室内场景

不传 input_image，按提示词生成画面，并指定 16:9 画幅与 jpeg 输出。

请求体
{
  "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,
    "safety_tolerance": 2
  }
}
在原图上做定向编辑

传入一张原图，只描述要替换的椅子和要新增的落地灯；不传 aspect_ratio，结果沿用原图比例。

请求体
{
  "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",
    "output_format": "png"
  }
}
提高审核宽松度并扩写提示词

内容被误拦时可以调高 safety_tolerance；需要更多细节时开启 prompt_upsampling。

请求体
{
  "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": true,
    "safety_tolerance": 2
  }
}

获取结果

  1. 提交成功后立即返回 taskId，不等待生成完成。
  2. 生产环境优先等待 callback.url 收到终态通知；本地调试时可轮询 GET /v1/tasks/:id。
  3. status=success 后，从返回的 output 中取图片地址并下载。
  4. 如果 status=fail，按返回的错误信息修正请求，不要盲目重试同一个无效请求。

常见问题

文生图和图片编辑怎么切换？

不传 input_image 就是文生图；传一张 input_image 就是编辑。两种模式使用同一个模型 ID 和同一个价格。

编辑时能改哪些内容？

可以改风格与材质、替换或增加元素、调整配色与光线、替换画面中的文字。写清要改什么和必须保留什么，未提到的部分会尽量保持。

编辑后画幅会变吗？

不设置 aspect_ratio 时沿用原图比例，实际像素按 32 的倍数微调（例如 1280×720 输出为 1328×752）；设置后按所选比例裁切或补边。

可以上传多张参考图吗？

只支持一张原图。需要多参考图合成、换装或组合素材时，请使用多参考图模型。

提示词可以用中文吗？

可以。中文或其他非英文提示词会先自动翻译成英文再生成；英文提示词原样使用。

输出尺寸和格式是什么？

每张约 100 万像素，编辑输出按 32 的倍数微调，实际像素以任务结果为准；格式可选 jpeg 或 png。

safety_tolerance 应该怎么选？

0 最严格，2 最宽松，默认 2；内容被误拦时调高，需要更严格审核时调低。

怎么计费？

按输出图片张数计费，每次请求返回 1 张；文生图与编辑同价，当前单价见实时价格页。

下一步