Skip to main content
ModelRunner
black-forest-labs avatar

FLUX.1 Kontext [max] API

black-forest-labs/flux-kontext/max

Edit an existing image from a text instruction — change objects, style, background, or text — at the family's highest fidelity, with top-tier prompt adherence, the strongest typography and consistency, and commercial-usage rights.

edit
0.08
OpenAPI

Model Input

Input

The edit instruction. Describe the change to apply to the source image (e.g. 'put a donut next to the flour') and name anything that should stay the same.

The source image to edit. Unmentioned regions are kept consistent while the described change is applied.

Additional Settings

Customize your input with more control.

Min: 1 - Max: 20

How strongly the result follows the edit instruction. Raise for stronger adherence; lower if the edit looks over-applied.

Min: 1 - Max: 4

The number of edited image variations to generate. Each generated image is billed separately.

Force the output aspect ratio. Leave unset to match the source image's aspect ratio.

Content-moderation strictness from '1' (strictest) to '6' (most permissive).

The format of the generated image.

Whether to automatically enhance the prompt for potentially better results.

Random seed. The same seed, prompt, and image produce the same result.

You need to be logged in to run this model and view results.
Log in

Model Output

Output

Loading
Generated in 11.506 seconds
Logs (1 lines)

Model Example Requests

Examples

Example output 1Example output 2Example output 3

FLUX.1 Kontext [max] API

FLUX.1 Kontext [max] is a image-to-image AI model by black-forest-labs. On ModelRunner it runs through a REST API or via MCP from any AI assistant, at $0.08 per image.

POST https://queue.modelrunner.run/black-forest-labs/flux-kontext/max

cURL

# Submit a request to the queue
curl -X POST https://queue.modelrunner.run/black-forest-labs/flux-kontext/max \
  -H "Authorization: Key $MRUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "prompt": "Change the woman\u0027s t-shirt to a deep emerald-green blazer and add small gold hoop earrings, keeping her face, hairsty…",
      "image_url": "https://media.modelrunner.ai/PTQ8gW2giuiaAsMbx5hrB.jpeg",
      "num_images": 1,
      "output_format": "jpeg",
      "enhance_prompt": false,
      "guidance_scale": 3.5,
      "safety_tolerance": "2"
    }
  }'
# → { "request_id": "...", "status_url": "...", "response_url": "..." }

# Poll status_url until "COMPLETED", then fetch the result
curl "https://queue.modelrunner.run/black-forest-labs/flux-kontext/max/requests/$REQUEST_ID/status" \
  -H "Authorization: Key $MRUN_API_KEY"
curl "https://queue.modelrunner.run/black-forest-labs/flux-kontext/max/requests/$REQUEST_ID" \
  -H "Authorization: Key $MRUN_API_KEY"

JavaScript

import { modelrunner } from "@modelrunner/client";

const result = await modelrunner.subscribe("black-forest-labs/flux-kontext/max", {
  input: {
    "prompt": "Change the woman's t-shirt to a deep emerald-green blazer and add small gold hoop earrings, keeping her face, hairsty…",
    "image_url": "https://media.modelrunner.ai/PTQ8gW2giuiaAsMbx5hrB.jpeg",
    "num_images": 1,
    "output_format": "jpeg",
    "enhance_prompt": false,
    "guidance_scale": 3.5,
    "safety_tolerance": "2"
  },
});
console.log(result);

Python

import os
import requests

headers = {"Authorization": f"Key {os.environ['MRUN_API_KEY']}"}

submitted = requests.post(
    "https://queue.modelrunner.run/black-forest-labs/flux-kontext/max",
    headers=headers,
    json={"input": {
      "prompt": "Change the woman's t-shirt to a deep emerald-green blazer and add small gold hoop earrings, keeping her face, hairsty…",
      "image_url": "https://media.modelrunner.ai/PTQ8gW2giuiaAsMbx5hrB.jpeg",
      "num_images": 1,
      "output_format": "jpeg",
      "enhance_prompt": false,
      "guidance_scale": 3.5,
      "safety_tolerance": "2"
    }},
).json()

# Poll submitted["status_url"] until "COMPLETED", then:
result = requests.get(submitted["response_url"], headers=headers).json()

Input parameters

NameTypeRequiredDescription
promptstringyesThe edit instruction. Describe the change to apply to the source image (e.g. 'put a donut next to the flour') and name anything that should stay the same.
image_urlstring (uri)yesThe source image to edit. Unmentioned regions are kept consistent while the described change is applied.
guidance_scalenumbernoHow strongly the result follows the edit instruction. Raise for stronger adherence; lower if the edit looks over-applied. Default: 3.5.
num_imagesintegernoThe number of edited image variations to generate. Each generated image is billed separately. Default: 1.
aspect_ratioenumnoForce the output aspect ratio. Leave unset to match the source image's aspect ratio.
safety_toleranceenumnoContent-moderation strictness from '1' (strictest) to '6' (most permissive). Default: "2".
output_formatenumnoThe format of the generated image. Default: "jpeg".
enhance_promptbooleannoWhether to automatically enhance the prompt for potentially better results. Default: false.
seedintegernoRandom seed. The same seed, prompt, and image produce the same result.

Machine-readable: OpenAPI schema · llms.txt

Use FLUX.1 Kontext [max] from Claude & Cursor (MCP)

Point Claude Code, Claude Desktop, Cursor, or any MCP client at the ModelRunner MCP server and FLUX.1 Kontext [max] becomes a tool your assistant can call directly — it authorizes via OAuth (no API key in config) and runs this model with the run_model tool using the endpoint black-forest-labs/flux-kontext/max.

MCP client config (Claude Desktop, Cursor)

{
  "mcpServers": {
    "modelrunner": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.modelrunner.run/mcp"]
    }
  }
}

Claude Code

claude mcp add --transport http modelrunner https://mcp.modelrunner.run/mcp

Then ask your assistant, for example: “Run black-forest-labs/flux-kontext/max on ModelRunner to generate image”. MCP setup guide.

Model Details

Model Details

FLUX.1 Kontext [max] edits an image you provide by following a plain-language instruction. You pass a source photo and a prompt describing the change — swap an object, restyle the scene, replace the background, alter text, or adjust color — and it re-renders the image with that edit applied while keeping everything you didn't mention consistent. It is the top tier of the Black Forest Labs Kontext editing family: the highest-fidelity, maximum-performance closed-weights model, with the strongest prompt adherence, the cleanest typography, and the best character and scene consistency in the family — tuned for complex edits and premium commercial work, with commercial-usage rights included. Untouched regions — faces, products, composition — stay stable instead of being regenerated, so demanding and iterative edits compound cleanly where lower tiers would drift.

## Best for - High-fidelity, premium commercial and marketing edits where prompt adherence and clean typography must be exact (edit or add legible text and signage) - Complex instruction edits a lower tier struggles with — "change the wooden floor to white marble", "make it nighttime", "remove the person on the left" - Restyling or relighting a scene while preserving the subject's identity and pose with maximum consistency - Replacing or restyling backgrounds without regenerating the foreground - Demanding, multi-step edits where consistency and detail must hold across rounds

## Choose another model when - You want the same editing at lower cost — use FLUX.1 Kontext [pro], the standard-quality tier at half the price - You want open weights and the lowest cost, and can trade some fidelity — use FLUX.1 Kontext [dev] - You have no source photo and want to generate an image from a prompt alone — use a text-to-image model - You want the edited result animated or in motion — use an image-to-video model - You need a precisely masked inpaint of one region only — use a dedicated inpainting model

## Tips - Describe the change precisely and name what should stay the same — Kontext keeps unmentioned regions consistent, so specific instructions edit less of the image - Leave `aspect_ratio` unset to match the source image's aspect (recommended for aligned before/after comparison); set it only when you deliberately want to reframe the output - Raise `guidance_scale` toward the higher end of its range for stronger adherence to the instruction; lower it if the edit looks over-applied

## Advanced Configuration - `guidance_scale` (1–20, default 3.5) controls how strongly the result follows the instruction; raise it for stronger edits, lower it if the edit looks over-applied. - `aspect_ratio` (unset by default) forces the output aspect ratio — one of `21:9`, `16:9`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `9:16`, `9:21`. Leave it unset to match the input image's aspect. - `safety_tolerance` (`1`–`6`, default `2`) sets content-moderation strictness: `1` is the strictest, `6` the most permissive. - `num_images` (1–4, default 1) sets how many edited variations to generate; each generated image is billed separately. - `output_format` selects `jpeg` (default) or `png`. - `enhance_prompt` (default false) automatically expands your instruction for potentially better results.

To run via the ModelRunner JavaScript client: ```js import { modelrunner } from "@modelrunner/client";

const result = await modelrunner.subscribe("black-forest-labs/flux-kontext/max", { input: { prompt: "Change the wooden floor to white marble.", image_url: "https://media.modelrunner.ai/OnB0a9tFqLGcUP53RQ46n.png", guidance_scale: 3.5, output_format: "jpeg", }, }); ```