> ## 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 existing images using text prompts and optional masks.

The image editing endpoint lets you modify existing images by providing a text prompt describing the desired changes. You can optionally include a mask to constrain edits to specific regions.

```
POST https://api.routeway.ai/v1/images/edits
```

## Basic Image Editing

Provide an image and a prompt describing how to modify it.

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

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

    response = client.images.edit(
        model="gpt-image-1",
        image=open("input.png", "rb"),
        prompt="Add a rainbow in the sky",
    )

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

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

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

    const response = await client.images.edit({
      model: "gpt-image-1",
      image: fs.createReadStream("input.png"),
      prompt: "Add a rainbow in the sky",
    });

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

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.routeway.ai/v1/images/edits \
      -H "Authorization: Bearer $ROUTEWAY_API_KEY" \
      -F model="gpt-image-1" \
      -F image="@input.png" \
      -F prompt="Add a rainbow in the sky"
    ```
  </Tab>
</Tabs>

## Inpainting with Masks

Use a mask to specify which region of the image should be edited. The mask is a same-size image where **transparent areas** indicate where edits should be applied.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    response = client.images.edit(
        model="gpt-image-1",
        image=open("room.png", "rb"),
        mask=open("mask.png", "rb"),
        prompt="A modern red sofa",
        size="1024x1024",
    )

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

  <Tab title="Node.js">
    ```javascript theme={null}
    const response = await client.images.edit({
      model: "gpt-image-1",
      image: fs.createReadStream("room.png"),
      mask: fs.createReadStream("mask.png"),
      prompt: "A modern red sofa",
      size: "1024x1024",
    });

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

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.routeway.ai/v1/images/edits \
      -H "Authorization: Bearer $ROUTEWAY_API_KEY" \
      -F model="gpt-image-1" \
      -F image="@room.png" \
      -F mask="@mask.png" \
      -F prompt="A modern red sofa" \
      -F size="1024x1024"
    ```
  </Tab>
</Tabs>

<Info>
  The mask must be a PNG with an alpha channel. Transparent pixels mark the area to edit; opaque pixels are preserved.
</Info>

## Supported Formats

| Format            | Supported |
| ----------------- | --------- |
| PNG               | ✅         |
| JPEG              | ✅         |
| WebP              | ✅         |
| GIF (first frame) | ✅         |

<Warning>
  Images must be square and no larger than 4MB. Non-square images may be automatically cropped or rejected depending on the model.
</Warning>

## Size Constraints

The `size` parameter controls the output dimensions of the edited image.

| Size        | Notes                              |
| ----------- | ---------------------------------- |
| `1024x1024` | Default. Works with all models.    |
| `512x512`   | Smaller output, faster processing. |
| `256x256`   | Minimum supported size.            |

<Tip>
  For best results, provide an input image that matches the requested output size. Mismatched sizes may result in distortion or quality loss.
</Tip>

## Editing with Multiple Outputs

Generate several variations of an edit by setting `n`.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    response = client.images.edit(
        model="gpt-image-1",
        image=open("photo.png", "rb"),
        prompt="Replace the background with a snowy mountain landscape",
        n=3,
    )

    for i, image in enumerate(response.data):
        print(f"Variation {i + 1}: {image.url}")
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const response = await client.images.edit({
      model: "gpt-image-1",
      image: fs.createReadStream("photo.png"),
      prompt: "Replace the background with a snowy mountain landscape",
      n: 3,
    });

    response.data.forEach((image, i) => {
      console.log(`Variation ${i + 1}: ${image.url}`);
    });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.routeway.ai/v1/images/edits \
      -H "Authorization: Bearer $ROUTEWAY_API_KEY" \
      -F model="gpt-image-1" \
      -F image="@photo.png" \
      -F prompt="Replace the background with a snowy mountain landscape" \
      -F n=3
    ```
  </Tab>
</Tabs>

## Saving Edited Images

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

    response = client.images.edit(
        model="gpt-image-1",
        image=open("input.png", "rb"),
        prompt="Make it look like a pencil sketch",
        response_format="b64_json",
    )

    image_data = base64.b64decode(response.data[0].b64_json)

    with open("edited.png", "wb") as f:
        f.write(image_data)

    print("Edited image saved to edited.png")
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const response = await client.images.edit({
      model: "gpt-image-1",
      image: fs.createReadStream("input.png"),
      prompt: "Make it look like a pencil sketch",
      response_format: "b64_json",
    });

    const imageBuffer = Buffer.from(response.data[0].b64_json, "base64");
    fs.writeFileSync("edited.png", imageBuffer);

    console.log("Edited image saved to edited.png");
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.routeway.ai/v1/images/edits \
      -H "Authorization: Bearer $ROUTEWAY_API_KEY" \
      -F model="gpt-image-1" \
      -F image="@input.png" \
      -F prompt="Make it look like a pencil sketch" \
      -F response_format="b64_json" \
      | jq -r '.data[0].b64_json' | base64 -d > edited.png
    ```
  </Tab>
</Tabs>

## Best Practices

<AccordionGroup>
  <Accordion title="Use masks for precise edits">
    Without a mask, the model decides what to change. For predictable results, provide a mask that clearly marks the target region.
  </Accordion>

  <Accordion title="Keep prompts focused on the edit">
    Describe only what should change, not the entire image. "A blue vase with flowers" works better than re-describing the whole scene.
  </Accordion>

  <Accordion title="Match input and output sizes">
    Provide images at the same resolution you request in `size` to avoid quality degradation from rescaling.
  </Accordion>
</AccordionGroup>