/packages/docs/cloud/image-generation.mdx

---
title: Image Generation
description: Generate images with AI on elizaOS Cloud using the configured image model catalog.
---

# Image Generation

Generate high-quality images from text prompts using state-of-the-art AI models.

## Overview

elizaOS Cloud provides image generation through the configured image provider
catalog. See the [Images API reference](/cloud/api/images) or API Explorer for
current models and defaults.

## Quick Start

### Dashboard

Navigate to [Dashboard → Images](https://elizacloud.ai/dashboard/image) for the visual interface.

### API

<Tabs>
  <Tab title="cURL">

```bash
curl -X POST "https://elizacloud.ai/api/v1/generate-image" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A futuristic cityscape at sunset, cyberpunk style",
    "model": "google/nano-banana-2/text-to-image",
    "aspectRatio": "16:9",
    "numImages": 1
  }'
```
  </Tab>
  <Tab title="JavaScript">

```javascript
const response = await fetch('https://elizacloud.ai/api/v1/generate-image', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    prompt: 'A futuristic cityscape at sunset, cyberpunk style',
    model: 'google/nano-banana-2/text-to-image',
    aspectRatio: '16:9',
    numImages: 1,
  }),
});

const result = await response.json();
console.log(result.images[0].url);

```
  </Tab>
  <Tab title="Python">

```python
import requests

response = requests.post(
    'https://elizacloud.ai/api/v1/generate-image',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'prompt': 'A futuristic cityscape at sunset, cyberpunk style',
        'model': 'google/nano-banana-2/text-to-image',
        'aspectRatio': '16:9',
        'numImages': 1,
    },
)

result = response.json()
print(result['images'][0]['url'])
```
  </Tab>
</Tabs>

### Response

```json
{
  "images": [
    {
      "url": "https://your-storage.vercel-storage.com/images/abc123.webp",
      "text": "Optional model response text",
      "mimeType": "image/webp",
      "fileSize": 102400
    }
  ],
  "numImages": 1
}
```

## Available Models

Model availability and defaults are documented in the canonical
[Images API reference](/cloud/api/images). Use that page or the API Explorer for
the current model catalog and pricing-sensitive defaults.

## Request Parameters

| Parameter       | Type    | Required | Description                                               |
| --------------- | ------- | -------- | --------------------------------------------------------- |
| `prompt`      | string  | ✓        | Text description of the image                             |
| `model`       | string  |          | Model to use (default: `google/nano-banana-2/text-to-image`) |
| `aspectRatio` | string  |          | Output aspect ratio (default: `1:1`)                    |
| `numImages`   | integer |          | Number of images (1-4, default: 1)                        |
| `stylePreset` | string  |          | Style preset to apply                                     |
| `sourceImage` | string  |          | Base64 data URL for image-to-image                        |

### Available Aspect Ratios

| Aspect Ratio | Description          |
| ------------ | -------------------- |
| `1:1`      | Square (default)     |
| `16:9`     | Wide landscape       |
| `9:16`     | Tall portrait        |
| `4:3`      | Standard landscape   |
| `3:4`      | Standard portrait    |
| `21:9`     | Ultra-wide cinematic |
| `9:21`     | Ultra-tall vertical  |

### Style Presets

| Preset           | Description                       |
| ---------------- | --------------------------------- |
| `none`         | No style modification (default)   |
| `photographic` | Realistic lighting and details    |
| `digital-art`  | Vibrant colors, modern aesthetics |
| `comic-book`   | Bold lines, dramatic shading      |
| `fantasy-art`  | Magical and ethereal elements     |
| `analog-film`  | Film grain and vintage tones      |
| `neon-punk`    | Cyberpunk style with neon colors  |
| `cinematic`    | Dramatic lighting and composition |

## Image-to-Image Generation

Transform existing images by providing a `sourceImage` parameter:

```javascript
const response = await fetch("https://elizacloud.ai/api/v1/generate-image", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    prompt: "Transform this into a watercolor painting",
    sourceImage: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  }),
});
```

## Prompt Engineering

### Basic Structure

```
[Subject] [Style] [Details] [Lighting] [Mood]
```

### Example Prompts

**Photorealistic:**

```json
{
  "prompt": "Professional headshot of a business executive, studio lighting, neutral background, sharp focus",
  "stylePreset": "photographic"
}
```

**Artistic:**

```json
{
  "prompt": "Enchanted forest with glowing mushrooms, magical atmosphere, soft moonlight filtering through trees",
  "stylePreset": "fantasy-art"
}
```

**Product:**

```json
{
  "prompt": "Modern smartphone on white background, professional product photography, soft shadows",
  "aspectRatio": "4:3"
}
```

## Best Practices

- **Be specific**: Include details about style, lighting, composition
- **Use style presets**: For consistent results across generations
- **Iterate**: Generate multiple images and refine your prompt
- **Aspect ratio matters**: Choose based on your use case

## Error Handling

| Code | Error                | Solution                       |
| ---- | -------------------- | ------------------------------ |
| 400  | Invalid prompt       | Ensure prompt is non-empty     |
| 400  | Invalid model        | Use a supported model          |
| 402  | Insufficient credits | Add credits to your account    |
| 429  | Rate limited         | Wait and retry                 |
| 500  | Generation failed    | Retry or try a different model |

## Next Steps

<CardGroup>
  <CardGroup.Card title="API Reference" href="/cloud/api/images">
    Complete API documentation
  </CardGroup.Card>
  <CardGroup.Card title="Gallery" href="/cloud/gallery">
    View and manage your images
  </CardGroup.Card>
  <CardGroup.Card title="Video Generation" href="/cloud/video-generation">
    Generate videos from text
  </CardGroup.Card>
</CardGroup>