Media¶

Image generation service that interfaces with ComfyUI and Fal.ai for text-to-image generation with automatic provider fallback.

Endpoints¶

POST /api/v1/media/generate¶

Generate a single image from a text prompt.

Request body:

{
  "prompt": "A futuristic cityscape with neon lights",
  "negative_prompt": "blurry, low quality",
  "width": 1024,
  "height": 1024,
  "steps": 30,
  "cfg_scale": 7.5,
  "seed": 42,
  "content_id": "optional-uuid"
}

Response:

{
  "file_path": "/data/media/img_abc123.png",
  "provider": "comfyui",
  "width": 1024,
  "height": 1024,
  "metadata": {},
  "asset_id": "asset-uuid"
}

curl -X POST http://localhost:8000/api/v1/media/api/v1/media/generate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A futuristic cityscape with neon lights",
    "width": 1024,
    "height": 1024
  }'

resp = httpx.post(
    "http://localhost:8000/api/v1/media/api/v1/media/generate",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "prompt": "A futuristic cityscape with neon lights",
        "width": 1024,
        "height": 1024,
    },
)
result = resp.json()

POST /api/v1/media/batch¶

Generate multiple images for a content item.

{
  "content_id": "content-uuid",
  "prompts": [
    { "prompt": "Scene 1: Opening shot of city skyline" },
    { "prompt": "Scene 2: Close-up of AI robot" }
  ]
}

Response:

{
  "content_id": "content-uuid",
  "succeeded": 2,
  "failed_count": 0,
  "results": [...],
  "errors": []
}

GET /api/v1/media/assets/{content_id}¶

Get all media assets for a content item.

GET /api/v1/media/providers¶

List available image generation providers and their status.

Provider Chain¶

The FallbackImageProvider implements the Strategy pattern:

flowchart LR
    REQ["Generate Request"] --> FBP["FallbackImageProvider"]
    FBP --> CUI{"ComfyUI\navailable?"}
    CUI -->|yes| COMFY["ComfyUIProvider\nlocalhost:8188"]
    CUI -->|no| FAL["FalImageProvider\nFal.ai Cloud"]

Default image dimensions: 1024 x 1024

Events¶