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

9.1 KiB
Raw Blame History

Advanced Image Generation

Advanced generation features: reference images, aliases, flows, and regeneration. For basic generation, see image-generation.md.

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

Reference Images

Use existing images as style or content references for generation.

Using References

Add referenceImages array to your generation request:

{
  "prompt": "A product photo with the logo in the corner",
  "referenceImages": ["@brand-logo", "@product-style"]
}

References can be:

  • Project aliases: @logo, @brand-style
  • Flow aliases: @hero (with flowId context)
  • Technical aliases: @last, @first, @upload
  • Image UUIDs: 550e8400-e29b-41d4-a716-446655440000

Auto-Detection from Prompt

Aliases in the prompt are automatically detected and used as references:

{
  "prompt": "Create a banner using @brand-logo with blue background"
}
// @brand-logo is auto-detected and added to referenceImages

Reference Limits

Constraint Limit
Max references 3 images
Max file size 5MB per image
Supported formats PNG, JPEG, WebP

Response with References

{
  "data": {
    "id": "550e8400-...",
    "prompt": "Create a banner using @brand-logo",
    "referencedImages": [
      { "imageId": "7c4ccf47-...", "alias": "@brand-logo" }
    ],
    "referenceImages": [
      {
        "id": "7c4ccf47-...",
        "storageUrl": "http://...",
        "alias": "@brand-logo"
      }
    ]
  }
}

Alias Assignment

Assign aliases to generated images for easy referencing.

Project-Scoped Alias

Use alias parameter to assign a project-wide alias:

{
  "prompt": "A hero banner image",
  "alias": "@hero-banner"
}

The output image will be accessible via @hero-banner anywhere in the project.

Flow-Scoped Alias

Use flowAlias parameter to assign a flow-specific alias:

{
  "prompt": "A hero image variation",
  "flowId": "550e8400-...",
  "flowAlias": "@best"
}

The alias @best is only accessible within this flow's context.

Alias Format

Rule Description
Prefix Must start with @
Characters Alphanumeric, underscore, hyphen
Pattern @[a-zA-Z0-9_-]+
Max length 50 characters
Examples @logo, @hero-bg, @image_1

Reserved Aliases

These aliases are computed automatically and cannot be assigned:

Alias Description
@last Most recently generated image in flow
@first First generated image in flow
@upload Most recently uploaded image in flow

Override Behavior

When assigning an alias that already exists:

  • The new image gets the alias
  • The old image loses the alias (alias set to null)
  • The old image is not deleted, just unlinked

3-Tier Alias Resolution

Aliases are resolved in this order of precedence:

1. Technical Aliases (Highest Priority)

Computed on-the-fly, require flow context:

GET /api/v1/images/@last?flowId=550e8400-...
Alias Returns
@last Last generated image in flow
@first First generated image in flow
@upload Last uploaded image in flow

2. Flow Aliases

Stored in flow's aliases JSONB field:

GET /api/v1/images/@hero?flowId=550e8400-...

Different flows can have the same alias pointing to different images.

3. Project Aliases (Lowest Priority)

Stored in image's alias column:

GET /api/v1/images/@logo

Global across the project, unique per project.

Resolution Example

// Request with flowId
GET /api/v1/images/@hero?flowId=abc-123

// Resolution order:
// 1. Is "@hero" a technical alias? No
// 2. Does flow abc-123 have "@hero" in aliases? Check flows.aliases JSONB
// 3. Does any image have alias = "@hero"? Check images.alias column

Flow Integration

Flows organize related generations into chains.

Lazy Flow Creation

When flowId is not provided, a pending flow ID is generated:

// Request
{
  "prompt": "A red car"
  // No flowId
}

// Response
{
  "data": {
    "id": "gen-123",
    "flowId": "flow-456"  // Auto-generated, flow record not created yet
  }
}

The flow record is created when:

  • A second generation uses the same flowId
  • A flowAlias is assigned to any generation in the flow

Eager Flow Creation

When flowAlias is provided, the flow is created immediately:

{
  "prompt": "A hero banner",
  "flowAlias": "@hero-flow"
}

No Flow Association

To explicitly create without flow association:

{
  "prompt": "A standalone image",
  "flowId": null
}

flowId Behavior Summary

Value Behavior
undefined (not provided) Auto-generate pendingFlowId, lazy creation
null (explicitly null) No flow association
"uuid-string" Use provided ID, create flow if doesn't exist

Regeneration

Regenerate Generation

Recreate an image using the exact same parameters:

POST /api/v1/generations/:id/regenerate

Behavior:

  • Uses exact same prompt, aspect ratio, references
  • Preserves output image ID and URL
  • Works regardless of current status
  • No request body needed

Response: Same as original generation with new image

Update and Regenerate

Use PUT to modify parameters with smart regeneration:

PUT /api/v1/generations/:id

{
  "prompt": "A blue car instead",
  "aspectRatio": "1:1"
}

Smart Behavior:

Changed Field Triggers Regeneration
prompt Yes
aspectRatio Yes
flowId No (metadata only)
meta No (metadata only)

Flow Regenerate

Regenerate the most recent generation in a flow:

POST /api/v1/flows/:id/regenerate

Behavior:

  • Finds the most recent generation in flow
  • Regenerates with exact same parameters
  • Returns error if flow has no generations

Flow Management

List Flows

GET /api/v1/flows

Query Parameters:

Parameter Type Default Description
limit number 20 Results per page (max: 100)
offset number 0 Pagination offset

Response:

{
  "data": [
    {
      "id": "flow-456",
      "projectId": "project-123",
      "aliases": { "@hero": "img-789", "@best": "img-abc" },
      "generationCount": 5,
      "imageCount": 7,
      "createdAt": "2025-11-28T10:00:00.000Z"
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 3, "hasMore": false }
}

Get Flow

GET /api/v1/flows/:id

Returns flow with computed counts and aliases.

List Flow Generations

GET /api/v1/flows/:id/generations

Returns all generations in the flow, ordered by creation date (newest first).

List Flow Images

GET /api/v1/flows/:id/images

Returns all images in the flow (generated and uploaded).

Update Flow Aliases

PUT /api/v1/flows/:id/aliases

{
  "aliases": {
    "@hero": "image-id-123",
    "@best": "image-id-456"
  }
}

Behavior: Merges with existing aliases (does not replace all).

Remove Flow Alias

DELETE /api/v1/flows/:id/aliases/:alias

Example: DELETE /api/v1/flows/flow-456/aliases/@hero

Delete Flow

DELETE /api/v1/flows/:id

Cascade Behavior:

  • Flow record is hard deleted
  • All generations in flow are hard deleted
  • Images without project alias: hard deleted with MinIO cleanup
  • Images with project alias: kept, but flowId set to null

Full Request Example

// POST /api/v1/generations
{
  "prompt": "A professional product photo using @brand-style and @product-template",
  "aspectRatio": "1:1",
  "autoEnhance": true,
  "enhancementOptions": { "template": "product" },
  "flowId": "campaign-flow-123",
  "alias": "@latest-product",
  "flowAlias": "@hero",
  "meta": { "campaign": "summer-2025" }
}

What happens:

  1. @brand-style and @product-template resolved and used as references
  2. Prompt enhanced using "product" template
  3. Generation created in flow campaign-flow-123
  4. Output image assigned project alias @latest-product
  5. Output image assigned flow alias @hero in the flow
  6. Custom metadata stored

Response Fields (Additional)

Field Type Description
flowId string Associated flow UUID
alias string Project-scoped alias (on outputImage)
referencedImages array Resolved references: [{ imageId, alias }]
referenceImages array Full image details of references

Error Codes

HTTP Status Code Description
400 ALIAS_FORMAT_CHECK Alias must start with @
400 RESERVED_ALIAS Cannot use technical alias
404 ALIAS_NOT_FOUND Referenced alias doesn't exist
404 FLOW_NOT_FOUND Flow does not exist

See Also