WaveSpeed AI for n8n

Powerful n8n nodes for WaveSpeed AI platform - Build multimodal AI workflows including text-to-image, image-to-video, text-to-audio, digital humans, and more.

📑 Table of Contents

• Features
• Installation
• Configuration
• Example Workflows
• Node Configuration
• Additional Resources
• Version History
• License
• Support
• Contributing

🚀 Features

1. WaveSpeed Predictor

Universal AI task execution node with dynamic model selection and intelligent parameter rendering.

Key Features:

• Multiple AI model categories with extensive model library
• Dynamic parameter loading based on selected model
• Fuzzy search support for easy model filtering
• Resource mapper for intuitive parameter configuration
• Automatic task completion with configurable polling
• Built-in retry mechanism for network errors

💡 Tip: Model list loading speed depends on your network. If experiencing slow loading, try switching to a different network or proxy.

Supported Categories:

• Text to Image, Text to Video, Text to Audio
• Image to Image, Image to Video, Image to 3D, Image to Text
• Video to Video, Audio to Video
• Video Effects, Image Effects, Image Tools
• And more...

2. WaveSpeed Upload

Upload local media files to WaveSpeed platform for use in AI workflows.

Key Features:

• Support for images, videos, and audio files
• Auto-detection of media type
• Binary data input from n8n workflows
• URL-based file download and upload
• Configurable file size and duration limits

Supported Formats:

• Images: JPG, PNG, WebP, GIF, BMP, TIFF
• Videos: MP4, AVI, MOV, WMV, FLV, WebM, MKV
• Audio: MP3, WAV, OGG, AAC, FLAC, M4A

3. WaveSpeed Loras

Configure LoRA (Low-Rank Adaptation) models to apply custom styles to image generation.

Key Features:

• Multiple LoRA models in a single node
• Adjustable scale/strength for each LoRA (0.0 - 2.0)
• Support for URL and HuggingFace model paths
• Easy integration with WaveSpeed Predictor

📦 Installation

Method 1: Via n8n Community Nodes (Recommended)

Step 1: Access n8n Settings

1. Open your n8n instance in a web browser
2. Click on your profile icon in the bottom left corner
3. Select "Settings" from the menu

Step 2: Navigate to Community Nodes

1. In the Settings sidebar, click on "Community nodes"
2. You'll see a list of installed community nodes (if any)

Step 3: Install WaveSpeed Nodes

1. Click the "Install" button in the top right
2. In the popup dialog, enter the package name: n8n-nodes-wavespeed
3. Click "Install" to confirm
4. Wait for the installation to complete (this may take 1-2 minutes)
5. You'll see a success message when installation is done

Step 4: Verify Installation

1. Close the settings panel
2. Click the "+" button to add a new node to your workflow
3. In the search box, type "wavespeed"
4. You should see three nodes:
   • WaveSpeed Predictor
   • WaveSpeed Upload
   • WaveSpeed Loras

Troubleshooting:

• If nodes don't appear, try refreshing your browser (F5 or Ctrl+R)
• If installation fails, check your n8n version (requires n8n v1.0.0 or higher)
• Ensure your n8n instance has internet access to download packages

Method 2: Via npm (For Self-Hosted n8n)

Prerequisites:

• Node.js installed (v18 or higher)
• npm or yarn package manager
• Access to your n8n installation directory

Installation Steps:

1. Navigate to your n8n directory:

   cd ~/.n8n

2. Install the package:

   npm install n8n-nodes-wavespeed

3. Restart n8n:

   # If running as a service
   sudo systemctl restart n8n
   
   # If running manually
   # Stop n8n (Ctrl+C) and start again
   n8n start

4. Verify installation:

   • Open n8n in your browser
   • Search for "wavespeed" in the node panel
   • Confirm all three nodes appear

Method 3: Via Docker

If you're running n8n in Docker, add the package to your docker-compose.yml or Dockerfile:

docker-compose.yml:

version: '3.8'
services:
  n8n:
    image: n8nio/n8n
    environment:
      - N8N_COMMUNITY_PACKAGES=n8n-nodes-wavespeed
    ports:
      - "5678:5678"
    volumes:
      - ~/.n8n:/home/node/.n8n

Then restart your container:

docker-compose down
docker-compose up -d

🔑 Configuration

Step 1: Get Your WaveSpeed API Key

Create an Account:

1. Visit WaveSpeed AI Dashboard
2. Click "Sign Up" if you don't have an account
3. Complete the registration process
4. Verify your email address

Generate API Key:

1. Log in to your WaveSpeed dashboard
2. Navigate to "API Keys" section in the sidebar
3. Click "Create New API Key" button
4. Give your key a descriptive name (e.g., "n8n Integration")
5. Click "Generate"
6. Important: Copy the API key immediately - it won't be shown again
7. Store it securely (you'll need it in the next step)

Step 2: Configure Credentials in n8n

Add WaveSpeed Credential:

1. In n8n, click on "Credentials" in the left sidebar
2. Click the "Add Credential" button (top right)
3. In the search box, type "WaveSpeed"
4. Click on "WaveSpeed API" from the results

Enter Your API Key:

1. In the credential form, you'll see an "API Key" field
2. Paste the API key you copied from WaveSpeed dashboard
3. Optionally, give this credential a custom name (e.g., "My WaveSpeed Account")
4. Click "Save" button

Test Your Credential:

1. Create a new workflow
2. Add a "WaveSpeed Predictor" node
3. Click on the "Credential to connect with" dropdown
4. Select your newly created WaveSpeed credential
5. If configured correctly, you should be able to select model categories

Troubleshooting:

• If you see "Invalid API Key" error, double-check you copied the entire key
• Ensure there are no extra spaces before or after the key
• Verify your API key hasn't been revoked in the WaveSpeed dashboard
• Check your WaveSpeed account has sufficient credits

📚 Example Workflows

We provide three ready-to-use example workflows in the example/ folder. Import them into n8n to get started quickly.

Example 1: Local File Upload

Files:

• example/1-local-file-upload/1.1 - Read From Disk.json
• example/1-local-file-upload/1.2 - Form Upload.json

Two workflows demonstrating different methods to upload local media files to WaveSpeed platform.

1.1 - Read From Disk

1.2 - Form Upload

1.1 - Read From Disk Workflow:

Start → Read/Write Files from Disk → WaveSpeed Upload → Output

What it does:

1. Read the binary file from your local disk
2. Upload to WaveSpeed platform with auto-detection
3. Return media URL and metadata for use in other workflows

1.2 - Form Upload Workflow:

n8n Form Trigger → WaveSpeed Upload → Output

What it does:

1. Create a web form for file uploads
2. Users upload files through the browser
3. Automatically upload to WaveSpeed platform
4. Return media URL and metadata

How to use (1.1 - Read From Disk):

⚠️ Important: n8n File Access Restrictions

By default, n8n only allows reading files from specific directories for security reasons. To upload local files:

1. Create the allowed directory:

   • Windows: C:\Users\YourName\.n8n-files\
   • Mac/Linux: ~/.n8n-files/

2. Place your files in this directory:

   • Example: C:\Users\YourName\.n8n-files\sample.jpg

3. Use the correct path in the Config node:

   • Windows: C:\Users\YourName\.n8n-files\sample.jpg
   • Mac/Linux: ~/.n8n-files/sample.jpg

Files outside this directory will result in "not allowed" errors.

Steps:

1. Import 1.1 - Read From Disk.json into n8n
2. Create the .n8n-files directory in your user folder
3. Copy your media file (image/video/audio) into .n8n-files
4. Open the "Read/Write Files from Disk" node
5. Update the file path with the full path to your file
6. Click "Execute Workflow"
7. Check the Output node for the uploaded media URL

How to use (1.2 - Form Upload):

1. Import 1.2 - Form Upload.json into n8n
2. Activate the workflow
3. Click on the form URL in the "n8n Form Trigger" node
4. Upload your file through the web form
5. Submit the form
6. Check the workflow execution for the uploaded media URL

---

Example 2: Scene Character Composition

File: example/2-scene-character-composition/2 - Scene Character Composition.json

An advanced workflow that generates two separate images (scene and character) and composites them together.

Workflow Steps:

Start → Config → [Generate Scene + Generate Character] → Merge → Compose Image → Output

What it does:

1. Define prompts for scene (jungle pond) and character (young boy) in Config node
2. Generate both images in parallel using text-to-image models
3. Wait for both generations to complete using Merge node
4. Composite character into scene using image-to-image model
5. Output final composed image with all intermediate results

How to use:

1. Import 2 - Scene Character Composition.json into n8n
2. Open the "Config" node
3. Customize scene_prompt and character_prompt if desired
4. Click "Execute Workflow"
5. Wait for completion (may take 1-2 minutes)
6. Check Output node for the final composed image

Result: A young boy standing in a serene jungle pond with natural lighting and realistic integration.

Use case: Create complex composite images by generating and merging multiple elements in parallel.

---

Example 3: LoRA Style Generation

File: example/3-lora-style-generation/3 - LoRA Style Generation.json

Demonstrates how to apply custom artistic styles using LoRA models.

Workflow Steps:

Start → Config → WaveSpeed Loras → Generate with LoRA → Output

What it does:

1. Configure generation prompt and LoRA model paths in Config node
2. Set up multiple LoRA models with custom scales in WaveSpeed Loras node
3. Generate styled image with LoRA effects applied
4. Output generated image with metadata and timing information

How to use:

1. Import 3 - LoRA Style Generation.json into n8n
2. Open the "Config" node
3. Update prompt with your desired image description
4. Update lora_path_1 and lora_path_2 with valid LoRA model URLs
5. Adjust lora_scale_1 and lora_scale_2 (0.0 - 2.0) for effect strength
6. Click "Execute Workflow"
7. Check Output node for the styled image

LoRA Configuration Example:

• LoRA 1: Anime style (scale: 0.8)
• LoRA 2: Watercolor effect (scale: 0.6)

Use case: Apply custom artistic styles to your AI-generated images using pre-trained LoRA models.

---

How to Import Example Workflows

1. Download the example JSON file from the example/ folder
2. In n8n, click "Workflows" in the left sidebar
3. Click "Import from File" button
4. Select the downloaded JSON file
5. The workflow will open in the editor
6. Configure your WaveSpeed API credential
7. Update any necessary parameters
8. Click "Execute Workflow" to test

🔧 Node Configuration

WaveSpeed Predictor

Required Parameters:

• Model Category - Select from available AI model categories
• Model - Choose specific model (supports fuzzy search)
• Parameters - Model-specific parameters (auto-loaded)

Optional Parameters:

• Max Wait Time - Maximum time to wait for completion (default: 5 minutes)
• Poll Interval - How often to check status (default: 5 seconds)
• Max Retries - Retry attempts for network errors (default: 20)

Note: Required parameters are shown by default. Optional parameters can be added from dropdown and are validated based on model schema.

WaveSpeed Upload

Input Type:

• File (default) - Use binary data from previous nodes
• URL - Download from URL and upload

Configuration:

• Binary Property - Default is data, specify the property name containing binary data
• Filename - Custom filename for uploaded file
• Tags - Comma-separated tags
• Max Duration - Maximum duration for audio/video (default: 600s)
• Max File Size - Maximum file size in MB (default: 500MB)
• Sample Rate - Target sample rate for audio (default: 44100Hz)
• Media Type - Auto-detect or specify: audio/image/video

WaveSpeed Loras

Configuration:

• Path - URL to LoRA file or HuggingFace model identifier
• Scale - Strength of LoRA effect (0.0 - 2.0)

Note: Add multiple LoRA configurations, each with independent path and scale. They are applied in order during generation.

📖 Additional Resources

Documentation

• WaveSpeed API Documentation - Complete API reference and guides
• n8n Documentation - Learn about n8n workflows and nodes
• n8n Community Forum - Get help from the community

Video Tutorials

• n8n Basics - Getting Started
• Working with Binary Data in n8n
• Building AI Workflows

Example Workflows

All example workflows are available in the example/ folder:

• 1-local-file-upload/
  • 1.1 - Read From Disk.json - Upload files from local disk
  • 1.2 - Form Upload.json - Upload files via web form
• 2-scene-character-composition/
  • 2 - Scene Character Composition.json - Advanced image composition
• 3-lora-style-generation/
  • 3 - LoRA Style Generation.json - LoRA styling techniques

🔄 Version History

• v1.1.0 (Current)

  • Renamed nodes for clarity: Upload, Predictor, Loras
  • Simplified architecture and improved performance
  • Enhanced parameter handling and validation
  • Better error messages and troubleshooting
  • Updated example workflows
  • Comprehensive documentation

• v1.0.3

  • Removed caching mechanism
  • Always wait for task completion
  • Improved error handling

• v1.0.1

  • Enhanced polling mechanism
  • Signal handling improvements

• v1.0.0

  • Initial release
  • Core functionality

📄 License

MIT License - see the LICENSE file for details.

🤝 Support

Need help? We're here for you:

• Email: support@wavespeed.ai
• Documentation: wavespeed.ai/docs
• GitHub Issues: github.com/WaveSpeedAI/wavespeed-n8n
• n8n Community: community.n8n.io

🌟 Contributing

We welcome contributions! Please feel free to submit issues and pull requests.

---

Made with ❤️ by WaveSpeed AI