Editing Images

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

Python
Node.js
cURL

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)

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);

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\"
  }"

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

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)

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.

Editing multiple images

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

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

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.

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

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

Response object

{
  "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

Keep source images under 4 MB

Resize large photos before encoding. A 1024×1024 PNG is typically well under 2 MB. Oversized images return a 400 error.

from PIL import Image

img = Image.open("large_photo.jpg")
img = img.resize((1024, 1024))
img.save("resized.png", format="PNG")

Be explicit about what to keep

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"

Use lower strength for subtle edits

A strength of 0.3–0.5 works well for lighting corrections, colour grading, and texture changes without losing structural detail.

Increase guidance_scale for literal prompts

When the model isn’t following the prompt closely enough, increase guidance_scale (try 7–12). Very high values (>15) can introduce artefacts.

Get Started

Platform Details

Help & Resources

Core Concepts

Account Management

Guides

Basic example

Request parameters

Inpainting with a mask

Editing multiple images

Controlling the edit with `strength`

Reproducible results with `seed`

Response object

Image requirements

Best practices

​Basic example

​Request parameters

​Inpainting with a mask

​Editing multiple images

​Controlling the edit with strength

​Reproducible results with seed

​Response object

​Image requirements

​Best practices

Basic example

Request parameters

Inpainting with a mask

Editing multiple images

Controlling the edit with `strength`

Reproducible results with `seed`

Response object

Image requirements

Best practices