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

8.7 KiB
Raw Blame History

Image Generation API

Basic image generation using AI. For advanced features like references, aliases, and flows, see 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:

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

Response: 201 Created

{
  "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

// 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

// 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:

{
  "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:

{
  "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

{
  "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