> For the complete documentation index, see [llms.txt](https://docs.qolaba.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qolaba.ai/api-platform/api-platform/image-generation/text-to-image.md). # Text-to-Image ## Text to image API `POST /api/v1/images/generate` **Headers** | Name | Value | | ------------- | ------------------ | | Content-Type | `application/json` | | Authorization | `Bearer ` | *** ### Models at a Glance | Model ID | Name | Engine | Speed | Max Resolution | Max Images | Key Feature | | -------------------------- | --------------- | ---------------- | -------- | -------------- | ---------- | ------------------------------------- | | `vertex/nano-banana-flash` | Nano Banana 2 | Gemini Flash | Fast | 4K | 10 | Search grounding | | `vertex/nano-banana-pro` | Nano Banana Pro | Gemini Pro | Standard | 4K | 10 | Text rendering, character consistency | | `vertex/imagen-4` | Imagen 4 | Imagen 4.0 | Standard | 2K | 4 | Balanced quality + adherence | | `vertex/imagen-4-fast` | Imagen 4 Fast | Imagen 4.0 Fast | Fastest | \~1K | 4 | Lowest cost, highest throughput | | `vertex/imagen-4-ultra` | Imagen 4 Ultra | Imagen 4.0 Ultra | Slowest | 2K | 4 | Highest quality, complex prompts | *** ### Nano Banana Flash — `vertex/nano-banana-flash` Powered by **Gemini 3.1 Flash**. Best for fast generation, real-time search-grounded accuracy, high-volume workflows, and image-to-image editing. #### Minimal ```json { "model": "vertex/nano-banana-flash", "prompt": "A cozy Japanese ramen shop on a rainy night, steam rising from bowls, warm ambient lighting" } ``` #### Standard ```json { "model": "vertex/nano-banana-flash", "prompt": "A hyperrealistic macro photograph of a butterfly on a lavender flower, water droplets on wings, golden hour light", "aspect_ratio": "4:3", "quality": "2K", "num_images": 1, "temperature": 1.0, "seed": 42 } ``` #### With Search Grounding Enable real-time Google Search so the model generates factually and visually accurate content — real architecture, real locations, real brand identities. ```json { "model": "vertex/nano-banana-flash", "prompt": "The interior of the Pantheon in Rome with sunlight streaming through the oculus, accurate architecture and proportions", "aspect_ratio": "4:3", "quality": "2K", "use_search_grounding": true } ``` #### Multiple Variations ```json { "model": "vertex/nano-banana-flash", "prompt": "A minimalist flat illustration of a coffee cup with steam, pastel color palette, icon style", "aspect_ratio": "1:1", "quality": "1K", "num_images": 4, "temperature": 1.1 } ``` #### Parameters | Field | Type | Default | Options | Description | | ---------------------- | --------- | ------------ | ------------------------ | ---------------------------------------------------- | | `prompt` | `string` | **required** | max 4000 chars | Text description of the image | | `aspect_ratio` | `string` | `1:1` | See Aspect Ratio Support | Output dimensions | | `quality` | `string` | `2K` | `512`, `1K`, `2K`, `4K` | Output resolution. `4K` triggers higher billing rate | | `num_images` | `integer` | `1` | 1–10 | Variations per call | | `temperature` | `number` | `1.0` | 0–2 | Creativity. Lower = faithful, higher = creative | | `seed` | `integer` | — | any integer | Reproducibility. Same seed + prompt = same image | | `use_search_grounding` | `boolean` | `false` | — | Real-time Google Search context for accuracy | | `celery` | `boolean` | `false` | — | `true` = async, returns `task_id` immediately | *** ### Nano Banana Pro — `vertex/nano-banana-pro` Powered by **Gemini 3 Pro**. Best for production output, multi-language text rendering in images, 4K exports, and consistent character/product depiction across generations. #### Minimal ```json { "model": "vertex/nano-banana-pro", "prompt": "A luxury watch on a black marble surface, dramatic spotlight lighting, product photography" } ``` #### Standard ```json { "model": "vertex/nano-banana-pro", "prompt": "A cinema-quality portrait of a woman in a traditional Japanese kimono standing in a cherry blossom garden, shallow depth of field, golden hour lighting", "aspect_ratio": "3:4", "quality": "4K", "num_images": 1, "temperature": 0.9, "seed": 12345 } ``` #### With Text in Image Nano Banana Pro renders text in images with high accuracy across multiple languages. ```json { "model": "vertex/nano-banana-pro", "prompt": "A clean coffee shop menu board with the text 'Espresso $3.50', 'Latte $4.50', 'Cappuccino $4.00' written in elegant chalk lettering on a dark background", "aspect_ratio": "3:4", "quality": "2K", "temperature": 0.8 } ``` #### With Reference Images (Character / Product Consistency) ```json { "model": "vertex/nano-banana-pro", "prompt": "Generate this character standing in a futuristic neon-lit city plaza at night. Keep exact face, hairstyle, and outfit from the references.", "reference_images": [ { "url": "https://your-cdn.com/character-front.jpg", "description": "Character front view — match face, hair color, and facial features exactly" }, { "url": "https://your-cdn.com/character-outfit.jpg", "description": "Character outfit — match the denim jacket, white t-shirt, and black jeans" } ], "quality": "2K", "aspect_ratio": "9:16", "temperature": 0.85 } ``` #### Parameters | Field | Type | Default | Options | Description | | ------------------ | ---------- | ------------ | ------------------------ | -------------------------------------------------------------------------------------------- | | `prompt` | `string` | **required** | max 4000 chars | Text description of the image | | `aspect_ratio` | `string` | `1:1` | See Aspect Ratio Support | Output dimensions | | `quality` | `string` | `2K` | `1K`, `2K`, `4K` | Output resolution. `4K` triggers higher billing rate | | `num_images` | `integer` | `1` | 1–10 | Variations per call | | `temperature` | `number` | `1.0` | 0–2 | Creativity. Lower = faithful, higher = creative | | `seed` | `integer` | — | any integer | Reproducibility | | `reference_images` | `object[]` | — | max 14 | Visual references for consistency. Each has `url` and optional `description` (max 500 chars) | | `celery` | `boolean` | `false` | — | `true` = async processing | *** ### Imagen 4 — `vertex/imagen-4` Powered by **Imagen 4.0**. Best for general-purpose generation with strict prompt adherence, multilingual support, and configurable safety controls. #### Minimal ```json { "model": "vertex/imagen-4", "prompt": "A hyperrealistic close-up of a dew-covered spider web at dawn, macro photography" } ``` #### Standard ```json { "model": "vertex/imagen-4", "prompt": "A sweeping landscape of the Scottish Highlands at golden hour, rolling heather-covered hills, dramatic storm clouds breaking, a lone castle in the distance", "aspect_ratio": "16:9", "num_images": 1, "image_size": "2K" } ``` #### With All Safety Controls ```json { "model": "vertex/imagen-4", "prompt": "A professional portrait of a businessperson in a modern office, natural window light, confident expression", "aspect_ratio": "3:4", "image_size": "2K", "num_images": 2, "output_compression_quality": 90, "person_generation": "allow_adult", "safety_filter_level": "block_medium_and_above", "enhance_prompt": false, "add_watermark": false } ``` *** ### Imagen 4 Fast — `vertex/imagen-4-fast` Powered by **Imagen 4.0 Fast**. Best for bulk generation, rapid prototyping, and cost-sensitive workloads. Fixed to approximately 1K resolution. #### Minimal ```json { "model": "vertex/imagen-4-fast", "prompt": "A vibrant flat illustration of a bicycle in a sunny park, digital art style" } ``` #### Standard ```json { "model": "vertex/imagen-4-fast", "prompt": "A simple icon of a shield with a checkmark, flat design, blue and white, clean vector style", "aspect_ratio": "1:1", "num_images": 4 } ``` #### Batch Generation ```json { "model": "vertex/imagen-4-fast", "prompt": "A colorful abstract geometric background pattern, modern gradient, suitable for mobile app splash screen", "aspect_ratio": "9:16", "num_images": 4, "celery": true } ``` *** ### Imagen 4 Ultra — `vertex/imagen-4-ultra` Powered by **Imagen 4.0 Ultra**. Best for the highest quality outputs, complex multi-element compositions, and strict instruction following. Use when quality is more important than speed or cost. #### Minimal ```json { "model": "vertex/imagen-4-ultra", "prompt": "A breathtakingly detailed oil painting of a medieval port city at twilight, torchlit cobblestone streets, galleons in harbor, figures in period clothing" } ``` #### Standard ```json { "model": "vertex/imagen-4-ultra", "prompt": "A hyperrealistic underwater scene: a coral reef ecosystem at depth, shafts of turquoise sunlight filtering through the surface, diverse marine life including clownfish, sea turtles, and manta rays, razor-sharp focus throughout the frame", "aspect_ratio": "16:9", "image_size": "2K", "num_images": 1 } ``` #### Maximum Quality ```json { "model": "vertex/imagen-4-ultra", "prompt": "A sweeping aerial panorama of the Dolomites in Italy at sunrise, snow-capped peaks glowing pink and orange, deep valleys in morning shadow, a winding mountain road visible far below, cinematic 8K quality", "aspect_ratio": "16:9", "image_size": "2K", "num_images": 1, "enhance_prompt": false, "add_watermark": false, "safety_filter_level": "block_medium_and_above" } ``` *** ### Aspect Ratio Support | Ratio | NB Flash | NB Pro | Imagen 4 / Fast / Ultra | | ------ | :------: | :----: | :---------------------: | | `1:1` | Yes | Yes | Yes | | `4:3` | Yes | Yes | Yes | | `3:4` | Yes | Yes | Yes | | `16:9` | Yes | Yes | Yes | | `9:16` | Yes | Yes | Yes | | `3:2` | Yes | Yes | — | | `2:3` | Yes | Yes | — | | `21:9` | Yes | Yes | — | | `1:4` | Yes | Yes | — | | `4:1` | Yes | Yes | — | | `5:4` | Yes | Yes | — | | `4:5` | Yes | Yes | — | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.qolaba.ai/api-platform/api-platform/image-generation/text-to-image.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.