Use FLUX 3 Video with Comfy Router

API Reference for FLUX 3 Video. FLUX 3 Video is Black Forest Labs’ video generation model, turning a text prompt into a short clip with synchronized audio.

Comfy Router is not generally available yet. POST /v2/models/{provider}/{model} and its catalog and schema siblings are not serving requests yet: an authenticated call answers 404 today. The snippets on this page document the contract those routes will serve, published ahead of the rollout so your integration is ready to write against.

Quick start

Create a key at platform.comfy.org/profile/api-keys and export it as COMFY_API_KEY. The Python and TypeScript snippets use the Comfy SDKs (pip install comfy-sdk, npm install @comfyorg/sdk); the cURL snippet is the same call over raw HTTP. Model ID: bfl/flux-3-video Endpoint: POST https://api.comfy.org/v2/models/bfl/flux-3-video

from comfy_sdk import Comfy

# Reads COMFY_API_KEY from the environment. Each call sends a fresh
# Idempotency-Key and waits up to 10 minutes for the finished result.
with Comfy() as client:
    result = client.models.run(
        "bfl/flux-3-video",
        {
            "mode": "t2v",
            "prompt": "a single red maple leaf falling onto still water, slow motion",
            "duration": 5,
            "aspect_ratio": "16:9",
            "generate_audio": True,
        },
    )

print("video:", result["result"]["sample"])

import { comfy } from "@comfyorg/sdk";

// Reads COMFY_API_KEY from the environment. Each call sends a fresh
// Idempotency-Key and waits up to 10 minutes for the finished result.
type Result = { result: { sample: string } };
const { data } = await comfy.models.run<Result>("bfl/flux-3-video", {
  mode: "t2v",
  prompt: "a single red maple leaf falling onto still water, slow motion",
  duration: 5,
  aspect_ratio: "16:9",
  generate_audio: true,
});

console.log("video:", data.result.sample);

curl https://api.comfy.org/v2/models/bfl/flux-3-video \
  -H "X-API-Key: $COMFY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d "{\"mode\": \"t2v\", \"prompt\": \"a single red maple leaf falling onto still water, slow motion\", \"duration\": 5, \"aspect_ratio\": \"16:9\", \"generate_audio\": true}"

Schema

Input

string

default:"\"auto\""

Output aspect ratio: auto, 21:9, 2:1, 16:9, 4:3, 1:1, 3:4, or 9:16. auto lets BFL choose from the prompt and any references.

boolean

default:"false"

Draft mode: generate a fast preview whose result includes a draft_cache download URL. Send that bundle back with mode draft_enhance to render the full-quality version of the same generation.

string

draft_enhance only. Encrypted draft-cache bundle from a prior draft generation, as the base64-encoded downloaded bundle or its still-valid http(s) URL. The original inputs are embedded in the bundle.

integer | string

default:"\"auto\""

Video duration in seconds (any whole second from 5 to 20), or auto to fit the content.Range: 5 to 20

boolean

default:"true"

Generate synchronized audio alongside the video.

object

i2v only. Images that become frames of the video, each an http(s) URL or base64, one to ten total. Accepts a single image, a list of images (one starts the video, two start and end it, more spread evenly and need a set duration), or timestamped [seconds, image] pairs in time order, e.g. [[0, ”…”], [3.5, ”…”]].

string

required

Generation mode: t2v (text-to-video), i2v (image-continuation), v2v (video-continuation), or draft_enhance (full-quality render of a prior draft). Spelled-out aliases such as text-to-video are accepted.

string

Free-form prompt describing the video. Required for every mode except draft_enhance.

string

default:"\"hd\""

Video resolution class: hd, or fhd for a higher-resolution result finished by the video upsampler. Exact dimensions vary with the aspect ratio.

integer

default:"2"

Tolerance level for input and output harm moderation, 0 strictest. Sexual content is limited to level 3 and hate content to level 2 regardless of the requested tolerance; requests with conditioning media are limited to level 2.Range: 0 to 4

string

v2v only. The video to continue, an http(s) URL or base64 MP4; the generated clip carries on from its final frames.

string

default:"\"latest\""

Endpoint version. latest serves the current release; dated pinnable release tags are added as they are published.

Generated from the schema Router serves at GET /v2/models/bfl/flux-3-video/openapi.json, the same document it validates a call against before the request reaches the provider.

Output

number

Provider-reported cost in credits, populated once the task is Ready.Format: float

string

required

BFL task identifier.

number

Optional generation progress reported by BFL.Range: 0 to 1Format: float

object | object

required

The finished generation. Exactly one of the two URL leaves is populated: sample in the default mode, draft_cache in draft: true mode.

number

Provider-reported task cost. This is BFL’s number, not the Comfy charge.Format: double

string (uri)

Signed URL returned INSTEAD of sample by the draft: true mode, re-hosted onto Comfy storage the same way sample is: normally a Comfy-hosted URL valid for up to 24 hours, and BFL’s own roughly two-hour delivery URL when the re-host could not be performed.Format: uri

string (uri)

Signed URL for the generated MP4. Router re-hosts the asset onto Comfy storage and rewrites this field, so it is normally a Comfy-hosted URL valid for up to 24 hours - signed for 24 hours when minted and replayed from a 23-hour memo, so a later poll can hand back one with as little as an hour left; a leaf whose re-host could not be performed keeps BFL’s own roughly two-hour delivery URL instead. Absent in draft: true mode.Format: uri

string

required

Task status: Pending, Reasoning, Generating, Ready, Request Moderated, Content Moderated, Error, or Task not found. Compare case-insensitively; Router forwards BFL’s spelling unchanged.

Examples

Input

{
  "mode": "t2v",
  "prompt": "A slow dolly shot through a rain-soaked neon street at night"
}

Output

{
  "cost": null,
  "id": "3f7a1b28-5c0d-4e91-8a6f-1b2c3d4e5f60",
  "progress": null,
  "result": {
    "cost": null,
    "draft_cache": "https://example.invalid/bfl/flux-3-video/draft.mp4"
  },
  "status": "Ready"
}

result.sample is a signed URL that expires roughly two hours after the result is ready. Download the MP4 promptly.

Before you ship

The snippets above are the shortest working call. Three things are the same for every model and are documented once on the Comfy Router headers page: send an Idempotency-Key on every paid call and reuse it when you retry, expect the connection to be held up to Router’s 10 minute deadline, and keep X-Comfy-Request-Id from every response. The SDKs do all three for you; the cURL tab does none of them. On failure, X-Comfy-Error-Type names the bucket, and a 422 means the body failed the model’s schema and was never billed.

Headers

Authentication, idempotency, request IDs, error buckets, retry pacing, spend limits.

Quick Start

Typed error handling in Python and TypeScript, reading the 422, walking the catalog.

Limitations

What Router does not do today, and what to use instead.

Develop with Comfy

Deploy ComfyUI

Run Workflows

Comfy Router

Comfy CLI

Specifications

Use FLUX 3 Video with Comfy Router

Quick start

Schema

Input

Output

Examples

Input

Output

Before you ship

Headers

Quick Start

Limitations

​Quick start

​Schema

​Input

​Output

​Examples

​Input

​Output

​Before you ship

Headers

Quick Start

Limitations

Quick start

Schema

Input

Output

Examples

Input

Output

Before you ship