usulpro
/
banatie-service
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
banatie-service/docs/api/image-generation.md

11 KiB
Raw Blame History

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

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

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:

Technical Aliases (Computed)

  • @last - Most recently generated image in project
  • @first - First generated image in project
  • @upload - Most recently uploaded image in project

Flow Aliases (Flow-scoped)

  • Stored in flow's aliases JSON field
  • Only accessible within flow context
  • Set via PUT /api/v1/flows/:id/aliases

Project Aliases (Global)

  • Unique within project
  • Accessible across all flows
  • Set via PUT /api/v1/images/:id/alias or generation parameters

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