comfyui-seedance-nodes

comfyui-seedance-nodes

ComfyUI custom nodes for BytePlus / ByteDance Seedance 2 video-generation API.

---

Nodes

| Node | Category | Description | |------|----------|-------------| | Seedance – Text to Video | Seedance/Video Generation | Generate a video from a text prompt only. | | Seedance – Image to Video (First Frame) | Seedance/Video Generation | Animate an image forward using a text description. The image becomes the first frame. | | Seedance – Image to Video (First + Last Frame) | Seedance/Video Generation | Interpolate motion between two images. Supply the start and end frames; the model fills in the middle. | | Seedance – Image to Video (Reference) | Seedance/Video Generation | Use one to three reference images to guide the visual style/subject of the video (no frame-position locking). |

All nodes output four values:

| Output | Type | Description | |--------|------|-------------| | video | VIDEO (STRING fallback) | Native ComfyUI VIDEO object — connect directly to Save Video or any video preview node. Falls back to the file path STRING on older ComfyUI builds. | | last_frame | IMAGE | The final frame of the generated video as a ComfyUI IMAGE tensor. Connect to the next node's first_frame input to chain clips seamlessly. | | video_url | STRING | CDN URL returned by the API (valid for 48 hours). | | video_path | STRING | Local path where the .mp4 was saved (inside ComfyUI's output directory). |

---

Installation

1. Clone into custom_nodes

cd ComfyUI/custom_nodes
git clone https://github.com/YOUR_USERNAME/comfyui-seedance-nodes.git

2. Install dependencies

pip install -r ComfyUI/custom_nodes/comfyui-seedance-nodes/requirements.txt

Note: opencv-python is required to extract the last frame from generated videos. It is included in requirements.txt.

3. Configure your API key

Option A – environment variable (recommended):

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

Option B – paste the key directly into the api_key field in any node inside ComfyUI.

Get your key at: https://console.byteplus.com/ark/region:ark+ap-southeast-1/apikey

4. Restart ComfyUI

The nodes will appear under the Seedance / Video Generation category in the node browser.

---

Node reference

Common inputs (all nodes)

| Input | Type | Description | |-------|------|-------------| | api_key | STRING | BytePlus ARK API key. If empty, falls back to the ARK_API_KEY environment variable. | | model | COMBO | Model ID to use. Currently dreamina-seedance-2-0-260128. | | ratio | COMBO | Output aspect ratio: 16:9, 9:16, 1:1, 4:3, 3:4, adaptive. | | duration | COMBO | Video length in seconds (5 or 10). | | generate_audio | BOOLEAN | Whether the model generates ambient audio. | | watermark | BOOLEAN | Whether to add a BytePlus watermark. | | poll_interval | INT | Seconds between status-check calls (default 10). | | max_wait | INT | Maximum total wait time in seconds (default 600). |

Text to Video – extra inputs

| Input | Description | |-------|-------------| | prompt | The text description of the video. |

Image to Video (First Frame) – extra inputs

| Input | Description | |-------|-------------| | first_frame | ComfyUI IMAGE tensor used as the first frame. | | prompt | Describes how the image should be animated. | | image_url_override | Optional: paste an HTTP URL to use instead of the IMAGE input. |

Image to Video (First + Last Frame) – extra inputs

| Input | Description | |-------|-------------| | first_frame | IMAGE tensor – first frame. | | last_frame | IMAGE tensor – last frame. | | prompt | Describes the motion between the two frames. | | first_frame_url / last_frame_url | Optional HTTP URL overrides. |

Image to Video (Reference) – extra inputs

| Input | Description | |-------|-------------| | reference_image_1 | Primary reference IMAGE tensor (required). | | reference_image_2 / reference_image_3 | Additional reference images (optional). | | prompt | Text description of the desired video. | | ref_url_1/2/3 | Optional HTTP URL overrides for each reference image. |

---

Tips

• Cold-start latency – the API queues tasks; poll_interval=10 with max_wait=600 works for most generations. Increase max_wait for 10-second videos at high resolution.
• Image inputs – connect any ComfyUI IMAGE node (LoadImage, VAE Decode output, etc.) directly to the image inputs. The node converts the tensor to a PNG base64 data-URI automatically.
• URL overrides – if your image is already hosted (e.g., on S3 or a CDN), paste the URL into the *_url_override / *_url_* fields to skip the base64 encoding step.
• Output – videos are saved in ComfyUI/output/ with a timestamp filename (seedance_<timestamp>.mp4). The video output connects directly to Save Video; the last_frame IMAGE output connects to the next node's first_frame to chain multiple clips together.

---

License

MIT