344 lines
8.7 KiB
Markdown
344 lines
8.7 KiB
Markdown
# 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
|