ComfyUI-BFL-Flux-3-video

<div align="center">

🎬 ComfyUI-BFL-Flux3-Video

Black Forest Labs FLUX 3 Video API integration for ComfyUI

Submit FLUX 3 video jobs directly from ComfyUI, poll them automatically, download the finished MP4, and continue your workflow with a native ComfyUI VIDEO output.

<br>

<br>

Installation · API Key · Modes · Examples · Troubleshooting

</div>

---

[!IMPORTANT]

Black Forest Labs API + credits are required

This custom node integrates directly with the hosted Black Forest Labs FLUX 3 Video API.

It does not run FLUX 3 Video locally.

To generate video you need:

• a Black Forest Labs account
• a valid Black Forest Labs API key
• sufficient Black Forest Labs API credits

Create API keys and purchase credits:
https://dashboard.bfl.ai/

API usage and generation charges are billed by Black Forest Labs according to their current pricing.

[!NOTE]

Independent community project

This project is not affiliated with, endorsed by, sponsored by, or officially maintained by Black Forest Labs.

Black Forest Labs, FLUX, FLUX 3, and related names and trademarks belong to their respective owners.

---

✨ Highlights

| | Feature | |---|---| | 🔌 | Direct Black Forest Labs FLUX 3 Video API integration | | 🧩 | Native ComfyUI custom node | | 🎞️ | Native ComfyUI VIDEO output | | 📝 | Text-to-video (t2v) | | 🖼️ | Image-to-video (i2v) with one or two keyframes | | ▶️ | Video continuation (v2v) | | ⚡ | Draft generation + draft_enhance | | 🔊 | Optional synchronized audio generation | | 🔐 | API key field or BFL_API_KEY environment variable | | 🔄 | Automatic asynchronous polling | | 💾 | Automatic MP4 and draft-cache download | | 🧪 | Request ID and result JSON debugging outputs | | ⏸️ | enable_this_node toggle to prevent unwanted API calls | | ⚙️ | Configurable endpoint, timeouts, aspect ratio, duration, resolution, and safety tolerance |

---

🚀 At a glance

ComfyUI Workflow
      │
      ▼
┌─────────────────────┐
│   BFL-Flux3-Video   │
└─────────────────────┘
      │
      │  HTTPS API request
      ▼
┌─────────────────────┐
│ Black Forest Labs   │
│ FLUX 3 Video API    │
└─────────────────────┘
      │
      │  polling_url
      ▼
 Automatic status polling
      │
      ▼
 Download generated MP4
      │
      ▼
 Native ComfyUI VIDEO

---

🧩 Node information

| Property | Value | |---|---| | Node ID / Python class | BFLFlux3Video | | Display name | BFL-Flux3-Video | | Category | BFL → FLUX 3 | | API | Black Forest Labs FLUX 3 Video | | Output video type | Native ComfyUI VIDEO | | License | GNU GPL v3.0 |

---

🎥 Supported Modes

📝 t2v — Text to Video

Generate a video directly from a prompt.

Typical inputs

prompt
aspect_ratio
duration
resolution
generate_audio
safety_tolerance
draft

No keyframe or starting-video connection is required.

---

🖼️ i2v — Image to Video

Generate a video from one or two ComfyUI IMAGE inputs.

One keyframe

IMAGE ─────► keyframe_1

keyframe_1 becomes the opening frame.

Two keyframes

IMAGE 1 ───► keyframe_1
IMAGE 2 ───► keyframe_2

The node uses:

| Input | Role | |---|---| | keyframe_1 | Starting frame | | keyframe_2 | Ending frame |

Connected ComfyUI images are automatically encoded as PNG/base64 data for the BFL request.

---

▶️ v2v — Video Continuation

Continue an existing native ComfyUI video.

VIDEO ─────► start_video

The node serializes the connected video as MP4 and submits it to Black Forest Labs as the starting video.

Mode-specific duration constraints are validated before submitting the request.

---

⚡ draft_enhance — Draft to Full Quality

FLUX 3 can generate a faster draft first, then reproduce the selected draft at full quality.

Recommended workflow

┌────────────────────────────┐
│ BFL-Flux3-Video            │
│ mode  = t2v / i2v / v2v   │
│ draft = true               │
└─────────────┬──────────────┘
              │
              │ draft_cache_path
              ▼
┌────────────────────────────┐
│ BFL-Flux3-Video            │
│ mode = draft_enhance       │
│ draft_cache ◄──────────────┘
└─────────────┬──────────────┘
              │
              ▼
       Full-quality VIDEO

Steps

1. Generate a video using t2v, i2v, or v2v.
2. Set draft = true.
3. The node automatically downloads the returned BFL draft_cache.
4. Connect draft_cache_path to the draft_cache input of another BFL-Flux3-Video node.
5. Set the second node to draft_enhance.
6. Queue the workflow.

[!NOTE] version is intentionally not sent in draft_enhance mode because the Black Forest Labs draft-enhancement schema does not accept that field.

The draft_cache input can accept:

• local file path
• HTTP/HTTPS URL
• base64 data URL
• raw base64 cache data

---

⏸️ Enable / Disable the Node

The node includes:

enable_this_node

Default:

true

When set to false:

• no BFL generation request should be submitted
• no BFL generation credits should be consumed by that node execution
• downstream execution for that branch is blocked

This is useful when maintaining multiple API-generation branches in a larger workflow.

---

🔑 Black Forest Labs API Key

A valid Black Forest Labs API key is required.

<div align="center">

🔗 https://dashboard.bfl.ai/

Create API keys · Manage your account · Purchase credits

</div>

The node resolves the API key in this order:

1. api_key field in the node
2. BFL_API_KEY environment variable

[!TIP] Use BFL_API_KEY whenever possible.

An API key typed directly into a ComfyUI node may be serialized into a workflow JSON if that workflow is saved or shared.

Windows PowerShell — current session

$env:BFL_API_KEY="your-api-key-here"

Windows — persistent environment variable

setx BFL_API_KEY "your-api-key-here"

Restart ComfyUI after using setx.

Linux / macOS

export BFL_API_KEY="your-api-key-here"

---

💳 Credits & Billing

[!WARNING] This node does not provide free FLUX 3 Video inference.

Every generation is submitted to Black Forest Labs and may consume API credits.

Black Forest Labs controls:

• pricing
• credit balances
• billing
• rate limits
• API availability
• account restrictions
• model availability

Manage API keys and credits here:

https://dashboard.bfl.ai/

For current pricing and model specifications, refer to the official Black Forest Labs documentation.

---

📦 Installation

Option 1 — Git clone

Open a terminal in your ComfyUI custom_nodes directory:

cd ComfyUI/custom_nodes

Clone the repository:

git clone https://github.com/AllenCraigBarnard/ComfyUI-BFL-Flux3-Video.git

Install dependencies:

pip install -r ComfyUI-BFL-Flux3-Video/requirements.txt

Restart ComfyUI.

---

Option 2 — Download ZIP

1. Open the GitHub repository.
2. Select Code → Download ZIP.
3. Extract the archive.
4. Place the folder at:

ComfyUI/custom_nodes/ComfyUI-BFL-Flux3-Video

5. Install requirements.txt.
6. Restart ComfyUI.

---

Windows Portable / Embedded Python

From your ComfyUI portable root:

python_embeded\python.exe -m pip install -r ComfyUI\custom_nodes\ComfyUI-BFL-Flux3-Video\requirements.txt

Restart ComfyUI afterward.

---

📋 Requirements

Python dependencies are listed in:

requirements.txt

Install them using the same Python environment that launches ComfyUI:

pip install -r requirements.txt

---

🎛️ Inputs

Generation inputs

| Input | Description | |---|---| | enable_this_node | Enables or disables this API branch | | prompt | Video-generation prompt | | mode | t2v, i2v, v2v, or draft_enhance | | keyframe_1 | First image keyframe for i2v | | keyframe_2 | Optional second image keyframe for i2v | | start_video | Native ComfyUI video used for v2v | | draft_cache | Previous FLUX 3 draft cache for draft_enhance | | aspect_ratio | Requested output aspect ratio | | duration | Requested video duration | | resolution | hd or fhd | | generate_audio | Enables synchronized audio generation | | safety_tolerance | Black Forest Labs safety-tolerance setting | | draft | Requests a draft generation when supported | | version | FLUX 3 version field for standard generation modes |

<details> <summary><strong>⚙️ Advanced API / execution inputs</strong></summary> <br>

| Input | Description | |---|---| | api_key | Optional API key override | | api_url | Black Forest Labs API endpoint | | poll_interval_seconds | Delay between asynchronous status checks | | job_timeout_seconds | Maximum time to wait for a generation | | http_timeout_seconds | Timeout for individual HTTP requests | | filename_prefix | Prefix for downloaded output files |

</details>

---

📤 Outputs

| Output | Description | |---|---| | video | Native ComfyUI VIDEO | | video_path | Local path of the downloaded MP4 | | request_id | Black Forest Labs request ID | | result_json | Request/result diagnostic metadata | | draft_cache_path | Local path of a downloaded draft cache |

Output directory

Generated videos are stored under:

ComfyUI/output/bfl_flux3_video/

Draft-cache bundles are stored locally for reuse with draft_enhance.

Large embedded media/base64 blobs are omitted from diagnostic output where possible.

---

🧪 Usage Examples

Example 1 — Text to Video

enable_this_node = true
mode             = t2v
prompt           = cinematic aerial shot of a forest at sunrise
aspect_ratio     = 16:9
duration         = 5
resolution       = hd
generate_audio   = true
draft            = false

What happens

Submit request
      ↓
Receive request ID + polling URL
      ↓
Poll BFL until Ready
      ↓
Download MP4
      ↓
Return native ComfyUI VIDEO

---

Example 2 — Two-Keyframe Image to Video

IMAGE 1 ───► keyframe_1
IMAGE 2 ───► keyframe_2

mode = i2v

The two images define the beginning and ending keyframes of the generated sequence.

---

Example 3 — Video Continuation

VIDEO ─────► start_video

mode = v2v

Describe what should happen next in prompt, then queue the workflow.

---

Example 4 — Draft → Enhance

Node 1

mode  = t2v
draft = true

Connect

Node 1: draft_cache_path
             │
             ▼
Node 2: draft_cache

Node 2

mode = draft_enhance

Queue the workflow to render the selected draft at full quality.

---

🌐 API Endpoint

Default:

https://api.bfl.ai/v1/flux-3-video

The node exposes api_url as an advanced field so a compatible BFL endpoint can be supplied when necessary.

---

🔐 Security

[!CAUTION] Never commit a real Black Forest Labs API key to GitHub.

Do not place credentials in:

• README.md
• nodes.py
• workflow JSON files
• screenshots
• example configurations
• shell scripts
• issue reports

Recommended .gitignore

__pycache__/
*.py[cod]
*.log

.env
.env.*

.vscode/
.idea/

.DS_Store
Thumbs.db

If a key is accidentally published, revoke or rotate it from your Black Forest Labs account immediately.

---

🛠️ Troubleshooting

<details> <summary><strong>Node does not appear in ComfyUI</strong></summary> <br>

1. Restart ComfyUI.

2. Check the ComfyUI console for import errors.

3. Confirm the repository is directly under:

   ComfyUI/custom_nodes/ComfyUI-BFL-Flux3-Video
   

4. Install requirements.txt with the same Python environment used by ComfyUI.

5. Confirm your ComfyUI installation supports the APIs used by the node.

</details> <details> <summary><strong>Missing API key</strong></summary> <br>

Typical message:

No Black Forest Labs API key was provided.

Fix it by either:

• entering the key in api_key, or
• defining BFL_API_KEY

</details> <details> <summary><strong>HTTP 402 — Insufficient credits</strong></summary> <br>

Typical response:

HTTP 402 Payment Required
Insufficient credits

The request reached Black Forest Labs, but the account associated with the API key does not have enough credits.

Add credits here:

https://dashboard.bfl.ai/

</details> <details> <summary><strong>HTTP 422 — Invalid request</strong></summary> <br>

An HTTP 422 response generally indicates a request field is incompatible with the selected FLUX 3 mode.

Check:

• mode
• keyframe connections
• start_video
• draft_cache
• duration
• resolution
• mode-specific fields

</details> <details> <summary><strong>API request fails for another reason</strong></summary> <br>

Check:

1. API key validity
2. BFL credit balance
3. selected mode
4. connected media inputs
5. HTTP status and returned error body
6. current Black Forest Labs FLUX 3 documentation

</details>

---

🔄 Updating

If installed with Git:

cd ComfyUI/custom_nodes/ComfyUI-BFL-Flux3-Video
git pull

Restart ComfyUI.

If dependencies changed:

pip install -r requirements.txt

using the same Python environment that runs ComfyUI.

---

🔗 Official Resources

| Resource | Link | |---|---| | Black Forest Labs Dashboard | https://dashboard.bfl.ai/ | | Black Forest Labs Documentation | https://docs.bfl.ai/ | | ComfyUI Documentation | https://docs.comfy.org/ |

---

🤝 Contributing

Issues and pull requests are welcome.

When reporting a problem, include:

• ComfyUI version
• Python version
• selected node mode
• relevant error message
• relevant ComfyUI console log

[!CAUTION] Never include API keys, credentials, or other secrets in an issue report.

By submitting a contribution, you agree that your contribution may be distributed under this project's GNU General Public License v3.0 (GPL-3.0).

---

⚖️ License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0).

You may use, study, modify, and redistribute this project under the terms of the GNU GPL v3.0. If you distribute modified versions or derivative works covered by the GPL, the corresponding source code must remain available under the applicable GPL terms.

See LICENSE for the full license text.

[!NOTE] The GPL license applies to this project's source code. It does not grant rights to Black Forest Labs services, models, APIs, trademarks, or other third-party materials.

Use of the Black Forest Labs API remains subject to Black Forest Labs' own terms, policies, pricing, and account requirements.

---

🙏 Acknowledgements

FLUX 3 and the FLUX API are products and services of Black Forest Labs.

This repository provides an independent ComfyUI integration for that API and is not an official Black Forest Labs project.

---

<div align="center">

Made for ComfyUI workflows that use the Black Forest Labs FLUX 3 Video API

API key + BFL credits required

https://dashboard.bfl.ai/

</div>