437 lines
11 KiB
Markdown
437 lines
11 KiB
Markdown
# Banatie API - Image Generation (v1)
|
|
|
|
All endpoints require Project Key authentication via `X-API-Key` header and are rate-limited to 100 requests/hour.
|
|
|
|
---
|
|
|
|
## Generations
|
|
|
|
### POST /api/v1/generations
|
|
|
|
Create new image generation with optional reference images and flow support.
|
|
|
|
**Authentication:** Project Key required
|
|
|
|
**Parameters:**
|
|
- `prompt` - Text description for image (required)
|
|
- `referenceImages` - Array of image references (aliases or image IDs)
|
|
- `aspectRatio` - Image aspect ratio (e.g., "16:9", "1:1")
|
|
- `flowId` - Associate generation with a flow (UUID)
|
|
- `assignAlias` - Assign project-level alias to output image
|
|
- `assignFlowAlias` - Assign flow-level alias to output image
|
|
- `autoEnhance` - Enable prompt enhancement (boolean)
|
|
- `meta` - Custom metadata (JSON object)
|
|
|
|
**Purpose:** Generate AI images with reference support and automatic alias assignment
|
|
|
|
// TODO: change assignAlias to alias, assignFlowAlias to flowAlias
|
|
// TODO: response should include enhanced prompt if used
|
|
---
|
|
|
|
### GET /api/v1/generations
|
|
|
|
List generations with filtering and pagination.
|
|
|
|
**Authentication:** Project Key required
|
|
|
|
**Query Parameters:**
|
|
- `flowId` - Filter by flow (UUID)
|
|
- `status` - Filter by status (pending/processing/success/failed)
|
|
- `limit` - Results per page (default: 20, max: 100)
|
|
- `offset` - Pagination offset (default: 0)
|
|
- `includeDeleted` - Include soft-deleted records (boolean)
|
|
|
|
**Purpose:** Browse generation history with optional filters
|
|
|
|
---
|
|
|
|
### GET /api/v1/generations/:id
|
|
|
|
Get single generation with full details.
|
|
|
|
**Authentication:** Project Key required
|
|
|
|
**Parameters:**
|
|
- `id` - Generation UUID (path parameter)
|
|
|
|
**Purpose:** View complete generation details including output and reference images
|
|
|
|
---
|
|
|
|
### POST /api/v1/generations/:id/retry
|
|
|
|
Retry a failed generation.
|
|
// TODO: the main purpose of this to regenerate an image, e.g. refresh, or reflect some shared project settings like styles or aliases. It's not for generating failed generations. Not sure we need to allow alter prompt or aspectRatio. Now it return error: "Cannot retry a generation that already succeeded" - it's not a desired behavior
|
|
|
|
**Authentication:** Project Key required
|
|
|
|
**Parameters:**
|
|
- `id` - Generation UUID (path parameter)
|
|
- `prompt` - Override original prompt (optional)
|
|
- `aspectRatio` - Override aspect ratio (optional)
|
|
|
|
**Purpose:** Recreate a failed generation with optional parameter overrides
|
|
|
|
---
|
|
|
|
### DELETE /api/v1/generations/:id
|
|
|
|
Delete generation and its output image.
|
|
|
|
**Authentication:** Project Key required
|
|
|
|
**Parameters:**
|
|
- `id` - Generation UUID (path parameter)
|
|
|
|
**Purpose:** Remove generation record and associated output image (soft delete)
|
|
|
|
---
|
|
|
|
## Flows
|
|
|
|
Flows organize related generations into chains and support flow-scoped aliases.
|
|
|
|
### POST /api/v1/flows
|
|
|
|
Create new flow.
|
|
// TODO: each generation without flowId specified should start a new flow. We don't need a separate create flow endpoint
|
|
|
|
**Authentication:** Project Key required
|
|
|
|
**Parameters:**
|
|
- `meta` - Custom metadata (JSON object, optional)
|
|
|
|
**Purpose:** Initialize a new generation chain/workflow
|
|
|
|
---
|
|
|
|
### GET /api/v1/flows
|
|
|
|
List all flows with pagination.
|
|
|
|
**Authentication:** Project Key required
|
|
|
|
**Query Parameters:**
|
|
- `limit` - Results per page (default: 20, max: 100)
|
|
- `offset` - Pagination offset (default: 0)
|
|
|
|
**Purpose:** Browse all flows with computed generation and image counts
|
|
|
|
---
|
|
|
|
### GET /api/v1/flows/:id
|
|
|
|
Get single flow with details.
|
|
|
|
**Authentication:** Project Key required
|
|
|
|
**Parameters:**
|
|
- `id` - Flow UUID (path parameter)
|
|
|
|
**Purpose:** View flow metadata, aliases, and computed counts
|
|
|
|
---
|
|
|
|
### GET /api/v1/flows/:id/generations
|
|
|
|
List all generations in a flow.
|
|
|
|
**Authentication:** Project Key required
|
|
|
|
**Parameters:**
|
|
- `id` - Flow UUID (path parameter)
|
|
|
|
**Query Parameters:**
|
|
- `limit` - Results per page (default: 20, max: 100)
|
|
- `offset` - Pagination offset (default: 0)
|
|
|
|
**Purpose:** View all generations associated with this flow
|
|
|
|
---
|
|
|
|
### GET /api/v1/flows/:id/images
|
|
|
|
List all images in a flow.
|
|
|
|
**Authentication:** Project Key required
|
|
|
|
**Parameters:**
|
|
- `id` - Flow UUID (path parameter)
|
|
|
|
**Query Parameters:**
|
|
- `limit` - Results per page (default: 20, max: 100)
|
|
- `offset` - Pagination offset (default: 0)
|
|
|
|
**Purpose:** View all images (generated and uploaded) associated with this flow
|
|
|
|
---
|
|
|
|
### PUT /api/v1/flows/:id/aliases
|
|
|
|
Update flow aliases.
|
|
|
|
**Authentication:** Project Key required
|
|
|
|
**Parameters:**
|
|
- `id` - Flow UUID (path parameter)
|
|
- `aliases` - Object mapping alias names to image IDs (request body)
|
|
|
|
**Purpose:** Add or update flow-scoped aliases for image referencing
|
|
|
|
**Notes:**
|
|
- Merges with existing aliases
|
|
- Aliases must map to valid image IDs
|
|
|
|
---
|
|
|
|
### DELETE /api/v1/flows/:id/aliases/:alias
|
|
|
|
Remove specific flow alias.
|
|
|
|
**Authentication:** Project Key required
|
|
|
|
**Parameters:**
|
|
- `id` - Flow UUID (path parameter)
|
|
- `alias` - Alias name to remove (path parameter)
|
|
|
|
**Purpose:** Delete a single alias from flow's alias map
|
|
|
|
---
|
|
|
|
### DELETE /api/v1/flows/:id
|
|
|
|
Delete flow.
|
|
|
|
**Authentication:** Project Key required
|
|
|
|
**Parameters:**
|
|
- `id` - Flow UUID (path parameter)
|
|
|
|
**Purpose:** Remove flow (hard delete, generations and images remain)
|
|
|
|
---
|
|
|
|
## Images
|
|
|
|
Database-tracked image management with upload, listing, and metadata updates.
|
|
|
|
### POST /api/v1/images/upload
|
|
|
|
Upload image file with database tracking.
|
|
|
|
**Authentication:** Project Key required
|
|
|
|
**Form Parameters:**
|
|
- `file` - Image file (required, max 5MB, PNG/JPEG/WebP)
|
|
- `alias` - Project-level alias (optional)
|
|
- `flowId` - Associate with flow (UUID, optional)
|
|
- `meta` - Custom metadata (JSON object, optional)
|
|
|
|
**Purpose:** Upload image with automatic database record creation and storage
|
|
|
|
**Notes:**
|
|
- Creates both MinIO storage file and database entry
|
|
- Supports PNG, JPEG, JPG, WebP formats
|
|
- Maximum file size: 5MB
|
|
|
|
// TODO: need to add flowAlias param
|
|
---
|
|
|
|
### GET /api/v1/images
|
|
|
|
List images with filtering and pagination.
|
|
|
|
**Authentication:** Project Key required
|
|
|
|
**Query Parameters:**
|
|
- `flowId` - Filter by flow (UUID)
|
|
- `source` - Filter by source (generated/uploaded)
|
|
- `alias` - Filter by project alias
|
|
- `limit` - Results per page (default: 20, max: 100)
|
|
- `offset` - Pagination offset (default: 0)
|
|
- `includeDeleted` - Include soft-deleted records (boolean)
|
|
|
|
**Purpose:** Browse image library with optional filters
|
|
|
|
---
|
|
|
|
### GET /api/v1/images/resolve/:alias
|
|
|
|
Resolve alias to image using 3-tier precedence.
|
|
|
|
**Authentication:** Project Key required
|
|
|
|
**Parameters:**
|
|
- `alias` - Alias to resolve (path parameter)
|
|
|
|
**Query Parameters:**
|
|
- `flowId` - Flow context for resolution (UUID, optional)
|
|
|
|
**Purpose:** Lookup image by alias with technical → flow → project precedence
|
|
|
|
**Notes:**
|
|
- Technical aliases: @last, @first, @upload (computed)
|
|
- Flow aliases: Scoped to specific flow
|
|
- Project aliases: Global within project
|
|
- Returns image record and resolution metadata (scope, flowId)
|
|
|
|
---
|
|
|
|
### GET /api/v1/images/:id
|
|
|
|
Get single image by ID.
|
|
|
|
**Authentication:** Project Key required
|
|
|
|
**Parameters:**
|
|
- `id` - Image UUID (path parameter)
|
|
|
|
**Purpose:** View complete image metadata and details
|
|
|
|
---
|
|
|
|
### PUT /api/v1/images/:id
|
|
|
|
Update image metadata.
|
|
|
|
**Authentication:** Project Key required
|
|
|
|
**Parameters:**
|
|
- `id` - Image UUID (path parameter)
|
|
- `alias` - Update project alias (optional)
|
|
- `focalPoint` - Update focal point coordinates (object: {x, y}, optional)
|
|
- `meta` - Update custom metadata (JSON object, optional)
|
|
|
|
**Purpose:** Modify image metadata fields
|
|
|
|
// TODO: should be a way to remove alias from an image
|
|
---
|
|
|
|
### PUT /api/v1/images/:id/alias
|
|
|
|
Assign or update project-scoped alias.
|
|
|
|
**Authentication:** Project Key required
|
|
|
|
**Parameters:**
|
|
- `id` - Image UUID (path parameter)
|
|
- `alias` - Alias name (string, required in request body)
|
|
|
|
**Purpose:** Set project-level alias for image referencing
|
|
|
|
**Notes:**
|
|
- Validates alias format and reserved names
|
|
- Checks for conflicts with existing aliases
|
|
|
|
// TODO: why we need this if we can do it with `PUT /api/v1/images/:id`?
|
|
---
|
|
|
|
### DELETE /api/v1/images/:id
|
|
|
|
Soft delete image.
|
|
|
|
**Authentication:** Project Key required
|
|
|
|
**Parameters:**
|
|
- `id` - Image UUID (path parameter)
|
|
|
|
**Purpose:** Mark image as deleted without removing from storage
|
|
|
|
**Notes:**
|
|
- Sets deletedAt timestamp
|
|
- Image remains in storage
|
|
- Excluded from default queries
|
|
|
|
// TODO: why "soft" delete? did we discuss "soft" way and how to actually delete the image then?
|
|
---
|
|
|
|
## Live Generation
|
|
|
|
### GET /api/v1/live
|
|
|
|
Generate image with prompt-based caching.
|
|
|
|
**Authentication:** Project Key required
|
|
|
|
**Query Parameters:**
|
|
- `prompt` - Text description for image (required)
|
|
- `aspectRatio` - Image aspect ratio (optional)
|
|
|
|
**Purpose:** Generate images with intelligent caching based on prompt hash
|
|
|
|
**Response Format:** Raw image bytes (not JSON)
|
|
|
|
**Response Headers:**
|
|
- `Content-Type` - image/jpeg (or appropriate MIME type)
|
|
- `X-Cache-Status` - HIT or MISS
|
|
- `X-Image-Id` - Image database UUID
|
|
- `X-Generation-Id` - Generation UUID (on cache MISS)
|
|
- `X-Cache-Hit-Count` - Number of cache hits (on cache HIT)
|
|
- `Cache-Control` - public, max-age=31536000
|
|
|
|
**Caching Behavior:**
|
|
- **Cache HIT:** Returns existing cached image from storage
|
|
- **Cache MISS:** Generates new image, caches it, returns bytes
|
|
- Cache key: SHA-256 hash of prompt
|
|
- Cache lookup scoped to project
|
|
|
|
// TODO: we can't pass apikey in query param because it's assumed those images are public available on the generated pages. So we need another way to protect this endpoint and also to protect clients from using their credits
|
|
---
|
|
|
|
## Alias System
|
|
|
|
The v1 API supports a 3-tier alias resolution system for referencing images.
|
|
|
|
**Alias Format Requirements:**
|
|
- All aliases MUST start with `@` symbol
|
|
- Pattern: `@[a-zA-Z0-9_-]+` (alphanumeric, underscore, hyphen)
|
|
- Maximum length: 50 characters
|
|
- Examples: `@hero`, `@product-main`, `@image_1`
|
|
|
|
**Technical Aliases** (Computed, Reserved)
|
|
- `@last` - Most recently generated image in project
|
|
- `@first` - First generated image in project
|
|
- `@upload` - Most recently uploaded image in project
|
|
|
|
**Reserved Aliases** (Cannot be used)
|
|
- Technical aliases: `@last`, `@first`, `@upload`
|
|
- Future reserved: `@all`, `@latest`, `@oldest`, `@random`, `@next`, `@prev`, `@previous`
|
|
|
|
**Flow Aliases** (Flow-scoped)
|
|
- Stored in flow's aliases JSON field
|
|
- Only accessible within flow context
|
|
- Set via `PUT /api/v1/flows/:id/aliases`
|
|
- Example: `@hero` in flow A is different from `@hero` in flow B
|
|
|
|
**Project Aliases** (Global)
|
|
- Unique within project
|
|
- Accessible across all flows
|
|
- Set via `PUT /api/v1/images/:id/alias` or generation parameters
|
|
- Example: `@logo` is the same image across entire project
|
|
|
|
**Resolution Order:**
|
|
1. Technical aliases (if matches @last, @first, @upload)
|
|
2. Flow aliases (if flowId provided in context)
|
|
3. Project aliases (global lookup)
|
|
|
|
---
|
|
|
|
## Error Codes
|
|
|
|
| Code | Description |
|
|
|------|-------------|
|
|
| 400 | Bad Request - Invalid parameters or validation failure |
|
|
| 401 | Unauthorized - Missing, invalid, expired, or revoked API key |
|
|
| 404 | Not Found - Resource does not exist |
|
|
| 429 | Too Many Requests - Rate limit exceeded |
|
|
| 500 | Internal Server Error - Processing or generation failure |
|
|
|
|
**Common Error Messages:**
|
|
- `"Prompt is required"` - Missing prompt parameter
|
|
- `"Flow not found"` - Invalid flowId
|
|
- `"Image not found"` - Invalid image ID or alias
|
|
- `"Alias already exists"` - Alias conflict in project
|
|
- `"Invalid aspect ratio"` - Unsupported aspect ratio format
|
|
- `"File too large"` - Upload exceeds 5MB limit
|
|
- `"alias_format_check"` - Alias must start with @ symbol (e.g., @hero not hero)
|