Flux Kontext API: Integration Guide, Pricing & Code

What the Flux Kontext API is — and what it isn’t

The Flux Kontext API is Black Forest Labs’ hosted endpoint for FLUX.1 Kontext, a model family that takes text plus one or more reference images and produces an edited or generated image. Where classic text-to-image models only accept a prompt, Kontext reads the content of your input images and applies instructions to them: change a car’s color, keep a character identical across scenes, swap a style, or rewrite text inside a picture.

It is not a plain text-to-image model, and it is not a free service. Three variants matter for integration:

• FLUX.1 Kontext [pro] — the hosted editing and generation model behind POST /v1/flux-kontext-pro. This is what most integrations call, and what provider docs mean by the flux kontext pro api.
• FLUX.1 Kontext [max] — a hosted variant with higher output quality, billed at twice the pro rate.
• FLUX.1 Kontext [dev] — a 12B-parameter open-weight release under a non-commercial license, run locally or through inference providers such as Replicate and fal.ai.

The API is asynchronous: you submit a task, get a task ID, then poll for the result (or receive a webhook). Black Forest Labs’ announcement describes the model family and its capabilities; the official API docs define the current request contract. If you are evaluating the Black Forest Labs flux API as a whole, Kontext is the editing family and FLUX.2 is the generation line — the last section of this guide covers the trade-off.

Flux Kontext API pricing: what each route actually costs

Pricing is per output image, and the unit is not the same everywhere. BFL sells credits (1 credit = $0.01) and deducts a fixed number per image; fal.ai and Replicate bill in dollars per image. The table below was checked against the live pages on August 11, 2026.

Route	Model	Price per image	Notes
BFL official	FLUX.1 Kontext [pro]	$0.04 (4 credits)	Pay-as-you-go credits, no free tier
BFL official	FLUX.1 Kontext [max]	$0.08 (8 credits)	Higher quality, double the pro rate
fal.ai	fal-ai/flux-pro/kontext	$0.04	Fixed per-image edit cost
Replicate	black-forest-labs/flux-kontext-pro	$0.04	Priced per output image

Sources: BFL pricing page, fal.ai Kontext API docs, and the Replicate flux-kontext-pro page, all accessed August 11, 2026.

The official FLUX.1 Kontext model page, captured from the live site on August 11, 2026. The capability sections (contextual understanding, character consistency, typography) are what you are paying for per image.

Together AI also serves FLUX.1 Kontext [pro] as a serverless endpoint (black-forest-labs/FLUX.1-kontext-pro), but its model page does not list a per-image rate in the page body, so there is no comparable number to put in this table. Check their pricing page before assuming parity.

Two pricing facts worth stating plainly:

1. There is no free tier for the hosted pro/max models. The Reddit question “is flux kontext api free?” gets a consistent answer across providers: no. The open-weight dev model is the only free route, and it carries a non-commercial license.
2. Per-image price is not per-edit-session cost. A multi-turn editing workflow (edit → feed result back in → edit again) pays the per-image rate on every generation. At $0.04, ten iterations cost $0.40. Budget for the loop, not the single call.

Get an API key and set up your first call

Create an account at the BFL dashboard (dashboard.bfl.ai), add credits, and copy an API key from your profile. The key goes in the x-key header on every request.

The smallest working call is a text-to-image request — no reference image needed, which makes it a good connectivity check:

curl -X POST https://api.bfl.ai/v1/flux-kontext-pro \
  -H "x-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A small furry elephant peeking out of a cat house",
    "aspect_ratio": "1:1",
    "output_format": "jpeg"
  }'

A successful submit returns JSON with an id and a polling_url, not the image itself. The response also includes cost in credits — a useful way to confirm you are being billed 4 credits per pro image before you build anything on top.

Edit an image with code: the BFL API, async and polled

The Kontext API request lifecycle: submit a task, get a task ID, poll for the result. The edited image is returned only after the async task completes.

For editing, add an input_image (a public URL or base64 data URI). The request below changes the car’s color in a reference photo — the canonical Kontext demo:

import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://api.bfl.ai"

def submit_edit(prompt: str, image_url: str, safety_tolerance: int = 2):
    resp = requests.post(
        f"{BASE}/v1/flux-kontext-pro",
        headers={"x-key": API_KEY, "Content-Type": "application/json"},
        json={
            "prompt": prompt,
            "input_image": image_url,
            "output_format": "jpeg",
            "safety_tolerance": safety_tolerance,
        },
    )
    resp.raise_for_status()
    return resp.json()["id"]

def wait_for_result(task_id: str, timeout: int = 120):
    import time
    deadline = time.time() + timeout
    while time.time() < deadline:
        r = requests.get(f"{BASE}/v1/get_result", params={"id": task_id},
                         headers={"x-key": API_KEY})
        data = r.json()
        status = data.get("status")
        if status == "Ready":
            return data["result"]["sample"]
        if status in ("Request Moderated", "Content Moderated", "Error"):
            raise RuntimeError(f"Task {status}: {data}")
        time.sleep(2)
    raise TimeoutError("Task did not finish in time")

task_id = submit_edit("Change the car color to red", "https://example.com/car.jpg")
edited = wait_for_result(task_id)
print(edited)  # URL of the edited image

Polling is the simplest reliable pattern for a first integration. Three refinements matter in production:

• Webhooks. Pass webhook_url (and optionally webhook_secret) in the submit body; BFL POSTs the result when it’s ready, and you skip polling entirely.
• Seeds for reproducible edits. A fixed seed with the same prompt, image, and model version returns the same output. For iterative workflows, decide deliberately whether to pin the seed (deterministic edits) or leave it unset (more variety between turns).
• Iterative editing. Kontext is built for multi-turn edits: take the output URL of one call and use it as the input_image of the next. The model keeps the character and style consistent across turns. That loop is the whole point of the model — plan your code around it rather than treating each call as independent.

The same submit+poll flow works for cURL and Node: submit to /v1/flux-kontext-pro, poll GET /v1/get_result?id=... with the same x-key header. That submit → poll → retrieve loop is the whole flux api kontext integration pattern.

Use multiple reference images (multiref)

Multiref in one call: a character reference and a style reference are combined with a text instruction into a single consistent output.

Kontext accepts up to four input images: input_image plus input_image_2, input_image_3, and input_image_4. The BFL API reference marks the extra slots as experimental multiref, but they are live in the request schema and are the practical way to combine a character reference with a style reference in one call.

resp = requests.post(
    f"{BASE}/v1/flux-kontext-pro",
    headers={"x-key": API_KEY, "Content-Type": "application/json"},
    json={
        "prompt": "Remake this product photo in the style of the second image",
        "input_image": "https://example.com/product.jpg",
        "input_image_2": "https://example.com/style-ref.jpg",
        "output_format": "jpeg",
    },
)

Two use patterns show up repeatedly in production:

1. Character + environment. Put the character shot in slot 1 and a scene or outfit reference in slot 2, then instruct the model to place the character into the scene. This is how teams build consistent product or avatar imagery without fine-tuning.
2. Local edits with annotation boxes. Kontext also understands bright colored boxes drawn over the input image as edit regions — box an area and the instruction applies to that region only. This pairs naturally with multiref for “change only this object, keep everything else.”

Both patterns are where Kontext earns its per-image price. If your workflow only needs single-image edits, a simpler inpainting API may be cheaper; if you need identity consistency across dozens of shots, multiref is the differentiator.

Alternative routes: fal.ai, Replicate, and Together AI

The same model is available from infrastructure providers, which matters when you already run workloads there or need their queue/subscribe tooling.

fal.ai — client-based, with a subscribe helper that handles polling:

import { fal } from "@fal-ai/client";

const result = await fal.subscribe("fal-ai/flux-pro/kontext", {
  input: {
    prompt: "Put a donut next to the flour.",
    image_url: "https://example.com/flour.jpg",
  },
  logs: true,
});
console.log(result.data);

Replicate — predictions API with a standard create-and-poll pattern:

curl -X POST https://api.replicate.com/v1/models/black-forest-labs/flux-kontext-pro/predictions \
  -H "Authorization: Bearer YOUR_REPLICATE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "prompt": "Change the car color to red",
      "image": "https://example.com/car.jpg"
    }
  }'

Together AI — OpenAI-compatible serverless endpoint, so it drops into existing SDKs:

from together import Together

client = Together(api_key="YOUR_TOGETHER_KEY")
resp = client.images.generate(
    model="black-forest-labs/FLUX.1-kontext-pro",
    prompt="Change the car color to red",
    image_url="https://example.com/car.jpg",
)
print(resp.data[0].url)

Which route should you pick? At the price level, pro is $0.04/image on BFL, fal, and Replicate alike, so price is not the deciding factor. Choose by operational fit: BFL direct for the newest model versions and webhooks; fal.ai if you already use its queue tooling; Replicate for its ecosystem and run history; Together if you want the OpenAI-compatible shape. For a broader look at how image-manipulation APIs behave in production, our image manipulation API guide compares seven workflows end to end.

Handle errors, moderation, and rate limits

The BFL API uses standard HTTP status codes. The ones you will actually hit:

Status	Meaning	What to do
400	Malformed request body	Validate prompt and image fields before retrying
402	Insufficient credits	Top up; check cost in the submit response
403	Key lacks permission	Verify the key and account state
422	Invalid parameters	Fix the body per the API reference
429	Rate limit exceeded	Back off and retry with exponential delay
500 / 503	Server or service issue	Retry later; do not resubmit blindly on 503

Moderation is part of the async result lifecycle, not a separate API. Polling get_result can return:

• Request Moderated — your prompt or input image was flagged before processing.
• Content Moderated — the generated output was flagged after processing.
• Task not found — the ID is invalid or expired.
• Error — processing failed; check the error detail.

The safety_tolerance parameter (0–6, default 2) controls moderation strictness on inputs and outputs. Leave it at the default unless you have a product reason to loosen it. Also note that BFL applies C2PA cryptographic provenance metadata to API outputs — if your product strips metadata, that is a deliberate choice, not an accident.

Should you still integrate FLUX.1 Kontext in 2026?

The honest answer: Black Forest Labs itself now recommends FLUX.2 for new projects. The Kontext documentation pages carry the note “For new projects, we recommend FLUX.2,” citing multi-reference support up to ten images, stronger text editing, and output up to 4MP. If you are starting from zero in 2026, read the FLUX.2 docs before committing to Kontext.

Kontext still makes sense in three situations:

1. You are already shipping on it. The API is stable, the price is known, and the model is not going away. Migrating to FLUX.2 is a model swap with a new request shape, not a free rename.
2. Iterative editing quality matters more than raw resolution. Kontext’s multi-turn consistency is its signature strength, and it remains competitive on that specific job.
3. You want the $0.04 entry point. FLUX.2 pro starts at $0.03 for text-to-image but image editing starts at $0.045; Kontext pro editing at $0.04 is still the cheapest hosted editing tier in the family.

What you should not do is pick Kontext reflexively because you found this guide. The official FLUX model comparison in the BFL API docs now leads with FLUX.2 for generation and editing; for comparison, our GPT Image 1.5 API guide shows what a competing editing model looks like at the same price point. The text-to-image API guide positions Kontext’s dual generation-editing capability against six dedicated generators.

Get started

A disclosure first, because it changes what you should expect from this page: Modellix does not offer FLUX.1 Kontext. We are an API aggregator, and our model catalog currently has no Black Forest Labs provider. This guide exists because the model is worth integrating well, and the decision should not depend on who wrote the tutorial.

Where Modellix does fit: if your product needs many image and video models behind one API key — 210+ models, pay-as-you-go, no monthly fee — the aggregator route is worth evaluating for everything Kontext is not. Start with the Modellix models page, where you can compare the editing and generation models we do carry, or use the Modellix CLI to try routes from your terminal.

The short version of this guide: Kontext pro is $0.04 per image on every major route (the flux kontext max api doubles that to $0.08 per image), the API is a submit-and-poll flow with multiref and iterative editing as the real capabilities, and BFL’s own recommendation has moved to FLUX.2 for new builds. Integrate accordingly.