Overview
This node generates a video based on a text prompt and a reference image of a human face using the Hailuo API. It is designed to create personalized videos where the subject's appearance is derived from the provided image, and the content or action in the video is guided by the text prompt.
Common scenarios include:
- Creating custom avatar videos for marketing or social media.
- Generating dynamic video content featuring a specific person’s likeness.
- Producing AI-driven video presentations or storytelling with a human face.
For example, you could input a description like "A person smiling and waving" along with a photo URL of a face, and the node will generate a video showing that person performing the described action.
Properties
| Name | Meaning |
|---|---|
| Text Prompt | Text prompt describing the desired video content (max 2000 characters). |
| Reference Image URL | URL of a JPG or PNG image containing a human face (300-4096px, aspect ratio between 2:5 and 5:2, max 10MB). |
| Expand Prompt | Boolean option to expand the input prompt automatically by adding more descriptive details. |
| Wait for Completion | Boolean option to wait until the video generation task completes before returning output. |
| Maximum Retries | Number of times to check the status of the video generation task if waiting for completion (shown only if waiting enabled). |
| Retry Interval (ms) | Time in milliseconds to wait between each status check when waiting for completion (shown only if waiting enabled). |
Output
The node outputs JSON data containing information about the video generation task:
- If Wait for Completion is disabled, the output JSON contains immediate response data from the API about the submitted task, including a task ID and initial status.
- If Wait for Completion is enabled, the node polls the task status until completion or retry limit is reached, then outputs the final task result JSON, which includes the generated video details such as URLs or metadata.
No binary data output is produced directly by this node; all results are returned as JSON.
Dependencies
- Requires an API key credential for the Hailuo-related service (referred generically as an API key credential).
- Uses the Hailuo API endpoint
/api/v1/taskto submit video generation tasks. - The node relies on helper functions (
piApiRequestandwaitForTaskCompletion) from a shared module to handle API requests and polling logic. - Network access to the reference image URL must be available for the API to fetch the image.
Troubleshooting
- Invalid Image URL or Format: Ensure the reference image URL points to a valid JPG or PNG image with correct dimensions and aspect ratio. The API may reject images outside the specified size or format limits.
- Prompt Too Long: The text prompt must not exceed 2000 characters; otherwise, the API might return an error.
- API Authentication Errors: Verify that the API key credential is correctly configured and has necessary permissions.
- Timeouts When Waiting for Completion: If the video generation takes longer than expected, consider increasing the maximum retries or retry interval.
- Network Issues: Ensure stable internet connectivity for both n8n and the API endpoints.
- Error Handling: If the node is set to continue on failure, errors will be included in the output JSON under an
errorfield instead of stopping execution.
Links and References
- Hailuo API Documentation (replace with actual URL if available)
- General guidance on preparing images for AI video generation services.
- Best practices for writing effective text prompts for video generation.