> 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/image-generation/text-to-image.md).

# Text-to-Image

Generate images from text prompts using Nano Banana and Imagen 4 models, with support forsearch grounding, text rendering, reference images, and configurable safety controls.

### Available Models

| Model ID                   | Name              | Engine           | Speed    | Max Resolution | Max Output Images | Key Capability                        |
| -------------------------- | ----------------- | ---------------- | -------- | -------------- | ----------------- | ------------------------------------- |
| `vertex/nano-banana-flash` | Nano Banana Flash | 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 and 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

**Model ID:** `vertex/nano-banana-flash`  |  **Engine:** Gemini Flash

Optimized for fast generation, search-grounded accuracy, and high-volume workflows.

#### Minimal Request

```json
{
  "model": "vertex/nano-banana-flash",
  "prompt": "A cozy Japanese ramen shop on a rainy night, steam rising from bowls, warm ambient lighting"
}
```

#### With Parameters

```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
}
```

#### Search Grounding

Set `use_search_grounding: true` to incorporate real-time Google Search context. This improves factual and visual accuracy for real-world subjects such as architecture, landmarks, and products.

```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
}
```

#### Batch Variations

Generate multiple variations of a single prompt by setting `num_images` (up to 10). Increase `temperature` above 1.0 for greater variation between outputs.

```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
}
```

### Nano Banana Pro

**Model ID:** `vertex/nano-banana-pro`  |  **Engine:** Gemini Pro

Optimized for production-quality output, multi-language text rendering in images, 4K resolution, and consistent character or product depiction across multiple requests.

#### Minimal Request

```json
{
  "model": "vertex/nano-banana-pro",
  "prompt": "A luxury watch on a black marble surface, dramatic spotlight lighting, product photography"
}
```

#### With Parameters

```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
}
```

#### Text Rendering

Nano Banana Pro renders text within generated 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
}
```

#### Reference Images

Pass reference images for character or product consistency across multiple outputs. Each reference includes a `url` and a `description` guiding the model on what to match.

```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
}
```

### Imagen 4

**Model ID:** `vertex/imagen-4`  |  **Engine:** Imagen 4.0

General-purpose generation with high prompt adherence, multilingual support, and configurable safety filtering and person-generation policies.

#### Minimal Request

```json
{
  "model": "vertex/imagen-4",
  "prompt": "A hyperrealistic close-up of a dew-covered spider web at dawn, macro photography"
}
```

#### With Parameters

```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"
}
```

#### Safety Controls

Imagen models support fine-grained content policies via `person_generation` and `safety_filter_level`.

```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

**Model ID:** `vertex/imagen-4-fast`  |  **Engine:** Imagen 4.0 Fast

Optimized for bulk generation, rapid prototyping, and cost-sensitive workloads. Output is fixed at approximately 1K resolution.

#### Minimal Request

```json
{
  "model": "vertex/imagen-4-fast",
  "prompt": "A vibrant flat illustration of a bicycle in a sunny park, digital art style"
}
```

#### With Parameters

```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
}
```

#### Async Mode

Set `mode: "async"` to return a `task_id` immediately instead of waiting for generation to complete. Poll `GET /tasks/{task_id}` for results.

```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,
  "mode": "async"
}
```

### Imagen 4 Ultra

**Model ID:** `vertex/imagen-4-ultra`  |  **Engine:** Imagen 4.0 Ultra

Highest quality output with high prompt adherence for complex multi-element compositions. Slower and higher cost than other Imagen 4 variants.

#### Minimal Request

```json
{
  "model": "vertex/imagen-4-ultra",
  "prompt": "A detailed oil painting of a medieval port city at twilight, torchlit cobblestone streets, galleons in harbor, figures in period clothing"
}
```

#### With Parameters

```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",
  "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",
  "aspect_ratio": "16:9",
  "image_size": "2K",
  "num_images": 1,
  "enhance_prompt": false,
  "add_watermark": false,
  "safety_filter_level": "block_medium_and_above"
}
```

### Supported Aspect Ratios

| Ratio  | Nano Banana Flash | Nano Banana 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       |            —            |
|        |                   |                 |                         |