docs/generation-flux.md

FLUX.2 Klein generation provider

Status and audited worker

MediaRouter optionally integrates the FLUX worker as provider flux, model flux.2-klein-4b, modality image, task text-to-image. The audited worker reports Apache-2.0 and loads these FLUX.2 Klein 4B variants once:

• black-forest-labs/FLUX.2-klein-4B (Distilled (4 steps))
• black-forest-labs/FLUX.2-klein-base-4B (Base (50 steps))

The worker contract is:

Method	Endpoint	Auth	Meaning
GET	/health	public	Liveness; {"status":"ok"} does not mean a model is ready
GET	/ready	public	ready, model_loaded, model, accepting_jobs; returns 503 when not ready
GET	/v1/info	public	Exact model ID, image type, Apache-2.0 license, and base/distilled variant map
POST	/v1/generate	Bearer	Form or multipart asynchronous generation submission
GET	/v1/jobs/{id}	Bearer	queued, running, completed, failed, or cancelled
POST	/v1/jobs/{id}/cancel	Bearer	Cancels queued jobs only
GET	/v1/jobs/{id}/output	Bearer	Streams a completed PNG

Availability requires configured credentials, healthy liveness, ready with a loaded/accepting model, exact flux.2-klein-4b image identity, Apache-2.0, and the two audited variant IDs. A health response alone never advertises FLUX.

Backend configuration

Set these backend-only values in deployment secrets:

FLUX_SPACE_URL=https://your-flux-worker.hf.space
FLUX_SPACE_TOKEN=replace-with-worker-secret
AI_WORKER_CONNECT_TIMEOUT_SECONDS=10
AI_WORKER_REQUEST_TIMEOUT_SECONDS=60
AI_WORKER_READ_TIMEOUT_SECONDS=300
AI_WORKER_MAX_RETRIES=3
AI_WORKER_RETRY_BACKOFF_SECONDS=0.5
GENERATION_WORKER_ENABLED=true

FLUX_SPACE_URL and FLUX_SPACE_TOKEN must be configured together. The token must be 32–512 characters and is never returned by REST, MCP, n8n, SDKs, the frontend, audit records, or logs. Missing/malformed FLUX configuration leaves only FLUX unavailable; it does not block WAN, social providers, or startup.

Typed request mapping

MediaRouter retains the existing /v1/generation/requests API and required Idempotency-Key. It never exposes a FLUX URL, worker header, path, or job ID.

{
  "provider": "flux",
  "model_id": "flux.2-klein-4b",
  "modality": "image",
  "prompt": "A futuristic city at sunrise, cinematic architecture",
  "flux": {
    "mode_choice": "Distilled (4 steps)",
    "seed": 42,
    "randomize_seed": false,
    "width": 1024,
    "height": 1024,
    "num_inference_steps": 4,
    "guidance_scale": 1.0,
    "prompt_upsampling": false
  }
}

The closed Pydantic flux schema supports only:

Field	Constraint/default
prompt	Required, nonblank, 1–4,000 characters
mode_choice	Distilled (4 steps) (default) or Base (50 steps)
seed	Integer 0–2,147,483,647; default 42
randomize_seed	Boolean; default false
width, height	256–1,024, multiples of 8; default 1,024
num_inference_steps	Integer 1–100; default 4
guidance_scale	Number 0–10; default 1.0
prompt_upsampling	Boolean; default false

Negative prompts and schedulers are not worker-supported and are rejected. Unknown fields are rejected before GPU work; no arbitrary provider payload is passed through. The worker accepts optional image-editing inputs, but the existing MediaRouter contract exposes zero or one workspace-owned canonical input_asset_id. That image must be readable, use image MIME, and be at most 20 MiB. The worker further validates decoded inputs (16,384 pixels per side, 40 million pixels, and 80 MiB aggregate decoded RGB). Text-only jobs use form fields; optional-image jobs use one input_images multipart field.

Job, retry, and cancellation behavior

MediaRouter durable job ID
        ↓
FLUX form/multipart submission
        ↓
opaque FLUX provider job ID (internal only)
        ↓
bounded status polling
        ↓
fixed authenticated output endpoint
        ↓
canonical workspace-owned asset

FLUX states map to the existing MediaRouter state machine: queued, running, completed → output finalization → succeeded, failed, and cancelled. (provider, external_job_id) uniqueness and workspace-scoped repository operations prevent cross-workspace polling, cancellation, or output attachment.

FLUX has no submission-idempotency or request lookup. A lost response after a connection failure, timeout, 502, or 504 is terminal GENERATION_SUBMISSION_AMBIGUOUS, never a blind re-submit. Received 429 and 503 rejection responses can use bounded durable retries. Polling retries connection failures, timeouts, 429, 502, 503, and 504; validation, 400, 401, 403, invalid worker jobs, generic 500, and programming exceptions do not retry automatically.

Only queued worker jobs can be confirmed cancelled. 409 FLUX_JOB_NOT_CANCELLABLE for a running inference is a failed cancellation, not a cancellation success. The shared service retains requested, confirmed, unsupported, and failed cancellation distinctions.

Output and security

The worker reports only type: image and output.png. The adapter derives the fixed relative /v1/jobs/{id}/output path, requires image/png, and never trusts worker filesystem paths, output URLs, or client paths. Shared transport rules disable redirects/proxy environment use and reject unsafe worker origins, private literal IPs, traversal, query strings, fragments, and client-selected workers.

PNG bytes are streamed to controlled staging, size/checksum-checked where the worker provides them, and verified through the PNG signature/IHDR dimensions. CleanupService and CanonicalAssetService publish a workspace-owned asset with SHA-256, MIME, output dimensions, safe metadata, and generation linkage. No provider-specific durable storage exists.

Limitations and verification

• Worker jobs/outputs are in-memory and disappear after a worker restart.
• MediaRouter intentionally supports one optional edit image although the worker can accept four, preserving the established single-asset contract.
• A live smoke test is not verified until FLUX_SPACE_URL and FLUX_SPACE_TOKEN are supplied to the backend; mocked tests need no HF credentials.