Generate images

curl https://api.lumenfall.ai/openai/v1/images/generations \
  -H "Authorization: Bearer $LUMENFALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "prompt": "A futuristic city skyline at sunset",
    "n": 1,
    "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.generate(
    model="gemini-3-pro-image",
    prompt="A futuristic city skyline at sunset",
    n=1,
    size="1024x1024"
)

print(response.data[0].url)

import OpenAI from "openai";

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

const response = await client.images.generate({
  model: "gemini-3-pro-image",
  prompt: "A futuristic city skyline at sunset",
  n: 1,
  size: "1024x1024",
});

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

{
  "created": 1702345678,
  "size": "1024x1024",
  "data": [
    {
      "url": "https://media.lumenfall.ai/abc123.png",
      "revised_prompt": "A futuristic city skyline at sunset with flying vehicles and neon lights"
    }
  ],
  "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

generations

curl https://api.lumenfall.ai/openai/v1/images/generations \
  -H "Authorization: Bearer $LUMENFALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "prompt": "A futuristic city skyline at sunset",
    "n": 1,
    "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.generate(
    model="gemini-3-pro-image",
    prompt="A futuristic city skyline at sunset",
    n=1,
    size="1024x1024"
)

print(response.data[0].url)

import OpenAI from "openai";

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

const response = await client.images.generate({
  model: "gemini-3-pro-image",
  prompt: "A futuristic city skyline at sunset",
  n: 1,
  size: "1024x1024",
});

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

{
  "created": 1702345678,
  "size": "1024x1024",
  "data": [
    {
      "url": "https://media.lumenfall.ai/abc123.png",
      "revised_prompt": "A futuristic city skyline at sunset with flying vehicles and neon lights"
    }
  ],
  "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 from a text prompt using AI models from various providers.

OpenAI CompatibilityThis endpoint implements the OpenAI Images 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.

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.

string

required

A text description of the desired image. Maximum length varies by model.Renamed

string

required

The model to use for image generation. See Models.

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
1024x1792 (portrait)
1792x1024 (landscape)

Converted

string

default:"standard"

The quality of the image. Options: standard, hd. Only supported by some models.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

string

default:"vivid"

The style of the generated images. Options: vivid, natural. Only supported by some models like DALL-E 3.Passthrough

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 generating 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/generations \
  -H "Authorization: Bearer $LUMENFALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "prompt": "A futuristic city skyline at sunset",
    "n": 1,
    "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.generate(
    model="gemini-3-pro-image",
    prompt="A futuristic city skyline at sunset",
    n=1,
    size="1024x1024"
)

print(response.data[0].url)

import OpenAI from "openai";

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

const response = await client.images.generate({
  model: "gemini-3-pro-image",
  prompt: "A futuristic city skyline at sunset",
  n: 1,
  size: "1024x1024",
});

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

{
  "created": 1702345678,
  "size": "1024x1024",
  "data": [
    {
      "url": "https://media.lumenfall.ai/abc123.png",
      "revised_prompt": "A futuristic city skyline at sunset with flying vehicles and neon lights"
    }
  ],
  "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"
  }
}

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