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

***

### 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  |            —            |