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

# Editing Images

> Modify an existing image with a text prompt and optional inpainting mask.

The `/v1/images/edits` endpoint takes one or more existing images and a text description of what to change, then returns modified versions. You can target specific regions using a mask (inpainting), or apply changes to the whole image.

***

## Basic example

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import os
    import base64
    from openai import OpenAI

    client = OpenAI(
        base_url="https://api.routeway.ai/v1",
        api_key=os.getenv("ROUTEWAY_API_KEY")
    )

    with open("photo.png", "rb") as f:
        encoded = base64.b64encode(f.read()).decode("utf-8")

    response = client.images.edit(
        model="flux-kontext-max",
        image=encoded,
        prompt="Replace the sky with a dramatic stormy sky, dark clouds and lightning",
        size="1024x1024",
    )

    print(response.data[0].url)
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    import OpenAI from "openai";
    import fs from "fs";

    const client = new OpenAI({
      baseURL: "https://api.routeway.ai/v1",
      apiKey: process.env.ROUTEWAY_API_KEY,
    });

    const imageBuffer = fs.readFileSync("photo.png");
    const encoded = imageBuffer.toString("base64");

    const response = await client.images.edit({
      model: "flux-kontext-max",
      image: encoded,
      prompt: "Replace the sky with a dramatic stormy sky, dark clouds and lightning",
      size: "1024x1024",
    });

    console.log(response.data[0].url);
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    ENCODED=$(base64 -i photo.png)

    curl https://api.routeway.ai/v1/images/edits \
      -H "Authorization: Bearer $ROUTEWAY_API_KEY" \
      -H "Content-Type: application/json" \
      -d "{
        \"model\": \"flux-kontext-max\",
        \"images\": [\"$ENCODED\"],
        \"prompt\": \"Replace the sky with a dramatic stormy sky\",
        \"size\": \"1024x1024\"
      }"
    ```
  </Tab>
</Tabs>

***

## Request parameters

| Parameter             | Type             | Default       | Description                                                                       |
| --------------------- | ---------------- | ------------- | --------------------------------------------------------------------------------- |
| `images`              | array of strings | required      | Base64-encoded PNG images (max 4 MB each)                                         |
| `prompt`              | string           | required      | Text description of the desired change                                            |
| `model`               | string           | —             | Model to use for editing (e.g. `"flux-kontext-max"`)                              |
| `mask`                | string           | —             | Base64-encoded PNG mask — white areas are edited, black areas are preserved       |
| `n`                   | integer          | `1`           | Number of output images to generate (1–10)                                        |
| `size`                | string           | `"1024x1024"` | Output resolution: `"256x256"`, `"512x512"`, or `"1024x1024"`                     |
| `response_format`     | string           | `"url"`       | `"url"` or `"b64_json"`                                                           |
| `strength`            | number           | —             | How strongly the edit is applied (0.0–1.0). Lower = more faithful to the original |
| `guidance_scale`      | number           | —             | How closely the model follows the prompt (0.0–20.0). Higher = more literal        |
| `num_inference_steps` | integer          | —             | Denoising steps (1–100). More steps = sharper result, slower generation           |
| `seed`                | integer          | —             | Fixed seed for reproducible outputs                                               |

***

## Inpainting with a mask

A mask lets you edit only a specific region of the image and leave the rest untouched. The mask is a PNG of the same dimensions as the input:

* **White pixels** → the area you want the model to edit
* **Black pixels** → the area to preserve exactly

```python theme={null}
import os
import base64
from openai import OpenAI

client = OpenAI(
    base_url="https://api.routeway.ai/v1",
    api_key=os.getenv("ROUTEWAY_API_KEY")
)

with open("portrait.png", "rb") as f:
    image_b64 = base64.b64encode(f.read()).decode("utf-8")

# Mask: white over the background, black over the subject
with open("mask_background.png", "rb") as f:
    mask_b64 = base64.b64encode(f.read()).decode("utf-8")

response = client.images.edit(
    model="flux-kontext-max",
    image=image_b64,
    mask=mask_b64,
    prompt="Replace the background with a sunlit Tuscan vineyard",
    size="1024x1024",
)

print(response.data[0].url)
```

<Tip>
  Create masks in any image editor by painting white over the area to change and black over the area to keep, then export as PNG. The mask must be the same width and height as the source image.
</Tip>

***

## Editing multiple images

Pass more than one image to let the model combine or reference several source images in the edit.

```python theme={null}
with open("style_reference.png", "rb") as f:
    style_b64 = base64.b64encode(f.read()).decode("utf-8")

with open("content_image.png", "rb") as f:
    content_b64 = base64.b64encode(f.read()).decode("utf-8")

response = client.images.edit(
    model="flux-kontext-max",
    images=[content_b64, style_b64],
    prompt="Apply the artistic style of the second image to the first image",
    size="1024x1024",
)
```

***

## Controlling the edit with `strength`

`strength` controls how much the model is allowed to deviate from the original image:

| `strength` | Effect                                                      |
| ---------- | ----------------------------------------------------------- |
| `0.1–0.3`  | Subtle changes — texture, colour, minor detail edits        |
| `0.4–0.6`  | Moderate changes — object swaps, lighting adjustments       |
| `0.7–1.0`  | Heavy changes — full style transfer, background replacement |

```python theme={null}
response = client.images.edit(
    model="flux-kontext-max",
    image=image_b64,
    prompt="Make the image look like an oil painting",
    strength=0.8,   # high — allow major stylistic change
    size="1024x1024",
)
```

***

## Reproducible results with `seed`

Pass a fixed integer `seed` to get the same output each time you send the same prompt and image. Useful for A/B testing or generating variants from a known baseline.

```python theme={null}
response = client.images.edit(
    model="flux-kontext-max",
    image=image_b64,
    prompt="Add soft studio lighting",
    seed=42,
    size="1024x1024",
)
```

<Info>
  Not all models honour the `seed` parameter. Results may still vary slightly due to floating-point non-determinism in some backends.
</Info>

***

## Response object

```json theme={null}
{
  "created": 1749052800,
  "data": [
    {
      "url": "https://cdn.routeway.ai/images/edited_abc123.png",
      "revised_prompt": "Replace the sky with a dramatic stormy sky, dark clouds and lightning"
    }
  ]
}
```

Same shape as the generations endpoint — `url` or `b64_json` per item, plus an optional `revised_prompt`.

***

## Image requirements

| Requirement            | Value                          |
| ---------------------- | ------------------------------ |
| Format                 | PNG                            |
| Max file size          | 4 MB per image                 |
| Encoding               | Base64 string                  |
| Max images per request | 10                             |
| Mask format            | PNG, same dimensions as source |

***

## Best practices

<AccordionGroup>
  <Accordion title="Keep source images under 4 MB" icon="file-image">
    Resize large photos before encoding. A 1024×1024 PNG is typically well under 2 MB. Oversized images return a `400` error.

    ```python theme={null}
    from PIL import Image

    img = Image.open("large_photo.jpg")
    img = img.resize((1024, 1024))
    img.save("resized.png", format="PNG")
    ```
  </Accordion>

  <Accordion title="Be explicit about what to keep" icon="shield">
    The more specific the prompt, the better the edit respects the original. Mention what should stay unchanged.

    ```
    # Vague — may alter the whole image
    "Add snow"

    # Specific — limits the change
    "Add a light dusting of snow on the rooftops only, keep the people and street unchanged"
    ```
  </Accordion>

  <Accordion title="Use lower strength for subtle edits" icon="sliders-horizontal">
    A `strength` of `0.3–0.5` works well for lighting corrections, colour grading, and texture changes without losing structural detail.
  </Accordion>

  <Accordion title="Increase guidance_scale for literal prompts" icon="target">
    When the model isn't following the prompt closely enough, increase `guidance_scale` (try `7–12`). Very high values (`>15`) can introduce artefacts.
  </Accordion>
</AccordionGroup>