Package Information
Documentation
n8n-nodes-viffly
This package provides a production-oriented n8n community node for Viffly, an AI content production platform for videos, images, reels, thumbnails, and media post-production.
The node uses Viffly API keys, supports n8n expressions and multiple input items, normalizes relative media URLs, accepts binary media, and can poll asynchronous jobs until their outputs are ready.
Features
- Generate AI video from text or an image with LTX, Wan, and managed Viffly models.
- Generate AI images, including saved-character identity references.
- Write or rewrite narration scripts in multiple languages.
- Create smart thumbnails from a URL or n8n binary input.
- Reframe, clean audio, remove silence, watermark, and create slideshows.
- Render a complete reel from binary narration audio and remote media.
- Read account balances, pricing, saved characters, character usage, and the video library.
- Call newly released Viffly endpoints with the Custom API Call resource.
- Submit long-running jobs without waiting, or poll them inside the node with configurable intervals and timeouts.
Installation
n8n self-hosted interface
- Open Settings → Community Nodes.
- Select Install.
- Enter
n8n-nodes-viffly. - Accept the community-node warning and select Install.
- Open a workflow and search for Viffly.
Only an n8n instance owner or administrator can install community packages.
Manual self-hosted installation
Use this method for queue mode or a custom n8n image:
mkdir -p ~/.n8n/nodes
cd ~/.n8n/nodes
npm install n8n-nodes-viffly
Restart every n8n main and worker process after installation. In queue mode, the package must be present in the same location and version on all processes.
Credentials
- Sign in to Viffly.
- Open Developer → API Keys.
- Create a key with only the scopes required by the workflow.
- Copy the
vf_...secret when Viffly displays it. The full secret is shown once. - In n8n, create a Viffly API credential and paste the secret.
- Keep the default Base URL,
https://viffly.app, unless Viffly has provided a different deployment URL.
Viffly programmatic API access requires a Business, Agency, or Admin account. The credential test calls /api/me, so the key needs the credits scope for the test itself.
Scope mapping
| Viffly scope | Node resources |
|---|---|
generate |
AI Video, Media Tool, Reel, Thumbnail |
ai_images |
AI Image, Character |
ai_script |
AI Script |
videos |
Video |
credits |
Account profile and credential test |
The Account credit-cost and AI-video pricing endpoints are public, but the node still uses the configured credential consistently. A Custom API Call needs the scope associated with its target endpoint.
Resources and operations
| Resource | Operations |
|---|---|
| Account | Get Profile, Get Credit Costs, Get Video Pricing |
| AI Image | Generate, Get |
| AI Script | Generate or rewrite narration |
| AI Video | Generate, Get |
| Character | Get Many, Get Usage |
| Media Tool | Auto Cut, Clean Audio, Create Slideshow, Get, Reframe, Watermark |
| Reel | Create |
| Thumbnail | Generate, Get |
| Video | Get Many |
| Custom API Call | Call any JSON Viffly /api/ route allowed by the key |
Common workflows
Generate and wait for an AI video
- Add a Viffly node and select AI Video → Generate.
- Select Text to Video or Image to Video.
- Set the model, prompt, and quality tier.
- For image-to-video, provide an HTTPS URL or the name of an incoming binary field.
- Keep Wait for Completion enabled to receive the final status and absolute output URL.
For high-volume workflows, disable Wait for Completion, store the returned job_id, and use AI Video → Get in a later execution. This avoids keeping an n8n worker occupied while rendering.
Generate thumbnails from binary video
- Download or read a video into an n8n binary field, usually
data. - Select Thumbnail → Generate and choose Binary Data.
- Choose output formats, variants, and visual mode.
- Keep Wait for Completion enabled to receive the
outputsarray.
Create a full reel
The Reel resource expects narration audio in an incoming n8n binary field. Add remote image and video assets in Media URLs as a JSON array. Viffly waits for the render and returns its video URL.
Asynchronous jobs
AI Image, AI Video, Thumbnail, and Media Tool operations use Viffly's submit-and-poll APIs. When Wait for Completion is enabled, the node:
- submits the job;
- reads the returned job ID;
- polls at the configured interval;
- stops on
done,completed,succeeded, orsuccess; - raises an actionable n8n error on failed or cancelled jobs;
- tells you to use the matching Get operation if the configured timeout is reached.
Viffly paths such as /videos/output.mp4 are converted to absolute URLs using the credential Base URL.
Error handling
The node maps HTTP responses to n8n API errors and includes the input item index. Common status codes are:
| Status | Meaning |
|---|---|
400 |
Invalid field, source URL, model, or generation mode |
401 |
Invalid, expired, or revoked API key |
402 |
Insufficient Viffly credits |
403 |
Missing key scope or required plan |
404 |
Job or resource not found |
429 |
API key rate limit exceeded; honor the Retry-After header |
5xx |
Viffly or an upstream generation provider could not complete the request |
Enable Continue On Fail in n8n to emit an error item and continue processing the remaining input items.
Compatibility
- Node.js 22.22 or newer for development and publishing.
- n8n Community Nodes API version 1.
- Viffly API access with the appropriate account plan and key scopes.
- No runtime npm dependencies.
Development
npm install
npm run lint
npm run build
npm run dev
The package uses the official @n8n/node-cli strict configuration. See PUBLISHING.md for the release and verification process.
Security
Store Viffly keys only in n8n credentials. Use least-privilege scopes, set an expiration date and per-key rate limit, and rotate any key exposed in logs or workflow JSON. See SECURITY.md for private reporting.