BytePlus Seedance Direct API

BytePlus Seedance Direct API

Community-maintained ComfyUI nodes for generating Seedance videos through the BytePlus ModelArk Direct API. The nodes submit paid tasks to the BytePlus account associated with your ARK_API_KEY.

This project is not an official BytePlus or ComfyUI release. BytePlus and Seedance are trademarks of their respective owners.

Install

ComfyUI Desktop users should install BytePlus Seedance Direct API from Manager → Custom Nodes Manager, then restart ComfyUI. Manager installs the small truststore dependency automatically.

If an older manual copy named byteplus_seedance25 is already installed, disable or remove it before installing the Registry version. Keeping both copies registers the same node IDs twice.

Manual installation:

cd ComfyUI/custom_nodes
git clone https://github.com/raucvr/byteplus-seedance-direct.git
cd byteplus-seedance-direct
python -m pip install -r requirements.txt

This release requires ComfyUI 0.34.0 or newer and Python 3.10 or newer.

Configure the API key

Activate the Seedance models you plan to use in the BytePlus ModelArk AP region and create an API key in the same region. Never put the key in a workflow, prompt, screenshot, or Git repository.

macOS or Windows / ComfyUI Desktop

After restarting ComfyUI once with this node installed, use any of these in-app entry points:

• Open Settings → BytePlus → Seedance → ModelArk API Key.
• Choose BytePlus → Configure BytePlus API Key from the top menu.
• Click Configure API Key inside the BytePlus Seedance Reference to Video node.

Paste the ModelArk ark-... key into the password field and click Save. The extension detects the operating system from the ComfyUI backend and stores the key in the current user's default macOS Keychain or Windows Credential Manager. It is not saved in ComfyUI settings, the node, workflow JSON, logs, or process arguments. The node can use the new key immediately without another restart.

On macOS, clicking Save or Delete Stored Key automatically opens the native Keychain unlock dialog when needed. You can also click Unlock macOS Keychain first. The Mac login password is collected only by macOS and never enters ComfyUI. If macOS reports that the Keychain is unlocked while authenticated operations still fail, the explicit action refreshes that stale state once and shows a new native prompt. If the native dialog cannot appear, bring ComfyUI Desktop to the foreground and try again. A login Keychain whose password is out of sync with the Mac login password may still need to be repaired or reset in Keychain Access.

On Windows, the credential belongs to the Windows user running ComfyUI. If ComfyUI runs as a different user, service, or session without Credential Manager access, use the launch-environment method below.

To remove the key later, reopen the same in-app window. If the node has already been uninstalled on macOS, the matching Keychain item can also be removed with:

/usr/bin/security delete-generic-password \
  -a ARK_API_KEY \
  -s com.byteplus.seedance.comfyui

Linux, WSL, or environment-managed ComfyUI

Set ARK_API_KEY in the environment that starts ComfyUI. Environment configuration varies by installation; do not save the key in workflow JSON. Linux and WSL use this method because the extension does not create a plaintext fallback store. An environment value takes precedence over macOS Keychain and Windows Credential Manager on every platform, and the in-app window will not overwrite it.

Node

The active node appears under BytePlus / Seedance:

• BytePlus Seedance Reference to Video — text-only, reference generation, edit, and extend across the supported Seedance 2.x models.

The old standalone BytePlus Seedance 2.5 Text to Video (Direct API) type is retained only so existing workflows continue to open. It is deprecated and hidden from node search by default; use the unified node for new workflows.

Connect the VIDEO output to the core Save Video node and queue the workflow. Ready-to-open examples are included in example_workflows/.

| Model | Default ModelArk ID | Resolution | Output duration | Format | | --- | --- | --- | --- | --- | | Seedance 2.5 | dreamina-seedance-2-5-260628 | 480p, 720p, 1080p | auto or 4–30 seconds | MP4, MOV | | Seedance 2.0 | dreamina-seedance-2-0-260128 | 480p, 720p, 1080p, 4k | auto or 4–15 seconds | MP4 | | Seedance 2.0 Fast | dreamina-seedance-2-0-fast-260128 | 480p, 720p | auto or 4–15 seconds | MP4 | | Seedance 2.0 Mini | dreamina-seedance-2-0-mini-260615 | 480p, 720p | auto or 4–15 seconds | MP4 |

Inference endpoint (optional)

Leave endpoint_id blank to use the default ModelArk ID from the selected model. If your API key is restricted to a specific ModelArk inference endpoint, enter that endpoint's ID in endpoint_id. The node sends this value as the request's model; it does not send a separate endpoint_id API field.

Keep the model selector set to the Seedance model deployed by that endpoint because the node uses the selected model for resolution, duration, format, and task-type validation. The API key and endpoint must belong to the same ModelArk project and AP region. This extension currently calls the BytePlus ModelArk AP base URL, so an endpoint from another region will not work.

An Endpoint ID is not an API key. It is saved in the ComfyUI workflow, so do not paste an ark-... secret into this field. AccessDenied can also indicate missing model activation, project, region, IP, or IAM permission; adding an Endpoint ID only fixes keys that are allowed to call that endpoint.

Reference inputs

The reference node exposes dynamic image_1, image_2, ... and audio_1, audio_2, ... sockets. Leave all reference sockets disconnected for text-to-video. In the prompt, refer to connected media as @Image 1, @Image 2, @Audio 1, and so on.

The task API accepts inline image and audio data but does not accept inline video bytes. The dynamic video_1, video_2, ... sockets therefore take a String containing either a public HTTPS video URL or an existing asset://... video URI. A normal local Load Video output cannot connect directly; upload the clip to storage you control or create a ModelArk asset first.

The asset_1, asset_2, ... String sockets accept typed asset URIs:

image:asset://ASSET_ID
video:asset://ASSET_ID
audio:asset://ASSET_ID

The visible seed changes ComfyUI caching only. It is not sent to BytePlus.

Task types

| Task type | Behavior | | --- | --- | | auto | Lets Seedance infer text, reference, edit, or extend behavior. | | reference | Uses connected references. With text only, the node automatically falls back to auto. | | edit | Seedance 2.5 only. Requires a reference video and follows its ratio and duration. | | extend | Seedance 2.5 only. Requires a reference video and generates a new continuation segment. |

Seedance 2.0, 2.0 Fast, and 2.0 Mini use auto for reference, edit, and extend prompts. The 2.5-specific task hint is not sent to those models.

Seedance 2.5 accepts up to 30 images, 10 videos, and 10 audio clips. The 2.0 models accept up to 9 images, 3 videos, and 3 audio clips. The node validates common size, duration, ratio, media-count, request-size, and download limits before or during submission.

Billing, data, and retries

Queuing the node can create a paid ModelArk task. Prompts and connected reference media are sent to BytePlus; generated video is downloaded from a temporary BytePlus result URL. Review the current BytePlus pricing, data-processing terms, and model access rules for your account before use.

Task creation is never automatically retried because a duplicate request could create duplicate charges. If polling or download fails after creation, the error includes a task ID. Paste it into the advanced resume_task_id input to continue the same task without creating another paid generation.

Stopping ComfyUI does not cancel an already-created remote task.

Support

Report node bugs at GitHub Issues. For ModelArk account access, quotas, pricing, and API service issues, use BytePlus support.

License

GPL-3.0. See LICENSE.