# Image Generation API

Basic image generation using AI. For advanced features like references, aliases, and flows, see [image-generation-advanced.md](image-generation-advanced.md).

All endpoints require Project Key authentication via `X-API-Key` header.

---

## Create Generation

```
POST /api/v1/generations
```

Generate an AI image from a text prompt.

**Request Body:**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | Yes | - | Text description of the image to generate |
| `aspectRatio` | string | No | `"1:1"` | Image aspect ratio |
| `autoEnhance` | boolean | No | `true` | Enable AI prompt enhancement |
| `enhancementOptions` | object | No | - | Enhancement configuration |
| `enhancementOptions.template` | string | No | `"general"` | Enhancement template |
| `meta` | object | No | `{}` | Custom metadata |

**Example Request:**

```json
{
  "prompt": "a red sports car on a mountain road",
  "aspectRatio": "16:9",
  "autoEnhance": true,
  "enhancementOptions": {
    "template": "photorealistic"
  }
}
```

**Response:** `201 Created`

```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "projectId": "57c7f7f4-47de-4d70-9ebd-3807a0b63746",
    "prompt": "A photorealistic establishing shot of a sleek red sports car...",
    "originalPrompt": "a red sports car on a mountain road",
    "autoEnhance": true,
    "aspectRatio": "16:9",
    "status": "pending",
    "outputImageId": null,
    "processingTimeMs": null,
    "createdAt": "2025-11-28T10:00:00.000Z",
    "updatedAt": "2025-11-28T10:00:00.000Z"
  }
}
```

---

## Aspect Ratios

Supported aspect ratios for image generation:

| Aspect Ratio | Use Case |
|--------------|----------|
| `1:1` | Square images, social media posts, profile pictures |
| `16:9` | Landscape, hero banners, video thumbnails |
| `9:16` | Portrait, mobile screens, stories |
| `3:2` | Photography standard, print |
| `21:9` | Ultra-wide banners, cinematic |

---

## Prompt Enhancement

By default, prompts are automatically enhanced by AI to produce better results.

### How It Works

When `autoEnhance: true` (default):
- Your original prompt is preserved in `originalPrompt`
- AI enhances it with style details, lighting, composition
- The enhanced version is stored in `prompt` and used for generation

When `autoEnhance: false`:
- Both `prompt` and `originalPrompt` contain your original text
- No AI enhancement is applied

### Enhancement Templates

Use `enhancementOptions.template` to guide the enhancement style:

| Template | Description | Best For |
|----------|-------------|----------|
| `general` | Balanced enhancement (default) | Most use cases |
| `photorealistic` | Photography terms, lighting, camera details | Realistic photos |
| `illustration` | Art style, composition, color palette | Artwork, drawings |
| `minimalist` | Clean, simple, essential elements | Logos, icons |
| `sticker` | Bold outlines, limited colors, vector style | Stickers, emojis |
| `product` | Studio lighting, materials, lifestyle context | E-commerce |
| `comic` | Action lines, expressions, panel composition | Comics, manga |

### Example: With Enhancement

```json
// Request
{
  "prompt": "a cat",
  "autoEnhance": true,
  "enhancementOptions": { "template": "photorealistic" }
}

// Response
{
  "prompt": "A photorealistic close-up portrait of a domestic cat with soft fur, captured with an 85mm lens at f/1.8, natural window lighting creating soft shadows, detailed whiskers and expressive eyes, shallow depth of field with creamy bokeh background",
  "originalPrompt": "a cat",
  "autoEnhance": true
}
```

### Example: Without Enhancement

```json
// Request
{
  "prompt": "a cat sitting on a windowsill",
  "autoEnhance": false
}

// Response
{
  "prompt": "a cat sitting on a windowsill",
  "originalPrompt": "a cat sitting on a windowsill",
  "autoEnhance": false
}
```

---

## Generation Status

Generations go through these status stages:

| Status | Description |
|--------|-------------|
| `pending` | Generation created, waiting to start |
| `processing` | AI is generating the image |
| `success` | Image generated successfully |
| `failed` | Generation failed (see `errorMessage`) |

Poll the generation endpoint to check status:

```
GET /api/v1/generations/:id
```

When `status: "success"`, the `outputImageId` field contains the generated image ID.

---

## List Generations

```
GET /api/v1/generations
```

List all generations with optional filters.

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `status` | string | - | Filter by status: `pending`, `processing`, `success`, `failed` |
| `limit` | number | `20` | Results per page (max: 100) |
| `offset` | number | `0` | Pagination offset |
| `includeDeleted` | boolean | `false` | Include soft-deleted records |

**Example:**

```
GET /api/v1/generations?status=success&limit=10
```

**Response:**

```json
{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "prompt": "A photorealistic establishing shot...",
      "originalPrompt": "a red sports car",
      "autoEnhance": true,
      "aspectRatio": "16:9",
      "status": "success",
      "outputImageId": "7c4ccf47-41ce-4718-afbc-8c553b2c631a",
      "processingTimeMs": 8500,
      "createdAt": "2025-11-28T10:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 42,
    "hasMore": true
  }
}
```

---

## Get Generation

```
GET /api/v1/generations/:id
```

Get a single generation with full details.

**Response:**

```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "projectId": "57c7f7f4-47de-4d70-9ebd-3807a0b63746",
    "prompt": "A photorealistic establishing shot of a sleek red sports car...",
    "originalPrompt": "a red sports car on a mountain road",
    "autoEnhance": true,
    "aspectRatio": "16:9",
    "status": "success",
    "outputImageId": "7c4ccf47-41ce-4718-afbc-8c553b2c631a",
    "outputImage": {
      "id": "7c4ccf47-41ce-4718-afbc-8c553b2c631a",
      "storageUrl": "http://localhost:9000/banatie/default/project-id/generated/image.png",
      "mimeType": "image/png",
      "width": 1792,
      "height": 1024,
      "fileSize": 1909246
    },
    "processingTimeMs": 8500,
    "retryCount": 0,
    "errorMessage": null,
    "meta": {},
    "createdAt": "2025-11-28T10:00:00.000Z",
    "updatedAt": "2025-11-28T10:00:08.500Z"
  }
}
```

---

## Delete Generation

```
DELETE /api/v1/generations/:id
```

Delete a generation and its output image.

**Response:** `200 OK`

```json
{
  "success": true,
  "message": "Generation deleted"
}
```

**Behavior:**
- Generation record is hard deleted
- Output image is hard deleted (unless it has a project alias)

---

## Response Fields

### Generation Response

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Generation UUID |
| `projectId` | string | Project UUID |
| `prompt` | string | Prompt used for generation (enhanced if applicable) |
| `originalPrompt` | string | Original user input |
| `autoEnhance` | boolean | Whether enhancement was applied |
| `aspectRatio` | string | Image aspect ratio |
| `status` | string | Generation status |
| `outputImageId` | string | Output image UUID (when successful) |
| `outputImage` | object | Output image details (when successful) |
| `processingTimeMs` | number | Generation time in milliseconds |
| `retryCount` | number | Number of retry attempts |
| `errorMessage` | string | Error details (when failed) |
| `meta` | object | Custom metadata |
| `createdAt` | string | ISO timestamp |
| `updatedAt` | string | ISO timestamp |

### Output Image

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Image UUID |
| `storageUrl` | string | Direct URL to image file |
| `mimeType` | string | Image MIME type |
| `width` | number | Image width in pixels |
| `height` | number | Image height in pixels |
| `fileSize` | number | File size in bytes |

---

## Error Codes

| HTTP Status | Code | Description |
|-------------|------|-------------|
| 400 | `VALIDATION_ERROR` | Invalid parameters |
| 401 | `UNAUTHORIZED` | Missing or invalid API key |
| 404 | `GENERATION_NOT_FOUND` | Generation does not exist |
| 429 | `RATE_LIMIT_EXCEEDED` | Too many requests |
| 500 | `GENERATION_FAILED` | AI generation failed |

---

## Rate Limits

- **100 requests per hour** per API key
- Rate limit headers included in response:
  - `X-RateLimit-Limit`: Maximum requests
  - `X-RateLimit-Remaining`: Remaining requests
  - `X-RateLimit-Reset`: Seconds until reset

---

## See Also

- [Advanced Generation](image-generation-advanced.md) - References, aliases, flows
- [Image Upload](images-upload.md) - Upload and manage images
- [Live URLs](live-url.md) - CDN and live generation