FLUX.1 Kontext Max API
https://api.hiapi.ai /v1/tasks Image, video, and audio models are called through theUnified Async API POST /v1/tasks endpoint; only the input fields differ (see input parameters below).
Model summary
| Model name | flux-1-kontext-max |
|---|---|
| Type | Text-to-image / image editing |
| Endpoint | POST /v1/tasks |
| Pricing | See HiAPI Pricing |
FLUX.1 Kontext Max covers text-to-image generation and single-image editing: write a prompt to create an image, or upload one photo and describe the change while keeping subjects, text and style consistent.
Production guidance
- For production, pass callback.url at the top level of the request body so HiAPI can notify your service when the task reaches a terminal state.
- GET /v1/tasks/:id is better for local debugging, low-volume jobs, or fallback reconciliation if a callback is missed.
- Result URLs expire — copy the output to your own storage once the task succeeds.
Best suited for
Upload one source image and change materials, colors, elements or text while everything else stays as close as possible.
input_imagepromptOmit the source image, describe the scene and choose one of six frames.
promptaspect_ratioReplace headlines, copy or primary colors while keeping layout, type positions and structure.
promptoutput_formatRequest parameters
model string required Fixed value flux-1-kontext-max.
input object required Business parameters.
prompt string required Describe the image to create; when a source image is supplied, describe what to change and what to keep. Chinese or English, up to 4,000 characters.
input_image string optional Optional source image URL. One image only; the prompt edits this image. Omit it to generate a new image from the prompt.
aspect_ratio enum optional Output aspect ratio. When editing, leave it empty to keep the source ratio (pixels are rounded to multiples of 32); setting it crops or pads to that ratio. For generation, empty lets the model choose the framing.
output_format enum optional Output image format.
prompt_upsampling boolean optional Automatically expands the prompt for more detail and creativity; takes slightly longer. Turn it off to follow the exact wording.
safety_tolerance enum optional Moderation strictness: 0 is the strictest, 2 the most permissive. Both generation and editing expose 0–2.
callback object optional Optional callback configuration. When set, HiAPI notifies your service when the task reaches a terminal state.
url string required Required when callback is set; HTTPS URL that receives terminal task notifications.
when enum optional Callback trigger timing. Use final.
Example requests
No input_image: the scene comes from the prompt with a 16:9 frame and jpeg output.
{
"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
}
}Pass one source image and describe only the chair swap and the new floor lamp. No aspect_ratio, so the source ratio is kept.
{
"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"
}
}Raise safety_tolerance when valid content is blocked, or enable prompt_upsampling for more detail.
{
"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
}
}Getting the result
- The response returns a taskId immediately without waiting for generation to finish.
- In production, prefer waiting for callback.url to receive the terminal notification. For local debugging, poll GET /v1/tasks/:id.
- When status=success, read the image URL from output and download it.
- When status=fail, fix the request based on the returned error instead of retrying the same invalid payload.
FAQ
How do I switch between generating and editing?
Omit input_image to generate; add one input_image to edit. Both modes use the same model ID and the same price.
What can I change when editing?
Style and materials, added or removed elements, colors and lighting, and text inside the image. State what should change and what must stay; unspecified areas are preserved as closely as possible.
Does editing change the aspect ratio?
Without aspect_ratio the source ratio is kept and pixels are rounded to multiples of 32 (for example 1280×720 becomes 1328×752). Setting it crops or pads to that ratio.
Can I upload more than one reference image?
Only one source image is supported. Use a multi-reference model for composition, try-on or combining materials.
Can I write the prompt in Chinese?
Yes. Chinese and other non-English prompts are translated to English before generation; English prompts are used as written.
What output size and format do I get?
About one megapixel per image, with edits rounded to multiples of 32; exact pixels come from the task result. Choose jpeg or png.
How should I set safety_tolerance?
0 is strictest and 2 most permissive, default 2. Raise it when valid content is blocked and lower it for stricter moderation.
How is it billed?
Per output image, one image per request, with generation and editing at the same rate. See the live pricing page for the current price.