Edit images - Lumenfall

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"

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

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

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.

image

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

prompt

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

model

string

required

The model to use for image editing. See Models.

mask

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

size

string

default:"1024x1024"

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

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

Converted

quality

string

default:"auto"

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

response_format

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

output_format

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

output_compression

integer

default:"100"

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

scale_factor

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

thinking

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

prompt_enhancement

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

user

string

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

Query parameters

dryRun

boolean

default:"false"

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

Response

created

integer

Unix timestamp of when the request was created.

size

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.

data

array

Array of generated image objects.

Show Image object

url

string

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

b64_json

string

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

revised_prompt

string

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

metadata

object

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

Show Metadata object

provider_name

string

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

provider

string

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

upstream_id

string

The provider’s request ID, useful for reconciliation.

model

string

The model string sent in the request.

executed_model

string

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

cost

number

Effective cost in the currency specified by cost_currency.

cost_currency

string

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

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"

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

​Request body

​Query parameters

​Response

Request body

Query parameters

Response