Edit images

curl https://api.lumenfall.ai/openai/v1/images/edits \
  -H "Authorization: Bearer $LUMENFALL_API_KEY" \
  -F "model=gemini-3-pro-image" \
  -F "image=@original.png" \
  -F "prompt=Add a red hat to the person" \
  -F "size=1024x1024"

from openai import OpenAI

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

response = client.images.edit(
    model="gemini-3-pro-image",
    image=open("original.png", "rb"),
    prompt="Add a red hat to the person",
    size="1024x1024"
)

print(response.data[0].url)

import OpenAI from "openai";
import fs from "fs";

const client = new OpenAI({
  apiKey: "your-lumenfall-api-key",
  baseURL: "https://api.lumenfall.ai/openai/v1",
});

const response = await client.images.edit({
  model: "gemini-3-pro-image",
  image: fs.createReadStream("original.png"),
  prompt: "Add a red hat to the person",
  size: "1024x1024",
});

console.log(response.data[0].url);

curl https://api.lumenfall.ai/openai/v1/images/edits \
  -H "Authorization: Bearer $LUMENFALL_API_KEY" \
  -F "model=gemini-3-pro-image" \
  -F "image[]=@lotion.png" \
  -F "image[]=@candle.png" \
  -F "image[]=@soap.png" \
  -F "prompt=Create a gift basket with these items"

from openai import OpenAI

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

response = client.images.edit(
    model="gemini-3-pro-image",
    image=[
        open("lotion.png", "rb"),
        open("candle.png", "rb"),
        open("soap.png", "rb"),
    ],
    prompt="Create a gift basket with these items"
)

print(response.data[0].url)

import OpenAI from "openai";
import fs from "fs";

const client = new OpenAI({
  apiKey: "your-lumenfall-api-key",
  baseURL: "https://api.lumenfall.ai/openai/v1",
});

const response = await client.images.edit({
  model: "gemini-3-pro-image",
  image: [
    fs.createReadStream("lotion.png"),
    fs.createReadStream("candle.png"),
    fs.createReadStream("soap.png"),
  ],
  prompt: "Create a gift basket with these items",
});

console.log(response.data[0].url);

{
  "created": 1702345678,
  "size": "1024x1024",
  "data": [
    {
      "url": "https://media.lumenfall.ai/abc123.png",
      "revised_prompt": "Add a stylish red fedora hat to the person in the image"
    }
  ],
  "metadata": {
    "model": "gemini-3-pro-image",
    "executed_model": "vertex/gemini-3-pro-image",
    "provider": "vertex",
    "provider_name": "Google Vertex AI",
    "cost": 0.04,
    "cost_currency": "USD"
  }
}

POST

openai

images

edits

curl https://api.lumenfall.ai/openai/v1/images/edits \
  -H "Authorization: Bearer $LUMENFALL_API_KEY" \
  -F "model=gemini-3-pro-image" \
  -F "image=@original.png" \
  -F "prompt=Add a red hat to the person" \
  -F "size=1024x1024"

from openai import OpenAI

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

response = client.images.edit(
    model="gemini-3-pro-image",
    image=open("original.png", "rb"),
    prompt="Add a red hat to the person",
    size="1024x1024"
)

print(response.data[0].url)

import OpenAI from "openai";
import fs from "fs";

const client = new OpenAI({
  apiKey: "your-lumenfall-api-key",
  baseURL: "https://api.lumenfall.ai/openai/v1",
});

const response = await client.images.edit({
  model: "gemini-3-pro-image",
  image: fs.createReadStream("original.png"),
  prompt: "Add a red hat to the person",
  size: "1024x1024",
});

console.log(response.data[0].url);

curl https://api.lumenfall.ai/openai/v1/images/edits \
  -H "Authorization: Bearer $LUMENFALL_API_KEY" \
  -F "model=gemini-3-pro-image" \
  -F "image[]=@lotion.png" \
  -F "image[]=@candle.png" \
  -F "image[]=@soap.png" \
  -F "prompt=Create a gift basket with these items"

from openai import OpenAI

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

response = client.images.edit(
    model="gemini-3-pro-image",
    image=[
        open("lotion.png", "rb"),
        open("candle.png", "rb"),
        open("soap.png", "rb"),
    ],
    prompt="Create a gift basket with these items"
)

print(response.data[0].url)

import OpenAI from "openai";
import fs from "fs";

const client = new OpenAI({
  apiKey: "your-lumenfall-api-key",
  baseURL: "https://api.lumenfall.ai/openai/v1",
});

const response = await client.images.edit({
  model: "gemini-3-pro-image",
  image: [
    fs.createReadStream("lotion.png"),
    fs.createReadStream("candle.png"),
    fs.createReadStream("soap.png"),
  ],
  prompt: "Create a gift basket with these items",
});

console.log(response.data[0].url);

{
  "created": 1702345678,
  "size": "1024x1024",
  "data": [
    {
      "url": "https://media.lumenfall.ai/abc123.png",
      "revised_prompt": "Add a stylish red fedora hat to the person in the image"
    }
  ],
  "metadata": {
    "model": "gemini-3-pro-image",
    "executed_model": "vertex/gemini-3-pro-image",
    "provider": "vertex",
    "provider_name": "Google Vertex AI",
    "cost": 0.04,
    "cost_currency": "USD"
  }
}

Edit or extend images using AI models from various providers. This endpoint accepts multipart/form-data requests for file uploads.

OpenAI CompatibilityThis endpoint implements the OpenAI Images Edit API. You can use any OpenAI SDK by changing the base URL to https://api.lumenfall.ai/openai/v1.Lumenfall normalizes behavior across all models - mapping parameters, emulating features, and standardizing errors - so your code works consistently regardless of which provider handles the request.

Upscaling uses this endpoint too. To upscale an image, call this endpoint with an upscale model and a scale_factor instead of a prompt. See Image upscaling for the full guide and model list.

Record & Replay: this endpoint supports replaying recorded responses and instant mock responses. Set X-Lumenfall-Replay (and optionally X-Lumenfall-Replay-Match) to record, replay, or mock a call. See the Record & Replay guide.

Request body

You can include additional parameters not listed here. They will be passed through to the underlying provider.

What do the parameter badges mean?

Each parameter has a badge showing how Lumenfall handles it across different providers:

Badge	Meaning
Passthrough	Passed as-is; some providers may ignore it
Renamed	Field name is mapped to the provider’s expected name
Converted	Value is transformed to match each provider’s format
Emulated	Works consistently on all models, even if the provider doesn’t natively support it

Learn more about unified model behavior.

file or array

required

The image(s) to edit. Must be a supported image file (PNG, WebP, or JPG) or an array of images. Maximum file size varies by model.Renamed

string

required

A text description of the desired edit. Maximum length varies by model. Not required when using an upscale model - pass scale_factor instead.Renamed

string

required

The model to use for image editing. See Models.

file

An image whose fully transparent areas (where alpha is zero) indicate where the image should be edited. Must be a valid PNG file with the same dimensions as the source image.Passthrough

integer

default:"1"

The number of images to generate. Must be between 1 and 10. Some models only support n=1.Emulated

string

default:"1024x1024"

The size of the generated images. Supported sizes vary by model:

256x256
512x512
1024x1024
1024x1536 (portrait)
1536x1024 (landscape)

Converted

string

default:"auto"

The quality of the image. Options vary by model: auto, low, medium, high, standard, hd.Passthrough

string

default:"url"

The format of the generated images. Options:

url — Returns a URL to the generated image
b64_json — Returns the image as base64-encoded JSON

Emulated

string

default:"png"

The image file format to generate. Lumenfall supports more formats than OpenAI:

png Lossless compression, supports transparency
jpeg — Lossy compression, smaller file size
gif — Supports animation and transparency
webp — Modern format with good compression
avif — Best compression, modern browsers only (Limited to 1,600px on the longest side. Larger images will fall back to the original format.)

If the provider returns a different format, Lumenfall automatically converts the image.Emulated

integer

default:"100"

Compression quality for lossy formats (jpeg, webp, avif). Range: 1-100, where 100 is highest quality.Emulated

number

Used only when calling an upscale model. Multiplies the input dimensions on each axis (e.g., 2 doubles width and height). Supported values vary by model. When omitted, each upscale model uses its default. Ignored by non-upscale models.Renamed

string

Controls the model’s internal reasoning effort. Options:

off — no extra reasoning
on — enable reasoning at the level the model treats as sensible
minimal — light reasoning
high — maximum reasoning

Supported values vary by model. Each model advertises the exact set it accepts as the parameter’s enum in its model schema (/openai/v1/models?schema=true) - a model with simple on/off support advertises ["off", "on"], while a model with graded levels advertises ["off", "on", "minimal", "high"]. Sending a value the chosen model does not support returns a 400 listing the supported set. thinking_level is accepted as an alias. Omit to use the model’s default.Converted

string

Whether an LLM rewrites and expands your prompt before generation. Options: on, off. When enabled and the provider returns the rewritten prompt, it appears in the response as revised_prompt. If the routed model does not support enhancement, the parameter is ignored. Omit to use the model’s default.Converted

string

A unique identifier representing your end-user. Only used by some providers.Passthrough

Query parameters

boolean

default:"false"

If true, returns a cost estimate without editing the image. See Cost estimation.

Response

integer

Unix timestamp of when the request was created.

string

Actual output dimensions as "WIDTHxHEIGHT" (e.g., "1024x1024"). Extracted from the generated image. May differ from the requested size if the model produced a different resolution.

array

Array of generated image objects.

Show Image object

string

URL of the generated image. Only present if response_format is url.

string

Base64-encoded image data. Only present if response_format is b64_json.

string

The prompt that was used to generate the image, if the model revised the original prompt.

object

Metadata about the request execution, including effective cost. See Billing.

Show Metadata object

string

Provider display name (e.g., "Google Vertex AI").

string

Provider slug (e.g., "vertex").

string

The provider’s request ID, useful for reconciliation.

string

The model string sent in the request.

string

The model that was actually executed, as "{provider_slug}/{provider_model}".

number

Effective cost in the currency specified by cost_currency.

string

Currency of the cost (e.g., "USD").

Headers

Optional headers that enable Record & Replay. See the guide and Modes & matching for the full behavior matrix, response signals, and error codes.

string

Activation: record, replay-or-mock, replay-or-error, replay-or-live, replay-or-record, mock, or off. Omit (with no key default) to run normally.

string

default:"standard"

How recordings are matched: standard, strict, specific, or pinned.

string

Comma-separated fields to match on. Required for specific.

string

Recording ID to replay. Required for pinned.

string

default:"instant"

Latency simulation: instant, real, or {ttfb},{duration} in ms.

curl https://api.lumenfall.ai/openai/v1/images/edits \
  -H "Authorization: Bearer $LUMENFALL_API_KEY" \
  -F "model=gemini-3-pro-image" \
  -F "image=@original.png" \
  -F "prompt=Add a red hat to the person" \
  -F "size=1024x1024"

from openai import OpenAI

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

response = client.images.edit(
    model="gemini-3-pro-image",
    image=open("original.png", "rb"),
    prompt="Add a red hat to the person",
    size="1024x1024"
)

print(response.data[0].url)

import OpenAI from "openai";
import fs from "fs";

const client = new OpenAI({
  apiKey: "your-lumenfall-api-key",
  baseURL: "https://api.lumenfall.ai/openai/v1",
});

const response = await client.images.edit({
  model: "gemini-3-pro-image",
  image: fs.createReadStream("original.png"),
  prompt: "Add a red hat to the person",
  size: "1024x1024",
});

console.log(response.data[0].url);

curl https://api.lumenfall.ai/openai/v1/images/edits \
  -H "Authorization: Bearer $LUMENFALL_API_KEY" \
  -F "model=gemini-3-pro-image" \
  -F "image[]=@lotion.png" \
  -F "image[]=@candle.png" \
  -F "image[]=@soap.png" \
  -F "prompt=Create a gift basket with these items"

from openai import OpenAI

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

response = client.images.edit(
    model="gemini-3-pro-image",
    image=[
        open("lotion.png", "rb"),
        open("candle.png", "rb"),
        open("soap.png", "rb"),
    ],
    prompt="Create a gift basket with these items"
)

print(response.data[0].url)

import OpenAI from "openai";
import fs from "fs";

const client = new OpenAI({
  apiKey: "your-lumenfall-api-key",
  baseURL: "https://api.lumenfall.ai/openai/v1",
});

const response = await client.images.edit({
  model: "gemini-3-pro-image",
  image: [
    fs.createReadStream("lotion.png"),
    fs.createReadStream("candle.png"),
    fs.createReadStream("soap.png"),
  ],
  prompt: "Create a gift basket with these items",
});

console.log(response.data[0].url);

{
  "created": 1702345678,
  "size": "1024x1024",
  "data": [
    {
      "url": "https://media.lumenfall.ai/abc123.png",
      "revised_prompt": "Add a stylish red fedora hat to the person in the image"
    }
  ],
  "metadata": {
    "model": "gemini-3-pro-image",
    "executed_model": "vertex/gemini-3-pro-image",
    "provider": "vertex",
    "provider_name": "Google Vertex AI",
    "cost": 0.04,
    "cost_currency": "USD"
  }
}

Generate images Generate videos

Overview

Images

Videos

Chat

Models

Webhooks

Billing

Request body

Query parameters

Response

Headers

​Request body

​Query parameters

​Response

​Headers

Request body

Query parameters

Response

Headers