Skip to main content
ModelRunner
black-forest-labs avatar

FLUX.1 Kontext [dev] API

black-forest-labs/flux-kontext/dev

Edit an existing image from a text instruction — change objects, style, background, or text — while keeping the rest of the photo consistent.

edit
0.025 per megapixel of image
OpenAPI

Model Input

Input

The edit instruction. Describe the change to apply to the source image (e.g. 'change the wooden floor to white marble') and name anything that should stay the same.

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

Min: 10 - Max: 50

Number of denoising steps. More steps can improve detail at the cost of speed.

Min: 1 - Max: 20

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

Output resolution. 'match_input' keeps the source image's resolution (recommended for alignment); 'auto' lets the model pick an optimal resolution matching the input aspect; or force an aspect ratio such as '16:9', '4:3', or '9:16'.

The format of the generated image.

Inference acceleration level. 'none' is highest quality; 'regular' and 'high' are progressively faster with a small quality trade-off. Does not change the price.

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

Safety checker can only be disabled on API call

Min: 1 - Max: 4

The number of images to generate. Each generated image is billed.

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

Model Output

Output

Loading
Generated in 10.689 seconds
Logs (1 lines)

Model Example Requests

Examples

Example output 1Example output 2Example output 3

FLUX.1 Kontext [dev] API

FLUX.1 Kontext [dev] 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.025 per megapixel.

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

cURL

# Submit a request to the queue. Input fields go at the top level of the
# body. The optional reserved "metadata" object holds your own flat string
# tags — stored on the request, never sent to the model; filter later with
# GET https://queue.modelrunner.run/requests?metadata=<url-encoded JSON>.
curl -X POST https://queue.modelrunner.run/black-forest-labs/flux-kontext/dev \
  -H "Authorization: Key $MRUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Place the dog on a sunny tropical beach with turquoise ocean waves and palm trees behind it, warm golden-hour light.",
    "image_url": "https://media.modelrunner.ai/OnB0a9tFqLGcUP53RQ46n.png",
    "acceleration": "none",
    "output_format": "jpeg",
    "guidance_scale": 2.5,
    "resolution_mode": "match_input",
    "num_inference_steps": 28,
    "enable_safety_checker": true,
    "metadata": {
      "project": "my-project"
    }
  }'
# → { "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/dev/requests/$REQUEST_ID/status" \
  -H "Authorization: Key $MRUN_API_KEY"
curl "https://queue.modelrunner.run/black-forest-labs/flux-kontext/dev/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/dev", {
  input: {
    "prompt": "Place the dog on a sunny tropical beach with turquoise ocean waves and palm trees behind it, warm golden-hour light.",
    "image_url": "https://media.modelrunner.ai/OnB0a9tFqLGcUP53RQ46n.png",
    "acceleration": "none",
    "output_format": "jpeg",
    "guidance_scale": 2.5,
    "resolution_mode": "match_input",
    "num_inference_steps": 28,
    "enable_safety_checker": true
  },
});
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/dev",
    headers=headers,
    json={
      "prompt": "Place the dog on a sunny tropical beach with turquoise ocean waves and palm trees behind it, warm golden-hour light.",
      "image_url": "https://media.modelrunner.ai/OnB0a9tFqLGcUP53RQ46n.png",
      "acceleration": "none",
      "output_format": "jpeg",
      "guidance_scale": 2.5,
      "resolution_mode": "match_input",
      "num_inference_steps": 28,
      "enable_safety_checker": true
    },
).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. 'change the wooden floor to white marble') 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.
num_inference_stepsintegernoNumber of denoising steps. More steps can improve detail at the cost of speed. Default: 28.
guidance_scalenumbernoHow strongly the result follows the edit instruction. Raise for stronger adherence; lower if the edit looks over-applied. Default: 2.5.
resolution_modeenumnoOutput resolution. 'match_input' keeps the source image's resolution (recommended for alignment); 'auto' lets the model pick an optimal resolution matching the input aspect; or force an aspect ratio such as '16:9', '4:3', or '9:16'. Default: "match_input".
output_formatenumnoThe format of the generated image. Default: "jpeg".
accelerationenumnoInference acceleration level. 'none' is highest quality; 'regular' and 'high' are progressively faster with a small quality trade-off. Does not change the price. Default: "none".
seedintegernoRandom seed. The same seed, prompt, and image produce the same result.
enable_safety_checkerbooleannoIf set to true, the safety checker will be enabled. Default: true.
num_imagesintegernoThe number of images to generate. Each generated image is billed. Default: 1.

Machine-readable: OpenAPI schema · llms.txt

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

Point Claude Code, Claude Desktop, Cursor, or any MCP client at the ModelRunner MCP server and FLUX.1 Kontext [dev] 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/dev.

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/dev on ModelRunner to generate image”. MCP setup guide.

Model Details

Model Details

FLUX.1 Kontext [dev] 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. Its strength is character and scene consistency across edits: faces, products, composition, and untouched regions stay stable instead of being regenerated from scratch, so iterative edits compound cleanly. It is the open-weights image editor from Black Forest Labs, tuned for precise local and global instruction-based editing.

## Best for - Instruction edits to a photo — "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 - Replacing or restyling backgrounds without regenerating the foreground - Editing or correcting text and signage inside an existing image - Iterative, multi-step edits where consistency must hold across rounds

## Choose another model when - 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 `resolution_mode` at `match_input` (the default) to preserve the source image's dimensions and keep the edit aligned with the original for before/after comparison - 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 - `num_inference_steps` (10–50, default 28) trades speed for refinement; more steps can sharpen detail. - `guidance_scale` (1–20, default 2.5) controls how strongly the result follows the instruction; raise it for stronger edits. - `resolution_mode` (default `match_input`) sets the output resolution: `match_input` keeps the source dimensions, `auto` lets the model pick an optimal resolution for the input aspect, or force an aspect ratio such as `16:9`, `4:3`, or `9:16`. - `acceleration` (`none`, `regular`, `high`, default `none`) speeds up inference at a small quality trade-off; it does not change the price. - `output_format` selects `jpeg` (default) or `png`.

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

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