Skip to main content

​
Step 1: Purchase a paid account

In order to use our API, you’ll need a paid subscription account. You can purchase your plans at https://www.hedra.com/plans.

​
Step 2: Register an API key

Go to your profile, click to generate an API key, and purchase API credits.

​
[Optional] Step 3: Purchase an enterprise subscription

We offer on-demand purchase packs and metered billing on the profile page, with low rate limits and without volume discount. For configurable rate limits, rates, and more, please submit a ticket via our enterpise sales form.

​
Step 4: Run the quickstart code

  • Character-3
  • Character-2 Legacy

​
Prerequisites

  • Python 3.10+
  • Git LFS (needs to be installed before cloning starter code
  • uv: A fast Python package installer and resolver. If you don’t have it, install it following the instructions

​
Clone the repository:

git clone <repository_url>
cd hedra-api-starter

​
Set up your API Key:

Create a file named .env in the project’s root directory and add the following line:
HEDRA_API_KEY=your_actual_api_key

​
Install Dependencies:

Use uv to install the required Python packages listed in pyproject.toml:
uv sync

​
Run the example

Run the main.py script using uv run, providing the necessary arguments:
uv run main.py \
    --aspect_ratio ratio \
    --resolution res \
    --text_prompt "<your_prompt>" \
    --audio_file <path/to/audio.mp3 \
    --image <path/to/image.png
Command-Line Arguments:* --aspect_ratio (Required): Aspect ratio for the video. Choices: 16:9, 9:16, 1:1.* --resolution (Required): Resolution for the video. Choices: 540p, 720p.* --text_prompt (Required): Text prompt describing the desired video content (enclose in quotes if it contains spaces).* --audio_file (Required): Path to the input audio file (e.g., .mp3, .wav).* --image (Required): Path to the input image file (e.g., .png, .jpg).* --duration (Optional): Desired duration for the video in seconds (float). Defaults to the length of the audio if not specified.* --seed (Optional): Seed for the generation process (integer). Allows for reproducible results if the model and other parameters are the same.Example:
uv run main.py \
    --aspect_ratio 9:16 \
    --resolution 540p \
    --text_prompt "A woman talking at the camera" \
    --audio_file assets/audio.wav \
    --image assets/9_16.jpg
The script will:
  1. Upload the image and audio assets.
  2. Submit the generation request to the Hedra API.
  3. Poll the API for the status of the generation job.
  4. Once complete, download the generated video file (e.g., asset_id.mp4) to the project directory.
Check the console output for progress and the final video file location.
⌘I