> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Flux Image Editing

> Edit images with Flux 2 using input_image fields for single-image editing, multi-image fusion, and width/height sizing

## Model Overview

Flux image editing and text-to-image generation share the same `/v1/images/generations` endpoint. Without `input_image`, the request is text-to-image. With `input_image`, it becomes image editing. With `input_image_2` through `input_image_8`, it becomes multi-image fusion editing.

<Note>
  **Key structure**

  Flux 2 image editing uses `application/json`. Reference images are string fields: `input_image`, `input_image_2`, `input_image_3` ... `input_image_8`. Values can be public image URLs or `data:image/png;base64,...` data URLs.
</Note>

## Models and Pricing

| Model            | Model ID           | Billing Type        | Current Price | Notes                                                        |
| ---------------- | ------------------ | ------------------- | ------------- | ------------------------------------------------------------ |
| Flux 2 Pro       | `flux-2-pro`       | Pay-per-call - Chat | \$0.0300/call | Recommended default for single-image and multi-image editing |
| Flux 2 Flex      | `flux-2-flex`      | Pay-per-call - Chat | \$0.0600/call | More controllable workflows                                  |
| Flux 2 Max       | `flux-2-max`       | Pay-per-call - Chat | \$0.0700/call | Highest-quality editing                                      |
| Flux Kontext Pro | `flux-kontext-pro` | Pay-per-call - Chat | \$0.0350/call | Legacy Kontext-compatible model                              |
| Flux Kontext Max | `flux-kontext-max` | Pay-per-call - Chat | \$0.0700/call | Legacy high-quality Kontext model                            |

<Tip>
  Actual model availability and pricing are shown in the console.
</Tip>

## Quick Start

### Single-Image Edit cURL

```bash theme={null}
curl -X POST "https://api2.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_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"
  }'
```

### Multi-Image Edit cURL

```bash theme={null}
curl -X POST "https://api2.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-pro",
    "prompt": "Use image 1 as the red robot, image 2 as the greenhouse background, and image 3 as the skateboard. Create one coherent scene: the robot rides the yellow skateboard in front of the turquoise greenhouse. Preserve the white scarf, orange door, purple wheels, and black star sticker.",
    "input_image": "https://example.com/source_1_red_robot.png",
    "input_image_2": "https://example.com/source_2_glass_greenhouse.png",
    "input_image_3": "https://example.com/source_3_yellow_skateboard.png",
    "width": 1792,
    "height": 1024,
    "output_format": "png"
  }'
```

### Local Multi-Image Edit cURL

Do not upload local files with `-F "image=@..."`. Convert local images to data URLs first, then place them in `input_image`, `input_image_2`, and `input_image_3`.

```bash theme={null}
cd ~/Downloads
export LAOZHANG_API_KEY="YOUR_API_KEY"

IMG1=$(base64 < source_1_red_robot.png | tr -d '\n')
IMG2=$(base64 < source_2_glass_greenhouse.png | tr -d '\n')
IMG3=$(base64 < source_3_yellow_skateboard.png | tr -d '\n')

curl -X POST "https://api2.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- \
  -o flux_local_multi_response.json <<EOF
{
  "model": "flux-2-pro",
  "prompt": "Combine the three provided 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. The final image must clearly include details from all three references, not a collage or split-screen.",
  "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
```

The returned image URL expires quickly, so download it immediately:

```bash theme={null}
python3 - <<'PY'
import json
import urllib.request

with open("flux_local_multi_response.json") as f:
    url = json.load(f)["data"][0]["url"]

urllib.request.urlretrieve(url, "flux_local_multi_edit.png")
print("saved: flux_local_multi_edit.png")
PY
```

<Warning>
  Do not use `/v1/images/edits` or multipart `-F "image=@..."` for Flux 2 multi-image editing. Flux 2 multi-image editing uses `/v1/images/generations` with JSON `input_image` fields.
</Warning>

## Python Examples

### URL Inputs

```python theme={null}
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api2.laozhang.ai/v1"

def flux_edit(prompt, image_urls, width=1024, height=1024, model="flux-2-pro"):
    if not image_urls:
        raise ValueError("image_urls must contain at least one image")
    if len(image_urls) > 8:
        raise ValueError("Flux 2 supports up to 8 reference images")

    payload = {
        "model": model,
        "prompt": prompt,
        "input_image": image_urls[0],
        "width": width,
        "height": height,
        "output_format": "png",
    }
    for index, image_url in enumerate(image_urls[1:], start=2):
        payload[f"input_image_{index}"] = image_url

    response = requests.post(
        f"{BASE_URL}/images/generations",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=240,
    )
    response.raise_for_status()
    return response.json()["data"][0]["url"]

result_url = flux_edit(
    prompt="Use image 1 as the subject, image 2 as the background, and image 3 as the prop. Fuse them into one coherent scene.",
    image_urls=[
        "https://example.com/image1.png",
        "https://example.com/image2.png",
        "https://example.com/image3.png",
    ],
    width=1792,
    height=1024,
)
print(result_url)
```

### Local File Inputs

Convert local images to data URLs before placing them in `input_image` fields.

```python theme={null}
import base64
import mimetypes
from pathlib import Path

def file_to_data_url(path):
    path = Path(path)
    mime_type = mimetypes.guess_type(path.name)[0] or "image/png"
    encoded = base64.b64encode(path.read_bytes()).decode("utf-8")
    return f"data:{mime_type};base64,{encoded}"

result_url = flux_edit(
    prompt="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.",
    image_urls=[
        file_to_data_url("source_1_red_robot.png"),
        file_to_data_url("source_2_glass_greenhouse.png"),
        file_to_data_url("source_3_yellow_skateboard.png"),
    ],
    width=1792,
    height=1024,
)
print(result_url)
```

## Parameters

| Parameter                          | Type    | Required | Description                                                                                               |
| ---------------------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `model`                            | string  | Yes      | Recommended: `flux-2-pro`; also supports `flux-2-max` / `flux-2-flex`                                     |
| `prompt`                           | string  | Yes      | Editing or fusion instruction. In multi-image requests, refer to image 1, image 2, and image 3 explicitly |
| `input_image`                      | string  | Yes      | First reference image, public URL or data URL                                                             |
| `input_image_2` \~ `input_image_8` | string  | No       | Additional reference images                                                                               |
| `width`                            | integer | No       | Output width, preferably divisible by 16                                                                  |
| `height`                           | integer | No       | Output height, preferably divisible by 16                                                                 |
| `size`                             | string  | No       | OpenAI-style size string such as `1792x1024`; use this or `width` / `height`, not both                    |
| `output_format`                    | string  | No       | `jpeg` / `png`                                                                                            |
| `seed`                             | integer | No       | Fixed seed for reproducibility                                                                            |
| `safety_tolerance`                 | integer | No       | Safety level, default 2                                                                                   |

## Prompt Tips

* Refer to sources explicitly as `image 1`, `image 2`, and `image 3`
* Name the key elements that must be preserved
* State that the output should be one coherent new image
* Say what to avoid, such as collage, split-screen, borders, or labels

```text theme={null}
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.
```

## Important Notes

1. **Endpoint**: Flux text-to-image, single-image editing, and multi-image editing all use `/v1/images/generations`
2. **Request format**: Use JSON, not multipart form data
3. **Multi-image limit**: Flux 2 Pro / Max / Flex support up to 8 reference images
4. **Image source**: Public URLs are recommended; local files can be converted to data URLs
5. **Result URL**: `data[0].url` is valid for about 10 minutes, so download immediately

## Related Resources

* [Flux Image Generation](/en/api-capabilities/flux-image-generation) - Text-to-image parameters and model notes
* [Pricing Calculator](https://api2.laozhang.ai/account/pricing) - Real-time pricing
* [Online Demo](https://yingtu.ai) - Test Flux editing