Skip to main content
Image editing uses AI to modify existing images based on text instructions. This includes inpainting (filling in regions), outpainting (extending images), and style transfer.

​
Overview

Unlike image generation which creates from scratch, image editing takes an existing image and transforms it. You provide the source image and describe the changes you want. 
from openai import OpenAI
import base64

client = OpenAI(
    api_key="your-lumenfall-api-key",
    base_url="https://api.lumenfall.ai/openai/v1"
)

# Load your source image
with open("source.png", "rb") as f:
    image_data = base64.b64encode(f.read()).decode()

response = client.images.edit(
    model="gemini-3-pro-image",
    image=image_data,
    prompt="Change the sky to a dramatic sunset with orange and purple clouds"
)

print(response.data[0].url)

​
Editing techniques

​
Inpainting

Inpainting replaces a specific region of an image. You provide a mask indicating which area to modify. 
# Mask: white pixels = edit, black pixels = keep
with open("source.png", "rb") as f:
    image_data = base64.b64encode(f.read()).decode()

with open("mask.png", "rb") as f:
    mask_data = base64.b64encode(f.read()).decode()

response = client.images.edit(
    model="gemini-3-pro-image",
    image=image_data,
    mask=mask_data,
    prompt="A red sports car"
)
Use cases:
  • Remove unwanted objects from photos
  • Replace backgrounds
  • Add or modify specific elements

​
Outpainting

Outpainting extends an image beyond its original borders. The AI generates content that seamlessly continues the existing image. 
response = client.images.edit(
    model="gemini-3-pro-image",
    image=image_data,
    prompt="Extend the landscape to show more of the mountain range",
    size="1792x1024"  # Larger than original
)
Use cases:
  • Expand images for different aspect ratios
  • Add context around a subject
  • Create panoramic versions of photos

​
Style transfer

Transform the visual style of an image while preserving its content. 
response = client.images.edit(
    model="gemini-3-pro-image",
    image=image_data,
    prompt="Convert to a watercolor painting style"
)
Use cases:
  • Create artistic versions of photos
  • Match images to brand aesthetics
  • Generate variations with different moods

​
Choosing a model

Models vary in their editing capabilities:
ModelStrengthsNotes
gemini-3-pro-imageVersatile editing, good at following instructionsHandles most editing tasks well
gpt-image-1.5Precise edits, text-awareExcellent at preserving unmasked regions
flux.2-maxStyle transfer, artistic editsStrong aesthetic transformations

​
Writing editing prompts

Editing prompts differ from generation prompts. Be specific about what to change and what to preserve.

​
Focus on the change

Describe the modification, not the entire image: 
A beautiful living room with a blue sofa, wooden floors, plants, and natural lighting

​
Reference the original

When helpful, reference elements in the source image: 
Replace the empty wall behind the desk with floor-to-ceiling bookshelves

​
Specify preservation

Tell the model what to keep: 
Add a sunset sky, keep the foreground and buildings unchanged

​
Working with masks

Masks control which regions the model can modify. A mask is an image where:
  • White pixels = areas to edit
  • Black pixels = areas to preserve

​
Creating masks

You can create masks using:
  • Image editing software (Photoshop, GIMP, Figma)
  • Programmatic tools (PIL/Pillow, OpenCV)
  • AI-based segmentation
from PIL import Image

# Create a simple rectangular mask
mask = Image.new("L", (1024, 1024), 0)  # Black background
# Draw white rectangle where you want edits
from PIL import ImageDraw
draw = ImageDraw.Draw(mask)
draw.rectangle([100, 100, 400, 400], fill=255)
mask.save("mask.png")

​
Mask tips

Hard mask edges can create visible seams. Apply a slight blur to mask edges for smoother transitions.
Make masks slightly larger than the object you’re editing. This gives the model context for seamless blending.
The mask must be the same dimensions as the source image, or the API will reject the request.

​
Image formats

Lumenfall accepts images as:
  • Base64-encoded data - Include the image directly in the request
  • URLs - Reference publicly accessible images
# Using a URL
response = client.images.edit(
    model="gemini-3-pro-image",
    image="https://example.com/source.png",
    prompt="Add dramatic clouds to the sky"
)
Supported formats: PNG, JPEG, WebP. PNG is recommended for images with transparency or when using masks.

​
Cost estimation

Use dry run mode to estimate costs before editing. Add ?dryRun=true to any request to get a cost estimate without executing it. See the Cost estimation API reference for details and response format.

​
Best practices

Editing works best with clear, high-resolution source images. Low-quality inputs produce low-quality outputs.
For complex changes, edit in steps. Change one element at a time rather than everything at once.
When inpainting, start with a small masked area to test. Expand the mask once you’re happy with the results.
Always preserve your source images. Editing is not always reversible, and you may want to try different approaches.

​
Next steps

Image Generation

Create new images from text prompts.

API Reference

Full endpoint documentation and parameters.