PiAPI Hunyuan Image to Video icon

PiAPI Hunyuan Image to Video

Generate videos from images using PiAPI Hunyuan

Overview

This node generates videos from images using the PiAPI Hunyuan service. It transforms a single input image into a video by applying one of two available image-to-video transformation methods, guided by a text prompt. The node supports loading the source image either from a URL or from binary data within the workflow.

Common scenarios for this node include:

  • Creating short video clips from static images with smooth motion effects.
  • Enhancing visual storytelling by animating images based on descriptive prompts.
  • Generating video content for social media or marketing campaigns where dynamic visuals are needed but only static images are available.

Practical example:

  • You provide an image URL and a prompt describing the desired animation style. The node processes the image to produce a video that visually follows the prompt, outputting a video file ready for further use or sharing.

Properties

Name Meaning
Task Type Type of image-to-video transformation:
- Image to Video Concat: Generate videos based on images for better movement (20 steps, 85 FPS)
- Image to Video Replace: Generate videos following the guiding image better (20 steps, 85 FPS)
Prompt Text prompt to guide the video generation
Image Source Where to get the image from:
- URL: Load image from URL
- Binary Data: Use image from binary field
Image URL URL of the image to transform into a video (required if Image Source is URL)
Binary Property Name of the binary property containing the image (required if Image Source is Binary Data)
Aspect Ratio Aspect ratio of the generated video:
- 16:9 (Landscape, 544x960)
- 9:16 (Portrait, 960x544)
- 1:1 (Square, 720x720)
Wait for Completion Whether to wait for the task to complete before returning (boolean)

Output

The node outputs JSON data containing information about the created video generation task. The main output fields include:

  • task_id: Identifier of the video generation task.
  • Other task-related metadata returned by the API, including status and result details.

If the "Wait for Completion" option is enabled, the node waits until the video generation task finishes and returns the final task data, which may include URLs or references to the generated video.

The node does not directly output binary video data; instead, it provides metadata and task results in JSON format.

Dependencies

  • Requires an API key credential for the PiAPI Hunyuan service.
  • Uses the PiAPI HTTP API endpoint /api/v1/task to submit video generation tasks.
  • The node depends on n8n's HTTP request helper functions to download images and communicate with the external API.
  • If using image URLs, the node downloads the image data internally.
  • If using binary data, the node reads the image from the specified binary property in the input item.

Troubleshooting

  • Invalid Image URL: If the provided image URL is malformed or unreachable, the node throws an error indicating the URL is invalid or the image could not be downloaded. Verify the URL correctness and network accessibility.
  • Missing Binary Data: When using binary data as the image source, if the specified binary property does not exist or contains no data, the node will throw an error. Ensure the binary property name matches exactly and that the previous node provides valid binary image data.
  • API Errors: If the PiAPI service returns an error response, the node surfaces the error message. Common causes include invalid API credentials, exceeding rate limits, or malformed requests. Check your API key validity and usage limits.
  • Timeouts or Long Processing Times: If "Wait for Completion" is enabled, the node waits for the task to finish, which might take time depending on server load. Consider disabling this option if immediate continuation is preferred.
  • Continue On Fail: If enabled, the node will continue processing subsequent items even if some fail, returning error messages in the output JSON.

Links and References

Discussion