Image Generation
Generate images using generate_media with mode="image". The system auto-selects the best backend based on available API keys.
Quick Start
# Simple text-to-image (auto-selects backend)
generate_media(prompt="A cat in space", mode="image")
# Specify backend and quality
generate_media(prompt="A logo for a coffee shop", mode="image",
backend_type="openai", quality="high")
# Batch generation (parallel)
generate_media(prompts=["sunset over ocean", "mountain landscape", "city at night"],
mode="image", max_concurrent=3)
Backend Comparison
| Backend |
Default Model |
Strengths |
API Key |
| Google (priority 1) |
gemini-3.1-flash-image-preview (Nano Banana 2) |
Fast, flexible sizes, image editing, multi-turn |
GOOGLE_API_KEY or GEMINI_API_KEY |
| OpenAI (priority 2) |
gpt-5.4 |
High quality, transparent backgrounds, continuation via response ID |
OPENAI_API_KEY |
| Grok (priority 3) |
grok-imagine-image |
1k resolution, continuation via stored data URI |
XAI_API_KEY |
| OpenRouter (priority 4) |
google/gemini-3.1-flash-image-preview |
Access to multiple models via single API |
OPENROUTER_API_KEY |
Key Parameters
| Parameter |
Description |
Example |
prompt |
Text description of the image |
"A watercolor painting of mountains" |
backend_type |
Force a specific backend |
"google", "openai", "grok", "openrouter" |
model |
Override default model |
"gemini-3-pro-image-preview" for studio quality |
quality |
Image quality (OpenAI) |
"low", "medium", "high", "auto" |
size |
Image dimensions |
See backends reference |
aspect_ratio |
Aspect ratio |
"16:9", "1:1", "4:5" |
input_images |
Source images for image-to-image editing |
["photo.jpg"] |
continue_from |
Continuation ID for multi-turn editing |
result["continuation_id"] |
Image-to-Image Editing
Transform existing images by providing input_images:
generate_media(
prompt="Make it look like a watercolor painting",
mode="image",
input_images=["photo.jpg"]
)
Supported backends for image-to-image: Google (Gemini), OpenAI, Grok. The system auto-selects if your current backend doesn't support it.
Multi-Turn Editing (Continuation)
Iteratively refine images using continue_from:
# First generation
result = generate_media(prompt="A logo for a coffee shop", mode="image")
# Refine using the continuation ID
result2 = generate_media(
prompt="Make the text larger and add a cup icon",
mode="image",
continue_from=result["continuation_id"]
)
Each backend uses a different continuation mechanism:
- OpenAI: Passes
previous_response_id (stateless)
- Google Gemini: In-memory chat store (LRU, 50 items)
- Grok: In-memory data URI store (LRU, 50 items)
Continuation only works for single image generation (not batch).
Google: Gemini vs Imagen
Google supports two API paths. Gemini (Nano Banana 2) is the default and recommended for most use cases. Imagen is only needed for advanced reference-image editing features.
- Gemini models (
gemini-*): generate_content() — text-to-image, image editing via input_images, multi-turn continuation
- Imagen models (
imagen-*): generate_images() / edit_image() — text-to-image with negative_prompt/seed/guidance_scale, plus style transfer, control editing, and subject consistency via reference images
For studio-quality precision and text rendering, use: model="gemini-3-pro-image-preview" (Pro-tier).
Need More Control?
- Per-backend sizes, quality options, and quirks: See references/backends.md
- Complete
extra_params reference: See references/extra_params.md
- Advanced editing (inpainting, style transfer, control, subject): See references/editing.md
1---2name: image-generation3description: Guide to image generation and editing in MassGen. Use when creating images, editing existing images, iterating on image designs, or choosing between image backends (OpenAI, Google Gemini/Imagen, Grok, OpenRouter).4---56# Image Generation78Generate images using `generate_media` with `mode="image"`. The system auto-selects the best backend based on available API keys.910## Quick Start1112```python13# Simple text-to-image (auto-selects backend)14generate_media(prompt="A cat in space", mode="image")1516# Specify backend and quality17generate_media(prompt="A logo for a coffee shop", mode="image",18 backend_type="openai", quality="high")1920# Batch generation (parallel)21generate_media(prompts=["sunset over ocean", "mountain landscape", "city at night"],22 mode="image", max_concurrent=3)23```2425## Backend Comparison2627| Backend | Default Model | Strengths | API Key |28|---------|--------------|-----------|---------|29| **Google** (priority 1) | `gemini-3.1-flash-image-preview` (Nano Banana 2) | Fast, flexible sizes, image editing, multi-turn | `GOOGLE_API_KEY` or `GEMINI_API_KEY` |30| **OpenAI** (priority 2) | `gpt-5.4` | High quality, transparent backgrounds, continuation via response ID | `OPENAI_API_KEY` |31| **Grok** (priority 3) | `grok-imagine-image` | 1k resolution, continuation via stored data URI | `XAI_API_KEY` |32| **OpenRouter** (priority 4) | `google/gemini-3.1-flash-image-preview` | Access to multiple models via single API | `OPENROUTER_API_KEY` |3334## Key Parameters3536| Parameter | Description | Example |37|-----------|-------------|---------|38| `prompt` | Text description of the image | `"A watercolor painting of mountains"` |39| `backend_type` | Force a specific backend | `"google"`, `"openai"`, `"grok"`, `"openrouter"` |40| `model` | Override default model | `"gemini-3-pro-image-preview"` for studio quality |41| `quality` | Image quality (OpenAI) | `"low"`, `"medium"`, `"high"`, `"auto"` |42| `size` | Image dimensions | See backends reference |43| `aspect_ratio` | Aspect ratio | `"16:9"`, `"1:1"`, `"4:5"` |44| `input_images` | Source images for image-to-image editing | `["photo.jpg"]` |45| `continue_from` | Continuation ID for multi-turn editing | `result["continuation_id"]` |4647## Image-to-Image Editing4849Transform existing images by providing `input_images`:5051```python52generate_media(53 prompt="Make it look like a watercolor painting",54 mode="image",55 input_images=["photo.jpg"]56)57```5859Supported backends for image-to-image: Google (Gemini), OpenAI, Grok. The system auto-selects if your current backend doesn't support it.6061## Multi-Turn Editing (Continuation)6263Iteratively refine images using `continue_from`:6465```python66# First generation67result = generate_media(prompt="A logo for a coffee shop", mode="image")6869# Refine using the continuation ID70result2 = generate_media(71 prompt="Make the text larger and add a cup icon",72 mode="image",73 continue_from=result["continuation_id"]74)75```7677Each backend uses a different continuation mechanism:78- **OpenAI**: Passes `previous_response_id` (stateless)79- **Google Gemini**: In-memory chat store (LRU, 50 items)80- **Grok**: In-memory data URI store (LRU, 50 items)8182Continuation only works for single image generation (not batch).8384## Google: Gemini vs Imagen8586Google supports two API paths. **Gemini (Nano Banana 2) is the default and recommended for most use cases.** Imagen is only needed for advanced reference-image editing features.8788- **Gemini models** (`gemini-*`): `generate_content()` — text-to-image, image editing via `input_images`, multi-turn continuation89- **Imagen models** (`imagen-*`): `generate_images()` / `edit_image()` — text-to-image with `negative_prompt`/`seed`/`guidance_scale`, plus style transfer, control editing, and subject consistency via reference images9091For studio-quality precision and text rendering, use: `model="gemini-3-pro-image-preview"` (Pro-tier).9293## Need More Control?9495- **Per-backend sizes, quality options, and quirks**: See [references/backends.md](references/backends.md)96- **Complete `extra_params` reference**: See [references/extra_params.md](references/extra_params.md)97- **Advanced editing (inpainting, style transfer, control, subject)**: See [references/editing.md](references/editing.md)
massgen