> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verlon.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Images

> Generate images from text prompts with multiple providers

The `image()` method generates images from text descriptions using AI models like DALL-E, Stable Diffusion, and Flux.

## Basic Image Generation

```typescript theme={null}
const response = await verlon.image({
  gateId: 'your-gate-id',
  data: {
    prompt: 'A serene mountain landscape at sunset with vibrant colors'
  }
});

console.log(response.images[0].url);
console.log('Cost:', response.cost);
```

## Image Sizes

Different models support different sizes:

```typescript theme={null}
const response = await verlon.image({
  gateId: 'your-gate-id',
  data: {
    prompt: 'A futuristic city skyline',
    size: '1024x1024'  // or '1792x1024', '1024x1792'
  }
});
```

### Supported Sizes

| Size        | Aspect Ratio | Use Case             |
| ----------- | ------------ | -------------------- |
| `256x256`   | 1:1          | Quick previews       |
| `512x512`   | 1:1          | Standard square      |
| `1024x1024` | 1:1          | High-quality square  |
| `1792x1024` | 16:9         | Landscape/widescreen |
| `1024x1792` | 9:16         | Portrait/vertical    |
| `1536x1024` | 3:2          | Landscape            |
| `1024x1536` | 2:3          | Portrait             |

<Tip>
  Choose portrait orientation (`1024x1792`) for mobile wallpapers, and landscape (`1792x1024`) for desktop backgrounds.
</Tip>

## Image Quality

Control generation quality (DALL-E 3 only):

```typescript theme={null}
const response = await verlon.image({
  gateId: 'your-gate-id',
  data: {
    prompt: 'A photorealistic portrait of a golden retriever',
    quality: 'hd'  // 'standard' or 'hd'
  }
});
```

### Quality Comparison

| Quality    | Description       | Cost   | Use Case             |
| ---------- | ----------------- | ------ | -------------------- |
| `standard` | Faster generation | Lower  | Drafts, iterations   |
| `hd`       | More details      | Higher | Final images, prints |

## Image Style

Set the style for DALL-E 3:

```typescript theme={null}
const response = await verlon.image({
  gateId: 'your-gate-id',
  data: {
    prompt: 'A dragon flying over a castle',
    style: 'vivid'  // 'vivid' or 'natural'
  }
});
```

### Style Options

| Style     | Appearance                              |
| --------- | --------------------------------------- |
| `vivid`   | Hyper-real, dramatic colors and details |
| `natural` | More subtle, realistic tones            |

## Multiple Images

Generate multiple variations:

```typescript theme={null}
const response = await verlon.image({
  gateId: 'your-gate-id',
  data: {
    prompt: 'A cozy coffee shop interior',
    count: 4  // Generate 4 images
  }
});

// Access all images
response.images.forEach((img, i) => {
  console.log(`Image ${i + 1}:`, img.url);
});
```

<Warning>
  Generating multiple images multiplies the cost. 4 images = 4x the price of a single image.
</Warning>

## Deterministic Generation

Use seeds for reproducible results:

```typescript theme={null}
const response = await verlon.image({
  gateId: 'your-gate-id',
  data: {
    prompt: 'An abstract geometric pattern',
    seed: 42  // Same seed + prompt = same image
  }
});
```

## Parameters

### Request Parameters

| Parameter | Type                   | Default       | Description                   |
| --------- | ---------------------- | ------------- | ----------------------------- |
| `prompt`  | `string`               | Required      | Image description             |
| `size`    | `string`               | Model default | Image dimensions              |
| `quality` | `'standard' \| 'hd'`   | `standard`    | Generation quality (DALL-E 3) |
| `count`   | `number`               | 1             | Number of images to generate  |
| `style`   | `'vivid' \| 'natural'` | `vivid`       | Image style (DALL-E 3)        |
| `seed`    | `number`               | Random        | Seed for reproducibility      |

## Response

```typescript theme={null}
interface ImageResponse {
  id: string;                    // Request ID
  model: string;                 // Model used
  images: ImageOutput[];         // Generated images
  cost: number;                  // Request cost in USD
  latency: number;               // Response time in ms
}

interface ImageOutput {
  url?: string;                  // Hosted image URL
  base64?: string;               // Base64-encoded image data
  revisedPrompt?: string;        // AI-revised prompt (DALL-E)
}
```

### Revised Prompts

DALL-E may revise your prompt for safety or clarity:

```typescript theme={null}
const response = await verlon.image({
  gateId: 'your-gate-id',
  data: {
    prompt: 'A dog'
  }
});

console.log('Your prompt:', 'A dog');
console.log('Revised:', response.images[0].revisedPrompt);
// "A friendly golden retriever sitting in a grassy park on a sunny day"
```

## Best Practices

### 1. Write Descriptive Prompts

```typescript theme={null}
// Good ✅ - Specific and detailed
{
  prompt: 'A Victorian-era library with floor-to-ceiling bookshelves, leather armchairs, warm lighting from a fireplace, and a large oak desk with an open book'
}

// Less effective - Too vague
{
  prompt: 'A library'
}
```

### 2. Specify Style and Mood

```typescript theme={null}
// Good ✅ - Clear artistic direction
{
  prompt: 'A cyberpunk street market at night, neon lights reflecting on wet pavement, manga style, high contrast'
}

// Less effective - Missing artistic details
{
  prompt: 'A street market'
}
```

### 3. Use Appropriate Sizes

```typescript theme={null}
// Good ✅ - Right size for use case
{
  prompt: 'Social media profile picture',
  size: '1024x1024'  // Square for avatars
}

// Good ✅ - Right size for use case
{
  prompt: 'Website hero banner',
  size: '1792x1024'  // Landscape for banners
}
```

### 4. Always Handle Errors

```typescript theme={null}
try {
  const response = await verlon.image({
    gateId: 'your-gate-id',
    data: {
      prompt: 'A sunset over the ocean'
    }
  });

  return response.images[0].url;
} catch (error) {
  console.error('Image generation failed:', error);
  return null;
}
```

### 5. Monitor Costs

```typescript theme={null}
const response = await verlon.image({
  gateId: 'your-gate-id',
  data: {
    prompt: 'A landscape',
    count: 3,
    quality: 'hd'
  }
});

console.log(`Generated ${response.images.length} images`);
console.log(`Total cost: $${response.cost.toFixed(4)}`);
console.log(`Per image: $${(response.cost / response.images.length).toFixed(4)}`);
```

## Examples

### Product Visualization

```typescript theme={null}
const response = await verlon.image({
  gateId: 'your-gate-id',
  metadata: { feature: 'product-viz' },
  data: {
    prompt: 'A modern minimalist water bottle, matte black finish, on a marble countertop with soft natural lighting',
    size: '1024x1024',
    quality: 'hd',
    style: 'natural'
  }
});
```

### Social Media Graphics

```typescript theme={null}
const response = await verlon.image({
  gateId: 'your-gate-id',
  data: {
    prompt: 'Bold typographic design with the text "Summer Sale" in vibrant gradient colors, tropical theme, Instagram post style',
    size: '1024x1024',
    style: 'vivid'
  }
});
```

### Concept Art

```typescript theme={null}
const response = await verlon.image({
  gateId: 'your-gate-id',
  data: {
    prompt: 'Sci-fi spaceship interior, command bridge with holographic displays, captain's chair in center, large viewport showing a nebula, cinematic lighting',
    size: '1792x1024',
    quality: 'hd',
    count: 3  // Generate multiple variations
  }
});

// Pick the best one
response.images.forEach((img, i) => {
  console.log(`Variation ${i + 1}:`, img.url);
});
```

### Background Images

```typescript theme={null}
const response = await verlon.image({
  gateId: 'your-gate-id',
  data: {
    prompt: 'Abstract gradient background, soft pastel colors (pink, purple, blue), smooth texture, suitable for presentation slides',
    size: '1792x1024'
  }
});
```

### Architecture Visualization

```typescript theme={null}
const response = await verlon.image({
  gateId: 'your-gate-id',
  data: {
    prompt: 'Modern sustainable house design, large windows, solar panels, surrounded by native plants, architectural rendering style',
    size: '1792x1024',
    quality: 'hd',
    style: 'natural'
  }
});
```

## Advanced Usage

### Batch Generation

Generate multiple different images:

```typescript theme={null}
const prompts = [
  'A forest in spring',
  'A forest in summer',
  'A forest in autumn',
  'A forest in winter'
];

const images = await Promise.all(
  prompts.map(prompt =>
    verlon.image({
      gateId: 'your-gate-id',
      data: { prompt, size: '1024x1024' }
    })
  )
);

images.forEach((response, i) => {
  console.log(prompts[i], '->', response.images[0].url);
});
```

### Override Model

Use a specific image model:

```typescript theme={null}
const response = await verlon.image({
  gateId: 'your-gate-id',
  model: 'dall-e-3',  // Force DALL-E 3
  data: {
    prompt: 'A futuristic city'
  }
});
```

### Custom Metadata

Track image generation:

```typescript theme={null}
const response = await verlon.image({
  gateId: 'your-gate-id',
  metadata: {
    userId: 'user-123',
    campaign: 'summer-2024',
    purpose: 'ad-creative'
  },
  data: {
    prompt: 'Beach vacation scene with palm trees'
  }
});
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Video" icon="video" href="/sdk-reference/video">
    Generate videos from text
  </Card>

  <Card title="Chat" icon="comments" href="/sdk-reference/chat">
    Analyze images with vision models
  </Card>

  <Card title="Gates & Routing" icon="route" href="/concepts/gates-and-routing">
    How Verlon routes image requests
  </Card>

  <Card title="Cost Tracking" icon="chart-line" href="/concepts/cost-tracking">
    Monitor image generation costs
  </Card>
</CardGroup>