Readme

Hunyuan Video - AI-Powered Video Generation

Transform static prompts into dynamic, high-quality videos with Hunyuan Video. This powerful open-source AI model enables developers and creators to generate engaging video content through a simple API interface.

Overview

Hunyuan Video is an Open video generation model with high visual quality, motion diversity, text-video alignment, and generation stability. This endpoint generates videos from text descriptions through the fal.ai platform. Whether you're building creative tools, content applications, or enterprise solutions, you can easily integrate video generation into your workflow.

Getting Started

Getting up and running with Hunyuan Video takes just a few minutes. Here's how to begin:

First, install your preferred SDK:

For JavaScript/TypeScript:

npm install --save @fal-ai/client

For Python:

pip install fal-client

Configure your authentication credentials:

JavaScript:

import { fal } from "@fal-ai/client";
fal.config({
  credentials: "YOUR_FAL_KEY_HERE"
});

Python:

import fal_client as fal
import os
os.environ["FAL_KEY"] = "YOUR_FAL_KEY_HERE"

Basic Usage

Generate your first video with this simple example:

JavaScript:

import { fal } from "@fal-ai/client";

const result = await fal.subscribe("fal-ai/hunyuan-video", {
  input: {
    prompt: "A stylish woman walks down a Tokyo street filled with warm glowing neon and animated city signage. She wears a black leather jacket, a long red dress, and black boots, and carries a black purse."
  }
});

console.log(result.data.video.url);

Python:

import fal_client as fal

result = fal.subscribe("fal-ai/hunyuan-video", {
    "prompt": "A stylish woman walks down a Tokyo street filled with warm glowing neon and animated city signage. She wears a black leather jacket, a long red dress, and black boots, and carries a black purse."
})

print(result.video.url)

API Parameters

Required Parameters

• prompt: The text prompt to generate the video from

Optional Parameters

• num_inference_steps: Number of inference steps (default: 30). Lower gets faster results, higher gets better results
• seed: Seed for reproducible results (default: random)
• pro_mode: Enable pro mode with 55 steps for higher quality (default: false). Costs 2x more billing units
• aspect_ratio: Video aspect ratio - "16:9" or "9:16" (default: "16:9")
• resolution: Video resolution - "480p", "580p", or "720p" (default: "720p")
• num_frames: Number of frames - 129 or 85 (default: 129)
• enable_safety_checker: Enable content safety checking (default: false)

Input Example

{
  "prompt": "A stylish woman walks down a Tokyo street filled with warm glowing neon and animated city signage. She wears a black leather jacket, a long red dress, and black boots, and carries a black purse.",
  "num_inference_steps": 30,
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "num_frames": 129,
  "enable_safety_checker": true
}

Advanced Implementation

For production applications, consider this more robust implementation:

import { fal } from "@fal-ai/client";

async function generateVideo(prompt, options = {}) {
  try {
    const result = await fal.subscribe("fal-ai/hunyuan-video", {
      input: {
        prompt,
        num_inference_steps: options.steps || 30,
        pro_mode: options.proMode || false,
        aspect_ratio: options.aspectRatio || "16:9",
        resolution: options.resolution || "720p",
        num_frames: options.frames || 129,
        enable_safety_checker: options.safetyCheck || false
      }
    });
    
    return result;
  } catch (error) {
    console.error("Video generation failed:", error);
    throw new Error("Failed to generate video");
  }
}

Queue Management

For production applications, use the queue API:

// Submit request
const { request_id } = await fal.queue.submit("fal-ai/hunyuan-video", {
  input: {
    prompt: "A stylish woman walks down a Tokyo street filled with warm glowing neon and animated city signage. She wears a black leather jacket, a long red dress, and black boots, and carries a black purse."
  },
  webhookUrl: "https://optional.webhook.url/for/results"
});

// Check status
const status = await fal.queue.status("fal-ai/hunyuan-video", {
  requestId: request_id,
  logs: true
});

// Get result when complete
const result = await fal.queue.result("fal-ai/hunyuan-video", {
  requestId: request_id
});

Output Format

{
  "video": {
    "url": "https://v3.fal.media/files/kangaroo/y5-1YTGpun17eSeggZMzX_video-1733468228.mp4",
    "content_type": "video/mp4",
    "file_name": "generated_video.mp4",
    "file_size": 2048576
  },
  "seed": 1234567890
}

Best Practices

To get the most out of Hunyuan Video:

• Write clear, detailed prompts that specify both content and style
• Include temporal elements in your prompts to guide video progression
• Monitor processing time (approximately 4 minutes per generation)
• Cache generated videos when possible to optimize performance
• Implement error handling for API calls
• Use pro mode for higher quality when extra time and cost are acceptable

Technical Specifications

Model Architecture:

• Type: Open-source video generation model by Tencent
• Parameters: 13 billion parameter diffusion transformer
• Processing Time: ~4 minutes average
• Commercial Use: Free for commercial use

Performance:

• Video Length: 5 seconds (typical output)
• Supported Resolutions: 480p, 580p, 720p
• Aspect Ratios: 16:9, 9:16
• Frame Options: 85 or 129 frames
• Quality Modes: Standard (35 steps) and Pro (55 steps)

Model Variants

Related Hunyuan Video models available:

• fal-ai/hunyuan-video: Text-to-video generation (main model)
• fal-ai/hunyuan-video/video-to-video: Video-to-video transformation
• fal-ai/hunyuan-video-image-to-video: Image-to-video generation
• fal-ai/hunyuan-video-img2vid-lora: Image-to-video with custom LoRA
• fal-ai/hunyuan-video-lora-training: LoRA training for customization
• fal-ai/hunyuan-custom: Custom video generation with identity consistency

Performance Optimization

For optimal performance:

• Keep your prompts focused and specific
• Implement proper error handling and retries
• Cache successful generations where appropriate
• Monitor API usage through the fal.ai dashboard
• Test different prompt structures to optimize results
• Consider using pro mode only when higher quality is essential

Pricing and Usage

• Cost: $0.4 per video
• Pro Mode: Costs 2x more billing units for higher quality
• Processing Time: This generation takes approximately 4m
• Commercial Use: Free for commercial use (open-source model)
• Billing: Pay only for successful generations

Support and Resources

Access comprehensive support through:

• Documentation: docs.fal.ai
• API Reference: fal.ai/models/fal-ai/hunyuan-video/api
• Model Gallery: Browse all models at fal.ai/models
• Support: support@fal.ai

Get started with Hunyuan Video today and bring your creative visions to life through dynamic, AI-generated video content.