ComfyUI Extension: wavespeed-comfyui

Authored by WaveSpeedAI

Created

Updated

57 stars

Run ComfyUI workflows without the setup

No installs, no CUDA version roulette, no GPU sitting idle on your bill. Bring a workflow and run it in the browser.

This is a custom node for ComfyUI that allows you to use the WaveSpeed AI API directly in ComfyUI. WaveSpeed AI is a high-performance AI image and video generation service platform offering industry-leading generation speeds. For more information, see a/WaveSpeed AI Documentation.

Looking for a different extension?

Custom Nodes (0)

    README

    🚀 ComfyUI-WaveSpeed: Universal AI Generation Plugin

    <div align="center">

    License ComfyUI WaveSpeed AI

    </div>

    ✨ Features

    🎭 Multi-Modal Generation

    Support for 20+ AI generation categories including:

    • Text to Image - Generate images from text prompts
    • Image to Image - Transform and edit existing images
    • Text to Video - Create videos from text descriptions
    • Video to Video - Transform and enhance videos
    • Text to Audio - Generate audio from text
    • Image to 3D - Convert images to 3D models
    • And more...

    🎯 Unified Interface

    • Single Predictor Node - Access 600+ AI models through one node
    • Dynamic Parameters - Model-specific parameters auto-configure
    • Fuzzy Search - Quickly find models by name or category
    • Category Tabs - Browse models by type

    ⚡ Performance & UX

    • Smart Caching - Fast model loading after first use (first load: 5-10 seconds)
    • Progress Indicators - Real-time generation progress
    • Workflow Support - Save and restore complete workflows
    • Connection Flexibility - Connect any compatible input/output

    📦 Installation

    Prerequisites

    💡 Built on: ComfyUI v0.8.2 (Frontend v1.35.9)

    Installation Steps

    Step 1: Clone the plugin

    cd ComfyUI/custom_nodes
git clone https://github.com/WaveSpeedAI/wavespeed-comfyui.git
cd wavespeed-comfyui

    Step 2: Find ComfyUI's Python path

    Start ComfyUI and check the console output for:

    ** Python executable: D:\Projects\ComfyUI\.venv\Scripts\python.exe

    Copy that path.

    Step 3: Install dependencies

    Use the Python path from Step 2:

    # Windows example:
D:\Projects\ComfyUI\.venv\Scripts\python.exe -m pip install -r requirements.txt

# Linux/Mac example:
/home/user/ComfyUI/.venv/bin/python -m pip install -r requirements.txt

    Step 4: Restart ComfyUI

    Close and restart ComfyUI. You should see WaveSpeed nodes available.

    ⚠️ Why this matters: If you just run pip install -r requirements.txt, it might install to the wrong Python environment, causing ModuleNotFoundError.

    Restart ComfyUI after installation.

    Configuration

    1. Get your API key from WaveSpeed AI
    2. In ComfyUI: Settings → WaveSpeed → Enter API Key
    3. Or create config.json in plugin directory:
    {
  "api_key": "your_api_key_here"
}

    💡 Prefer node-based API key input? Switch to the feature/client-node-api-key branch to use a dedicated WaveSpeed Client node for API key configuration via node connection instead of Settings.

    ⏱️ First Load Notice: The first loading will fetch 600+ models from 25 categories. This takes approximately 2-4 minutes depending on your network. Subsequent loads use cached data and are instant.

    🎨 Usage Examples

    Example 1: Text-to-Image Generation

    📸 High-Quality Image Generation

    <img src="examples/case1-text-to-image/case1_t2i.png" width="600">

    Use Case: Generate professional-quality images from text descriptions

    Models: Flux Dev, SDXL, Ghibli Style, etc.

    Key Features:

    • Multiple aspect ratios (1:1, 16:9, 9:16, etc.)
    • Resolution control (512px - 2048px)
    • Seed control for reproducibility
    • Negative prompts support

    Result:

    <img src="examples/case1-text-to-image/case1.png" width="400">

    📥 Download Workflow JSON

    Example 2: Text-to-Video Generation

    🎬 Create Videos from Text

    <img src="examples/case2-text-to-video/case2_t2v.png" width="600">

    Use Case: Generate short videos from text prompts

    Models: Kling v1.6, Minimax Video, Wan2.1, etc.

    Key Features:

    • Duration control (2-10 seconds)
    • Resolution options (480p, 720p, 1080p)
    • Camera movement control
    • Audio generation option

    Note: Video generation may take several minutes. The plugin supports up to 30-minute timeout for long-running tasks.

    Result:

    https://github.com/user-attachments/assets/c6f5383b-2b80-4166-b9ea-dcfe406884b6

    📥 Download Workflow JSON

    Example 3: Image-to-Image Transformation

    🎨 Transform and Edit Images

    <img src="examples/case3-image-to-image/case3_i2i.png" width="600">

    Use Case: Transform existing images with AI

    Models: Flux Redux, Instant Character, Step1X Edit, etc.

    Key Features:

    • Style transfer
    • Image editing with prompts
    • Reference image support
    • Strength control

    Result:

    <img src="examples/case3-image-to-image/case3.png" width="400">

    📥 Download Workflow JSON

    Example 4: Image-to-Video Animation

    🎬 Animate Static Images

    <img src="examples/case4-image-to-video/case4_i2v.png" width="600">

    Use Case: Bring static images to life with motion

    Models: Stable Video Diffusion, I2VGen-XL, etc.

    Key Features:

    • Motion generation from single image
    • Camera movement control
    • Duration control
    • Smooth animation

    Result:

    📹 Download Video | 📥 Download Workflow JSON

    Example 5: Video-to-Video Enhancement

    🎞️ Enhance and Transform Videos

    <img src="examples/case5-video-to-video/case5_v2v.png" width="600">

    Use Case: Upscale, stylize, or transform videos

    Models: Seedance v1.5, Real-ESRGAN, etc.

    Key Features:

    • Video upscaling (2x, 4x)
    • Style transformation
    • Motion preservation
    • Frame interpolation

    Result:

    📹 Download Video | 📥 Download Workflow JSON

    Example 6: Text-to-Audio Generation

    🎵 Generate Audio from Text

    <img src="examples/case6-text-to-audio/case6_t2a.png" width="600">

    Use Case: Generate music, sound effects, or voice from text

    Models: Dia TTS, MMAudio V2, etc.

    Key Features:

    • Voice synthesis
    • Music generation
    • Sound effect creation
    • Multiple voice options

    Result:

    case6.mp3

    📥 Download Workflow JSON

    Example 7: Image-to-3D Model

    🎲 Convert Images to 3D

    <img src="examples/case7-image-to-3d/case7_i23D.png" width="600">

    Use Case: Generate 3D models from 2D images

    Models: Hunyuan 3D V2, etc.

    Key Features:

    • Multi-view generation
    • GLB format export
    • Texture mapping
    • Mesh optimization

    Result:

    📦 Download 3D Model (.glb) | 📥 Download Workflow JSON

    Example 8: Complex Multi-Stage Pipeline

    🔗 Advanced ComfyUI Integration

    <img src="examples/case8-complex-pipeline/case8_combination.png" width="600">

    Use Case: Demonstrate seamless integration with ComfyUI native nodes and complex multi-stage pipelines

    Workflow Highlights:

    • Multiple WaveSpeed Nodes - Chain multiple AI generation steps (T2I → I2I → I2V)
    • Native Node Integration - Mix with ComfyUI's Load Image, Save Image, Preview Image nodes
    • Flexible Data Flow - Pass IMAGE/VIDEO tensors between nodes seamlessly
    • Real-world Pipeline - Text→Image → Image Enhancement → Image→Video

    Pipeline Stages:

    1. Stage 1: Text-to-Image (WaveSpeed Predictor #1)

      • Generate base image from text prompt
      • Model: Text-to-Image model (e.g., FLUX)
      • Output: ComfyUI IMAGE tensor
      • Native Integration: Output connects directly to ComfyUI Preview Image node

    2. Stage 2: Image-to-Image Enhancement (WaveSpeed Predictor #2)

      • Enhance and refine the generated image
      • Model: Image-to-Image model (e.g., Flux Redux)
      • Input: IMAGE tensor from Stage 1 (via native ComfyUI connection)
      • Output: Enhanced IMAGE tensor
      • Native Integration: Seamlessly receives IMAGE from previous WaveSpeed node

    3. Stage 3: Image-to-Video Animation (WaveSpeed Predictor #3)

      • Animate the enhanced image into video
      • Model: Image-to-Video model (e.g., Stable Video Diffusion)
      • Input: Enhanced IMAGE tensor from Stage 2
      • Output: VIDEO URL
      • Native Integration: Works with ComfyUI's video preview nodes

    4. Stage 4: Preview & Save (Native ComfyUI Nodes)

      • Use ComfyUI's Preview Image nodes to view intermediate results
      • Use Save Image nodes to export final outputs
      • All connections work exactly like native ComfyUI nodes

    Key Integration Features:

    ✅ Tensor Compatibility

    • WaveSpeed nodes accept ComfyUI IMAGE/VIDEO/AUDIO tensors directly
    • No manual conversion needed - just connect and run
    • Works with any image/video processing node in ComfyUI ecosystem

    ✅ Output Flexibility

    • Outputs can connect to any compatible node
    • Support for Preview Image, Save Image, Video Preview, etc.
    • Chain multiple WaveSpeed nodes together seamlessly

    ✅ Workflow Persistence

    • All connections saved in workflow JSON
    • Model selections preserved across sessions
    • Parameter values restored on load
    • Full workflow portability

    ✅ Native ComfyUI Features

    • Works with node groups and reroute nodes
    • Compatible with workflow templates
    • Supports ComfyUI's execution queue
    • Full undo/redo support
    • Drag-and-drop connections

    Results:

    Stage 1 & 2 Outputs (Text-to-Image → Image-to-Image):

    <table> <tr> <td align="center"> <img src="examples/case8-complex-pipeline/case8_1.jpeg" width="400"><br> <em>Stage 1: Generated Image</em> </td> <td align="center"> <img src="examples/case8-complex-pipeline/case8_2.jpeg" width="400"><br> <em>Stage 2: Enhanced Image</em> </td> </tr> </table>

    Stage 3 Output (Image-to-Video):

    https://github.com/user-attachments/assets/10949f10-4010-4eed-a38e-159ec83dede0

    📥 Download Workflow JSON

    🔧 Core Nodes

    WaveSpeedAI Predictor ⚡

    Input:

    • Dynamic parameters - Auto-generated based on selected model
      • Common parameters: prompt, negative_prompt, seed, resolution, etc.
      • Media inputs: image, video, audio (accepts ComfyUI IMAGE/VIDEO/AUDIO tensors or URLs)
      • All parameters can be set via UI widgets or connected from other nodes

    Output:

    • output (ANY) - URL string or list of URLs:
      • Single output → URL string (e.g., "https://cdn.wavespeed.ai/image.png")
      • Multiple outputs → List of URLs (e.g., ["url1", "url2"])
      • 3D model tasks → List containing preview images + 3D model URL

    Note: Output is URL format, not tensor. Use WaveSpeedAI Preview node to convert to IMAGE/VIDEO tensors for further processing.

    WaveSpeedAI Preview 👁️

    Input:

    • input_url (ANY) - Accepts URL string, list of URLs, or text content from WaveSpeed Predictor

    Output:

    • image (IMAGE) - ComfyUI IMAGE tensor (if input is image URL)
    • video (VIDEO) - ComfyUI VIDEO tensor (if input is video URL)

    Note: Automatically detects input type and converts URLs to tensors. For 3D model tasks, only displays preview without tensor conversion.

    📚 Advanced Features

    Dynamic Parameter System

    The plugin automatically generates input fields based on each model's schema. Parameters can be:

    • Set via UI widgets (text fields, dropdowns, sliders)
    • Connected from other nodes (images, videos, audio, numbers, text)
    • Mixed (UI defaults + node connections)

    Array Parameters

    For models that accept multiple inputs (e.g., multiple reference images):

    Example: Multiple Reference Images

    image_0 → First reference
image_1 → Second reference
image_2 → Third reference

    The plugin automatically:

    • Expands array parameters to individual inputs
    • Limits to API-defined maxItems (typically 5)
    • Merges back to array format for API submission

    Size Parameter Handling

    The plugin intelligently handles size parameters:

    Enum Size (Dropdown):

    • Models like Seedance provide fixed size options
    • Example: "auto", "10241024", "10241536"
    • UI shows dropdown selector

    Range Size (Width/Height):

    • Models like Flux allow custom dimensions
    • UI shows separate width/height inputs
    • Ratio buttons for quick selection (1:1, 16:9, 9:16, etc.)
    • Each component can be connected independently

    Tensor Upload

    When you connect image/video/audio nodes, the plugin automatically:

    1. Detects the data type (image/video/audio)
    2. Converts to appropriate format (PNG/MP4/WAV)
    3. Uploads to WaveSpeed CDN
    4. Passes the URL to the API

    Supported input types:

    • ComfyUI IMAGE tensors
    • ComfyUI VIDEO tensors
    • ComfyUI AUDIO dicts
    • VHS_AUDIO callables
    • VideoFromFile objects

    Smart Output Detection

    The plugin intelligently detects output types and returns the appropriate format:

    • Images: URL or tensor (for further processing)
    • Videos: URL (for preview or download)
    • Audio: URL (for playback)
    • 3D Models: URL with .glb/.obj format (for 3D viewer)
    • Text: Plain text output

    Workflow Save/Restore

    Automatic Workflow Persistence:

    • All node states saved in workflow JSON
    • Model selections preserved
    • Parameter values restored
    • Input connections maintained

    ❓ FAQ

    <details> <summary><b>Q: How do I get an API key?</b></summary>

    Visit WaveSpeed AI and sign up. Free tier includes:

    • 100 credits per month
    • Access to all models
    • No credit card required
    </details> <details> <summary><b>Q: Why is the first load slow?</b></summary>

    The first load fetches the complete model list from WaveSpeed API (5-10 seconds). Subsequent loads use cached data and are much faster.

    </details> <details> <summary><b>Q: Why can't I find a specific model?</b></summary>
    1. Check if you're in the correct category tab
    2. Use the fuzzy search feature
    3. Model might be temporarily unavailable
    4. Check WaveSpeed AI dashboard for model status
    </details> <details> <summary><b>Q: How do I handle "Task timed out" errors?</b></summary>

    The default timeout is 30 minutes. For longer tasks:

    1. Check your network connection
    2. Try a different model
    3. Reduce output resolution/duration
    4. Contact support if issue persists
    </details> <details> <summary><b>Q: Can I use local LoRA files?</b></summary>

    No, but you can:

    1. Upload LoRA to Hugging Face
    2. Use the public URL in the plugin
    3. Or use WaveSpeed's built-in LoRA library
    </details>

    🛠️ Troubleshooting

    Common Issues

    Issue: "No API key configured"

    • Solution: Configure your API key using Settings → WaveSpeed
    • Verify key at WaveSpeed Dashboard

    Issue: "Model list not loading"

    • Solution: Check your internet connection and API key validity
    • First load may take 5-10 seconds
    • Check ComfyUI console for error messages

    Issue: "Task timeout"

    • Solution: Video generation can take up to 30 minutes
    • Check network connection
    • Try reducing output resolution/duration

    Issue: "Upload failed"

    • Solution: Check file size limits and format compatibility
    • Ensure your API key has sufficient credits

    Issue: "VideoFromFile is not JSON serializable"

    • Solution: Update to latest version (v2.0+)
    • This issue has been fixed in the new architecture

    Issue: "Cannot find WaveSpeed nodes"

    • Restart ComfyUI completely
    • Check custom_nodes/wavespeed-comfyui exists
    • Check console for error messages

    🤝 Contributing

    We welcome contributions! Here's how you can help:

    Report Issues

    • Use GitHub Issues
    • Include workflow JSON
    • Provide error messages
    • Describe expected vs actual behavior

    Submit Pull Requests

    1. Fork the repository
    2. Create a feature branch
    3. Make your changes
    4. Add tests if applicable
    5. Submit PR with clear description

    Improve Documentation

    • Fix typos
    • Add examples
    • Translate to other languages
    • Create video tutorials

    📄 License

    This project is licensed under the MIT License - see the LICENSE file for details.

    📞 Support

    Need help? We're here for you:

    Our support team is ready to assist you with any questions or issues.

    📊 Changelog

    v2.0.0

    • Complete architecture redesign with unified Predictor node
    • Support for 20+ model categories and 600+ models
    • Dynamic parameter generation from model schemas
    • Fuzzy search and category filtering
    • Smart output detection and format conversion
    • Automatic tensor upload and conversion
    • Real-time progress tracking
    • Support for long-running tasks (30-minute timeout)
    • VideoFromFile support for video-to-video models
    • Size component widget for resolution parameters
    • Workflow save/restore functionality
    • Array parameter expansion (images, loras, etc.)
    • Object array support (bbox_condition, etc.)
    <div align="center">

    Made with ❤️ by the WaveSpeed Team

    ⭐ Star us on GitHub | 🌐 Visit WaveSpeed.ai

    </div>

    Run ComfyUI workflows without the setup

    No installs, no CUDA version roulette, no GPU sitting idle on your bill. Bring a workflow and run it in the browser.

    Learn more