FLUX.2 API: image editing

FLUX.2 edits images through the same JSON endpoint that generates them: send one image to edit it, or combine up to eight reference images. Requests are billed per call, and each result URL expires 10 minutes after generation.

Item	Details
Endpoint	`POST https://api.laozhang.ai/v1/images/generations` with a JSON body
Image to edit	Send a `prompt` and an `input_image`
More references	`input_image_2` through `input_image_8`, up to eight images in total
Reference format	A public image URL or a `data:` URL
Price	`flux-2-pro` $0.03 per call, `flux-2-flex` $0.06, `flux-2-max` $0.07; public pricing as of September 24, 2026 (see the model and pricing catalog)
Result	`data[0].url`, which expires 10 minutes after the image is generated, so download it right away

Start with flux-2-pro. Black Forest Labs recommends flux-2-max for the highest-precision edits and flux-2-flex for fine-grained control, such as text rendering and small details. All three models take the same request.

Before you start

Create an API key

FLUX.2 models are billed per call. In Token management, create a key (or edit an existing one) and set Billing mode (计费模式) to Usage first (按量优先, recommended) or Per-call (按次计费). A Usage first key can call both per-call and usage-based models; a Per-call key calls only per-call models.Keep the key in a server-side environment variable.

Create-token dialog in the LaoZhang API console with Billing mode set to Per-call (按次计费)

Set up your environment

Export the key and install requests, which the Python example uses:

export LAOZHANG_API_KEY="sk-..."  # replace with your LaoZhang API key
python3 -m pip install requests

Save the download script

Save this script as save_images.py. The cURL examples run it on the response file to download every image. FLUX returns only URLs; the script also decodes b64_json, which some other image models return:

save_images.py

import base64
import json
import sys
import urllib.request
from pathlib import Path

response_file, stem = sys.argv[1], sys.argv[2]
response = json.loads(Path(response_file).read_text())
if not response.get("data"):
    sys.exit(f"No image in {response_file}: {response}")

for number, item in enumerate(response["data"], start=1):
    if item.get("b64_json"):
        # Drop an optional data:image/...;base64, prefix and restore missing padding.
        value = item["b64_json"].split(",", 1)[-1]
        image = base64.b64decode(value + "=" * (-len(value) % 4))
    else:
        with urllib.request.urlopen(item["url"], timeout=120) as download:
            image = download.read()
    if image.startswith(b"\x89PNG"):
        extension = "png"
    elif image[:4] == b"RIFF" and image[8:12] == b"WEBP":
        extension = "webp"
    else:
        extension = "jpg"
    path = Path(f"{stem}-{number}.{extension}")
    path.write_bytes(image)
    print(f"Saved {path}")

Edit an image

Add input_image to a generation request to turn it into an edit. Replace the URL with a publicly accessible image:

curl --fail-with-body --max-time 300 "https://api.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-pro",
    "prompt": "Keep the same main subject. Change the background to a clean pale blue studio backdrop and preserve the original lighting.",
    "input_image": "https://example.com/source.png",
    "width": 1792,
    "height": 1024,
    "output_format": "png"
  }' \
  -o flux-edit.json

python3 save_images.py flux-edit.json flux-edit

The script prints Saved flux-edit-1.png. The reference URL is fetched during the request, so it must load without a login, cookies, or bot checks.

To combine references, send JSON to /v1/images/generations and put each reference in an input_image field. The multipart endpoint /v1/images/edits takes a single file in a field named image, so it can’t combine references.

Edit a local file

To edit a file on your machine, send it as a data URL whose MIME type matches the file, such as data:image/png;base64,... for a PNG. Passing the body through a heredoc keeps a large image out of the command line:

IMG=$(base64 < product.png | tr -d '\n')

curl --fail-with-body --max-time 300 "https://api.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- \
  -o flux-local-edit.json <<EOF
{
  "model": "flux-2-pro",
  "prompt": "Place the product on a marble counter in soft morning light. Keep the product and its label unchanged.",
  "input_image": "data:image/png;base64,$IMG",
  "size": "1024x1024",
  "output_format": "png"
}
EOF

python3 save_images.py flux-local-edit.json flux-product

Combine reference images

Add input_image_2 through input_image_8 for more references, and refer to them in the prompt as image 1, image 2, and so on, in field order. This example reads three PNG files from the current directory:

IMG1=$(base64 < robot.png | tr -d '\n')
IMG2=$(base64 < greenhouse.png | tr -d '\n')
IMG3=$(base64 < skateboard.png | tr -d '\n')

curl --fail-with-body --max-time 300 "https://api.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- \
  -o flux-multi-edit.json <<EOF
{
  "model": "flux-2-pro",
  "prompt": "Combine the three reference images into one coherent new image. Use image 1 as the red robot, image 2 as the turquoise glass greenhouse background, and image 3 as the yellow skateboard. Include details from all three references. Do not create a collage or split-screen layout.",
  "input_image": "data:image/png;base64,$IMG1",
  "input_image_2": "data:image/png;base64,$IMG2",
  "input_image_3": "data:image/png;base64,$IMG3",
  "width": 1792,
  "height": 1024,
  "output_format": "png"
}
EOF

python3 save_images.py flux-multi-edit.json flux-multi-edit

Edit with Python

This script accepts one to eight references, turns local files into data URLs, passes public URLs through unchanged, and saves the result as soon as the request returns:

import base64
import mimetypes
import os
from pathlib import Path

import requests

API_URL = "https://api.laozhang.ai/v1/images/generations"
HEADERS = {"Authorization": f"Bearer {os.environ['LAOZHANG_API_KEY']}"}


def to_image_input(source):
    """Return a URL unchanged, or convert a local file to a data URL."""
    if source.startswith(("https://", "http://", "data:")):
        return source
    path = Path(source)
    mime_type = mimetypes.guess_type(path.name)[0] or "image/png"
    encoded = base64.b64encode(path.read_bytes()).decode("ascii")
    return f"data:{mime_type};base64,{encoded}"


def flux_edit(prompt, sources, width=1024, height=1024, model="flux-2-pro"):
    if not 1 <= len(sources) <= 8:
        raise ValueError("FLUX.2 accepts 1 to 8 reference images")
    payload = {
        "model": model,
        "prompt": prompt,
        "width": width,
        "height": height,
        "output_format": "png",
    }
    for number, source in enumerate(sources, start=1):
        field = "input_image" if number == 1 else f"input_image_{number}"
        payload[field] = to_image_input(source)
    response = requests.post(API_URL, headers=HEADERS, json=payload, timeout=240)
    response.raise_for_status()
    return response.json()


def save_first_image(result, stem):
    # FLUX returns a URL that expires after 10 minutes, so download it immediately.
    download = requests.get(result["data"][0]["url"], timeout=120)
    download.raise_for_status()
    image = download.content
    extension = "png" if image.startswith(b"\x89PNG") else "jpg"
    path = Path(f"{stem}.{extension}")
    path.write_bytes(image)
    return path


result = flux_edit(
    "Use image 1 as the red robot, image 2 as the greenhouse background, and image 3 "
    "as the yellow skateboard. Create one coherent new scene, not a collage.",
    ["robot.png", "greenhouse.png", "skateboard.png"],
    width=1792,
    height=1024,
)
print("Saved", save_first_image(result, "flux-python-edit"))

Parameters

Parameter	Type	Required	Description
`model`	string	Yes	`flux-2-pro`, `flux-2-flex`, or `flux-2-max`
`prompt`	string	Yes	The edit instruction; with several references, name them as image 1, image 2, and so on
`input_image`	string	Yes, for an edit	First reference, as a public URL or data URL
`input_image_2` … `input_image_8`	string	No	More references, numbered in order
`size`	string	No	Output size such as `1792x1024`
`width`, `height`	integer	No	Output size in pixels: multiples of 16, at least 64, up to about 4 MP in total; use instead of `size`
`output_format`	string	No	`jpeg` (default) or `png`
`seed`	integer	No	Fixed seed for repeatable results
`n`	integer	No	Number of images; only `1` is supported

Set the output size with either size or width and height, not both. The FLUX.2 generation guide lists the common size values.

Handle the response

The response returns one image as data[0].url. FLUX doesn’t return b64_json, so don’t send response_format. The link expires 10 minutes after the image is generated; download it as soon as the request returns, especially in batch jobs. The image is JPEG unless you set output_format to png.

Prompt tips

Refer to each source as image 1, image 2, image 3, and so on, in field order.
Name the elements that must be preserved from each reference, such as a logo, a face, or a product color.
Say that the output should be one coherent image.
Say what to avoid, such as a collage, split screen, borders, or labels.

Use image 1 as the character, image 2 as the background, and image 3 as the product.
Create one coherent commercial poster.
Preserve the character's clothing, the background lighting, and the product logo.
Do not create a collage or split-screen layout.

Errors and billing

HTTP 400: check the field names, the number of references, and the output size.
- Field names: input_image, then input_image_2 and up.
- Number of references: at most 8.
- Output size: multiples of 16, at least 64 pixels, up to about 4 MP, set with size or with width and height.
A reference can’t be loaded: the URL must be public. Otherwise send the file as a data URL.
The result link no longer works: it expired 10 minutes after generation. Run the request again and download the result immediately.
HTTP 401: check the key and the Authorization: Bearer header.
HTTP 429, 5xx, or a timeout: retry with backoff. After a timeout, check call logs before resending, so you don’t pay twice.

Each request is billed at the model’s per-call price. Call logs show the model and the charge for every request.

Legacy FLUX Kontext models

flux-kontext-pro and flux-kontext-max remain in the catalog for existing integrations. They use an aspect_ratio field instead of size; the legacy section of the generation guide covers them. Build new edits on FLUX.2.

FAQ

Can I edit only part of an image?

Yes, by describing it. The request has no mask field, so name the element to change in the prompt and say what must stay the same.

Does an edit cost more than a generation?

No. FLUX.2 is billed per call, so an edit costs the same per-call price as a generation, whether you send one reference or eight and whatever the output size. Check call logs for the actual charge.

Do editing and generation use the same model?

Yes. flux-2-pro, flux-2-flex, and flux-2-max handle both. A request with input_image is an edit; without it, the request generates a new image, as shown in FLUX.2 image generation.

Can I edit with the OpenAI SDK’s `images.edit()`?

Only for single-image edits. images.edit() uploads multipart form data to /v1/images/edits, which takes one image and can’t combine references. Use client.images.generate() instead, and put input_image (plus the numbered fields for more references) in extra_body as public URLs or data URLs. The Python helper on this page does the same with requests.

FLUX.2 image generation — text-to-image requests, output sizes, and legacy Kontext models
Choose an image API — compare FLUX.2 with other image models
Images API reference — shared request and response format
Model and pricing catalog — current FLUX prices and groups
Call logs — check the model and charge for each request
Black Forest Labs: FLUX.2 image editing — multi-reference editing, reference limits, and result URL lifetime
Black Forest Labs: FLUX.2 overview — what each FLUX.2 variant is built for

Get started

Image Generation & Editing APIs

Video Generation APIs

Text APIs

Multimodal & Audio APIs

FLUX.2 API: image editing

Before you start

Edit an image

Edit a local file

Combine reference images

Edit with Python

Parameters

Handle the response

Prompt tips

Errors and billing

Legacy FLUX Kontext models

FAQ

Can I edit only part of an image?

Does an edit cost more than a generation?

Do editing and generation use the same model?

Can I edit with the OpenAI SDK’s `images.edit()`?

​Before you start

​Edit an image

​Edit a local file

​Combine reference images

​Edit with Python

​Parameters

​Handle the response

​Prompt tips

​Errors and billing

​Legacy FLUX Kontext models

​FAQ

​Can I edit only part of an image?

​Does an edit cost more than a generation?

​Do editing and generation use the same model?

​Can I edit with the OpenAI SDK’s images.edit()?

​Related documentation and sources

Before you start

Edit an image

Edit a local file

Combine reference images

Edit with Python

Parameters

Handle the response

Prompt tips

Errors and billing

Legacy FLUX Kontext models

FAQ

Can I edit only part of an image?

Does an edit cost more than a generation?

Do editing and generation use the same model?

Can I edit with the OpenAI SDK’s `images.edit()`?

Related documentation and sources