POST /v1/images/generations

Generate images from text descriptions using AI models

Creates images from text prompts using image generation models. Internally routes to chat completion models with image generation capabilities.

Endpoint

POST https://api.llmgateway.io/v1/images/generations

Authentication

Requires authentication using Bearer token or x-api-key header. See Authentication.

Request Body

prompt · string · required

A text description of the desired image(s).

Example: "A white siamese cat"

model · string · default: "auto"

The model to use for image generation.

Options:

• "auto" - Automatically selects gemini-3-pro-image-preview
• "gemini-2.5-flash-image"
• "gemini-3-pro-image-preview"
• Other image generation models

Example: "gemini-2.5-flash-image"

n · number · default: 1

The number of images to generate. Must be between 1 and 10.

Example: 1

size · string

The size of the generated images. Supported sizes depend on the model.

Common sizes:

• "1024x1024" (square)
• "1792x1024" (landscape)
• "1024x1792" (portrait)
• "1536x1024"
• "1024x1536"

Example: "1024x1024"

aspect_ratio · string

The aspect ratio of the generated images. Takes precedence over size if both are provided.

Common ratios:

• "1:1" (square)
• "16:9" (landscape)
• "9:16" (portrait)
• "4:3"
• "3:2"
• "7:4"

Example: "16:9"

quality · string

The quality of the generated image.

Options: "standard", "hd", "low", "medium", "high"

Example: "standard"

style · string

The style of the generated images.

Options:

• "vivid" - Hyper-real, dramatic lighting and colors
• "natural" - Realistic, organic look

Example: "vivid"

response_format · string · default: "b64_json"

The format in which the generated images are returned. Only b64_json is supported.

Example: "b64_json"

Response

created · number

Unix timestamp of when the images were created.

data · array

Array of generated images.

Each image contains:

• b64_json (string): Base64-encoded image data
• revised_prompt (string, optional): The actual prompt used (may differ from input)

Examples

Generate Single Image

cURL

curl https://api.llmgateway.io/v1/images/generations \
  -H "Authorization: Bearer $LLMGATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A serene mountain landscape at sunset",
    "model": "gemini-2.5-flash-image",
    "size": "1024x1024",
    "quality": "standard"
  }'

Generate Multiple Images

response = client.images.generate(
    prompt="A futuristic city skyline",
    model="gemini-2.5-flash-image",
    n=3,
    size="1024x1024"
)

# Save all images
for i, image in enumerate(response.data):
    image_data = base64.b64decode(image.b64_json)
    with open(f"image_{i}.png", "wb") as f:
        f.write(image_data)

Custom Aspect Ratio

response = client.images.generate(
    prompt="A wide panoramic view of the ocean",
    model="gemini-2.5-flash-image",
    aspect_ratio="16:9",  # Wide format
    style="natural"
)

High Quality with Vivid Style

response = client.images.generate(
    prompt="A detailed dragon in a fantasy setting",
    model="gemini-2.5-flash-image",
    quality="hd",
    style="vivid",
    size="1792x1024"
)

Response Example

{
  "created": 1677858242,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...",
      "revised_prompt": "A serene mountain landscape at sunset with dramatic orange and pink skies"
    }
  ]
}

Image Edits Endpoint

The gateway also supports editing existing images:

POST https://api.llmgateway.io/v1/images/edits

Request Body (JSON)

images · array · required

Array of input image references to edit. Each image must have:

• image_url (string): HTTPS URL or base64 data URL

Example:

[
  {"image_url": "https://example.com/image.png"},
  {"image_url": "data:image/png;base64,..."}
]

prompt · string · required

A text description of the desired image edit.

Example: "Add a watercolor effect to this image"

model · string

The model to use for image editing.

Example: "gemini-3-pro-image-preview"

n · number

The number of edited images to generate (1-10).

Example: 1

background · string

Background behavior for generated image output.

Options: "transparent", "opaque", "auto"

Example: "transparent"

input_fidelity · string

Controls fidelity to the original input image(s).

Options: "high", "low"

Example: "high"

quality · string

Output quality for image models.

Options: "low", "medium", "high", "auto"

Example: "high"

size · string

Requested output image size.

Options: "auto", "1024x1024", "1536x1024", "1024x1536"

Example: "1024x1024"

output_format · string

Output image format.

Options: "png", "jpeg", "webp"

Example: "png"

output_compression · number

Compression level for JPEG or WebP output (0-100).

Example: 100

Multipart Form Data

The edits endpoint also accepts multipart/form-data for OpenAI compatibility:

curl https://api.llmgateway.io/v1/images/edits \
  -H "Authorization: Bearer $LLMGATEWAY_API_KEY" \
  -F image=@source.png \
  -F prompt="Add a sunset background" \
  -F model="gemini-3-pro-image-preview" \
  -F size="1024x1024"

Supported field names for the image file:

• image
• image[] (used by some clients)
• file

Optional mask field:

• mask - Mask image to specify areas to edit

Edit Image Example

response = client.images.edit(
    image=open("source.png", "rb"),
    prompt="Add a watercolor painting effect",
    model="gemini-3-pro-image-preview",
    size="1024x1024",
    input_fidelity="high",
    quality="high"
)

# Save edited image
image_data = base64.b64decode(response.data[0].b64_json)
with open("edited.png", "wb") as f:
    f.write(image_data)

Error Responses

Invalid Request

{
  "error": true,
  "status": 400,
  "message": "Invalid request parameters: prompt: Required"
}

No Images Generated

{
  "error": true,
  "status": 500,
  "message": "The model did not generate any images. Try a different model with image generation capabilities."
}

Invalid Image URL

{
  "error": true,
  "status": 400,
  "message": "images[0].image_url must be an https URL or a base64 data URL"
}

Notes

• Images are returned as base64-encoded data in the response
• The gateway internally uses chat completion models with image generation capabilities
• Different models support different aspect ratios and sizes
• For best results, provide detailed and specific prompts
• The revised_prompt in the response shows how the model interpreted your prompt