Black Forest Labs

FLUX.1 Kontext Max

flux-1-kontext-max

The flagship image editing version of the Kontext series, skilled at making local edits according to natural language instructions, with stronger prompt adherence and in-image text layout, suitable for brand visuals and batch storyboard production

flux-1-kontext-max

Try flux-1-kontext-max

Input

Output

Fill in the parameters and run — results show up here.

Pricing

flux-1-kontext-max per image

Unit Price	$0.0715

Positioning Overview

FLUX.1 Kontext Max is an image generation and editing model released by Black Forest Labs, accessible through the unified HiAPI.ai interface. It supports text-to-image generation and single-image editing: when an original image is provided, it modifies the specified content according to the prompt while preserving the rest; when the original image is omitted, it generates a new image from the prompt. Compared with lower-tier versions in the series, it is stronger at prompt adherence and in-image text layout, making it suitable for developers and content production teams that need precise control over the editing scope and visual consistency.

Key Highlights

Local editing that preserves unspecified regions — simply describe the colors, objects, background, or style to change in the prompt, and the rest of the image is kept as unchanged as possible.
Strongest prompt adherence and text layout in the series — as the top-tier version of the Kontext series, it executes complex editing intents and renders in-image text more accurately and cleanly.
One set of parameters for both text-to-image and image-to-image — within the same interface, toggling whether an original image is passed lets you choose between generating from scratch and editing based on an original image.
Adjustable aspect ratio and moderation strength — supports six output ratios, jpeg/png formats, and content moderation leniency levels from 0 to 2.

Capabilities

Natural-language local editing: pass a single original image and a prompt, and the model changes only the parts covered by the description while leaving unmentioned regions unchanged, ideal for rapid iteration on existing assets.

Text-to-image generation: when no original image is passed, it generates a brand-new image from the prompt, allowing the same interface to connect from-scratch generation and subsequent editing.

In-image text handling: the best text layout performance in the series, suitable for generating or modifying copy within images while keeping it readable and neat.

Ratio and format control: when editing, leaving the ratio empty retains the original image's ratio; specifying one crops or pads to the target ratio. Output can be jpeg or png for direct integration into downstream workflows.

Prompt rewriting toggle: enable prompt upsampling to add detail and creativity, or disable it to ensure strict generation from the original text.

Use Cases

Marketing teams modifying existing brand assets — input a finished poster or banner and specify the colors, objects, or background to replace, yielding variant images ready for publication.
Designers adjusting in-image copy — replace text and layout on existing visual drafts via prompts, producing finished images for ad placements or social media.
Storyboarding and multi-scene content production — edit a base image with the same style one by one to get a series of shots with consistent framing and style for storyboards.
Local replacement in product photos — upload a product photo and specify a new background or color scheme, producing finished images for e-commerce detail pages and display pages.

Limitations and Selection Advice

Only a single original image input is supported, so character consistency cannot be maintained through multi-image references; its positioning centers on image editing and modifying specified regions, and pure text-to-image is not its main strength. As a closed-source hosted model, it cannot be deployed locally and is not suitable for scenarios requiring self-controlled inference environments. Billing is per image, so cost must be factored in for high-volume, high-frequency editing; for everyday edits such as simple color or background adjustments, consider lower-tier versions in the same series to control expenses.

Create a generation task

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

Headers

AuthorizationstringRequired

Account API key. Required on every request. Example: Bearer YOUR_HIAPI_API_KEY. Get your API key

Content-TypestringOptional

The request body is always parsed as JSON; when sent, only application/json (optionally with charset) is accepted — any other value returns 415. Example: application/json.

Idempotency-KeystringOptional

Idempotency key, up to 255 bytes. Retries with the same key from the same account create the task only once; replays return the original taskId.

Idempotency key

On network timeouts or client retries, the same key creates the task only once — no double charges (scope: the API key's account). Use a business-unique identifier as the key (e.g. "order-42"); replays return the original taskId, and keys expire 24 hours after the first request. See the Unified Async API overview for the full scenario matrix.

Body

modelstringRequired

Current fixed value: flux-1-kontext-max

routestringOptional

Current fixed value: default

inputobjectRequired

Business parameters for flux-1-kontext-max and route default — see the parameter table below.

promptstringRequiredminLength 1maxLength 4000

描述要生成的图片；使用原图时，描述需要修改和需要保留的内容。可用中文或英文，非英文提示词会先自动转成英文再生成。

input_imagestringOptional

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

aspect_ratiostringOptional

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

Options:21:916:94:31:13:49:16

output_formatstringOptionalDefault: "jpeg"

输出文件格式：jpeg 或 png。

Options:jpegpng

safety_toleranceintegerOptionalDefault: 2

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

Options:012

prompt_upsamplingbooleanOptionalDefault: false

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

callbackobjectOptional

Terminal-state notification config. When omitted, no callback is delivered — poll the task yourself. See the callback note below.

Callbacks (Webhook)

Provide callback.url when creating a task and HiAPI POSTs to your service once the task reaches a terminal state — no polling needed. The callback payload mirrors the task detail structure; signature verification, delivery retries and idempotency are documented on the Unified Async API overview page.

urlstringRequired

Required when callback is present. A POST is sent to this URL once the task reaches a terminal state; must be a valid http(s) URL.

whenstringOptionalDefault: "final"

Only final is supported today — notified on both success and fail.

Options:final

storagestringOptionalDefault: "temp"

Artifact storage tier: temp (default, retained about 7 days) or persistent (long-term, billed by size). Insufficient balance or exceeding the storage cap silently downgrades to temp; the effective tier is shown in the task detail response.

Options:temppersistent

Request examples

# Submit an async task; returns a taskId immediately (no waiting for generation)
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 task detail

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

Response fields

taskIdstringRequired

Task ID, always prefixed with tk-hiapi-.

modelstringRequired

Resolved full model name. Tasks submitted with the route parameter return base@route (e.g. gpt-image-2/text-to-image@ext); otherwise identical to the name passed at creation.

routestringOptional

Present only when the task was submitted with an explicit route parameter; echoes the submitted value.

statusstringRequired

Task status.

Status values

queued Queued, not started yet. handling Being processed. archiving Processing finished, artifacts being prepared. success Terminal: completed, artifacts available (output returned). fail Terminal: failed (error returned). After submission, check status: success and fail are terminal, everything else is non-terminal. Poll every 1–3 seconds until terminal. On success, download artifacts from output[].url and transfer them before expireAt; pass storage: "persistent" at creation time when long-term retention is needed.

creatednumberRequired

Task creation time (Unix seconds).

completednumberRequired

Unix seconds when the task reached a terminal state; fixed to 0 while not terminal.

outputarrayOptional

Present only when status == success. Artifact list — always an array; a single task may return multiple types at once (e.g. video + first_frame).

Array [ object ]

Array items

urlstringRequired

Artifact URL, directly downloadable.

typestringRequired

Current possible values: video, image, audio, first_frame, last_frame, thumbnail; more may be added later.

expireAtnumberRequired

Unix seconds until which the artifact remains accessible; download or transfer before it expires.

errorobjectOptional

Present only when status == fail.

codestringRequired

Business error code.

messagestringRequired

Error description.

Response examples

Success

{
  "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
      }
    ]
  }
}

Processing (non-terminal)

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

Failed

{
  "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"
    }
  }
}