Create Realistic AI Avatar Videos with Hunyuan Heygen Actions

24 Apr 2025
Create Realistic AI Avatar Videos with Hunyuan Heygen Actions

In today's digital landscape, creating realistic AI avatars has become increasingly important for applications in entertainment, education, and customer engagement. The Hunyuan Heygen Woman 2 API provides a powerful set of Cognitive Actions designed to generate stunning AI avatar videos. With its pre-built actions, developers can easily integrate avatar creation into their applications, enhancing user experiences and providing a new level of interactivity.

Prerequisites

Before you begin using the Cognitive Actions in the Hunyuan Heygen API, you'll need the following:

  • API Key: You will need to obtain an API key from the Cognitive Actions platform to authenticate your requests. This key will be passed in the headers of your API calls.
  • Setup: Ensure you have access to the necessary libraries for making HTTP requests, such as requests in Python.

Cognitive Actions Overview

Generate Finetuned Heygen AI Avatar Video

This action allows you to create a finely-tuned AI avatar video using the HunyuanVideo technology, enabling you to configure various video parameters such as resolution, frame rate, and flow continuity. This flexibility enhances the realism of avatar video creation.

Input

The input schema for this action is a JSON object that includes the following properties:

  • seed (integer, optional): A seed value for reproducibility of results.
  • steps (integer, optional): The number of diffusion steps to perform, ranging from 1 to 150 (default: 50).
  • width (integer, optional): The width of the generated video in pixels (default: 640, range: 64-1536).
  • height (integer, optional): The height of the generated video in pixels (default: 360, range: 64-1024).
  • prompt (string, required): A descriptive text prompt guiding the video scene creation.
  • loraUrl (string, optional): URL pointing to a LoRA file or Hugging Face repository.
  • flowShift (integer, optional): A factor controlling video continuity (default: 9, range: 0-20).
  • frameRate (integer, optional): Frames displayed per second (default: 24, range: 1-60).
  • crfQuality (integer, optional): Quality of H264 encoding (default: 19, range: 0-51).
  • forceOffload (boolean, optional): Determines if model layers should be offloaded to CPU (default: true).
  • loraStrength (number, optional): Influence strength of the LoRA model (default: 1).
  • guidanceScale (number, optional): Balance between adherence to the prompt and model style (default: 6).
  • weightFileUri (string, optional): URI pointing to LoRA weights.
  • numberOfFrames (integer, optional): Total number of frames in the video (default: 85, range: 1-300).
  • denoiseStrength (number, optional): Strength of noise application (default: 1).

Example Input:

{
  "steps": 30,
  "width": 960,
  "height": 544,
  "prompt": "HGW2 woman sitting on a beige couch in a well-decorated room. She is wearing a light-colored, long-sleeved turtleneck top and has long, straight brown hair. The couch is adorned with several throw pillows, each with a black and white geometric pattern. The background includes a wooden chair with a yellow cushion, a wooden side table, and a large mirror with a wooden frame. The room has a warm and cozy atmosphere, with soft lighting and a comfortable ambiance. The woman appears to be speaking or presenting something, as she is looking directly at the camera with a neutral expression",
  "loraUrl": "",
  "flowShift": 9,
  "frameRate": 20,
  "crfQuality": 19,
  "forceOffload": true,
  "loraStrength": 0.9,
  "guidanceScale": 6,
  "numberOfFrames": 49,
  "denoiseStrength": 1
}

Output

Upon successful execution, the action typically returns a URL pointing to the generated avatar video.

Example Output:

https://assets.cognitiveactions.com/invocations/6f1b826d-9a1b-4f63-838f-b76c578c2e94/cdacb43d-64e0-4ef4-9e84-11e3fb70fc02.mp4

Conceptual Usage Example (Python)

Here’s how you might call this action in Python:

import requests
import json

# Replace with your Cognitive Actions API key and endpoint
COGNITIVE_ACTIONS_API_KEY = "YOUR_COGNITIVE_ACTIONS_API_KEY"
COGNITIVE_ACTIONS_EXECUTE_URL = "https://api.cognitiveactions.com/actions/execute" # Hypothetical endpoint

action_id = "0563ac1e-a628-4f48-8c9e-dbb28e876d19" # Action ID for Generate Finetuned Heygen AI Avatar Video

# Construct the input payload based on the action's requirements
payload = {
    "steps": 30,
    "width": 960,
    "height": 544,
    "prompt": "HGW2 woman sitting on a beige couch in a well-decorated room...",
    "loraUrl": "",
    "flowShift": 9,
    "frameRate": 20,
    "crfQuality": 19,
    "forceOffload": True,
    "loraStrength": 0.9,
    "guidanceScale": 6,
    "numberOfFrames": 49,
    "denoiseStrength": 1
}

headers = {
    "Authorization": f"Bearer {COGNITIVE_ACTIONS_API_KEY}",
    "Content-Type": "application/json"
}

try:
    response = requests.post(
        COGNITIVE_ACTIONS_EXECUTE_URL,
        headers=headers,
        json={"action_id": action_id, "inputs": payload} # Hypothetical structure
    )
    response.raise_for_status() # Raise an exception for bad status codes (4xx or 5xx)

    result = response.json()
    print("Action executed successfully:")
    print(json.dumps(result, indent=2))

except requests.exceptions.RequestException as e:
    print(f"Error executing action {action_id}: {e}")
    if e.response is not None:
        print(f"Response status: {e.response.status_code}")
        try:
            print(f"Response body: {e.response.json()}")
        except json.JSONDecodeError:
            print(f"Response body: {e.response.text}")

In this example, replace YOUR_COGNITIVE_ACTIONS_API_KEY with your actual API key. The payload variable is structured according to the action's input schema, and the action ID is specified in the request.

Conclusion

The Hunyuan Heygen Woman 2 Cognitive Actions provide developers with an exceptional opportunity to create realistic AI avatar videos effortlessly. By leveraging the flexibility and power of these actions, you can enhance user engagement in your applications and explore a range of creative possibilities. Start integrating these actions today and bring your avatar experiences to life!

← Back to All Articles