Generate an Avatar Video

All examples use the base URL https://api.hedra.com/web-app/public and require an X-API-Key header.

export HEDRA_API_KEY="your_api_key"

Avatar videos are driven by audio—the character in the image will lip-sync and move to the provided audio. Hedra Avatar (together/hedra-avatar) requires an image and audio input. Use GET /models?types=video to read its current output and input-duration limits before submitting long-form work.

Step 1: Upload your audio

The audio normally determines the video length. Omit duration_ms to follow the source audio.

# Create the asset record
curl -X POST https://api.hedra.com/web-app/public/assets \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $HEDRA_API_KEY" \
  -d '{
    "name": "avatar-audio.mp3",
    "type": "audio"
  }'

# Upload the file
curl -X POST https://api.hedra.com/web-app/public/assets/{audio_asset_id}/upload \
  -H "X-API-Key: $HEDRA_API_KEY" \
  -F "file=@/path/to/avatar-audio.mp3"

Step 2: Upload your portrait image

curl -X POST https://api.hedra.com/web-app/public/assets \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $HEDRA_API_KEY" \
  -d '{
    "name": "portrait.png",
    "type": "image"
  }'

curl -X POST https://api.hedra.com/web-app/public/assets/{image_asset_id}/upload \
  -H "X-API-Key: $HEDRA_API_KEY" \
  -F "file=@/path/to/portrait.png"

Step 3: Generate the avatar video

Use the Hedra Avatar model (together/hedra-avatar):

curl -X POST https://api.hedra.com/web-app/public/generations \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $HEDRA_API_KEY" \
  -d '{
    "type": "video",
    "model_slug": "together/hedra-avatar",
    "start_keyframe_id": "{image_asset_id}",
    "audio_id": "{audio_asset_id}",
    "generated_video_inputs": {
      "text_prompt": "A person speaking to the camera",
      "aspect_ratio": "9:16",
      "resolution": "720p"
    }
  }'

The model catalog reports output limits separately from limits on each input slot. Check both before uploading long audio.

Inline audio generation

Instead of uploading audio separately, you can generate speech inline by passing audio_generation instead of audio_id. To find a voice_id, list the available voices:

curl https://api.hedra.com/web-app/public/voices \
  -H "X-API-Key: $HEDRA_API_KEY"

See the Generate Audio guide for the full list of voice options, including voice cloning.

curl -X POST https://api.hedra.com/web-app/public/generations \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $HEDRA_API_KEY" \
  -d '{
    "type": "video",
    "model_slug": "together/hedra-avatar",
    "start_keyframe_id": "{image_asset_id}",
    "audio_generation": {
      "type": "text_to_speech",
      "voice_id": "f412c62f-e94f-41c0-bfc6-97f63289941c",
      "text": "Hello, this is a demo of inline audio generation for avatar videos."
    },
    "generated_video_inputs": {
      "text_prompt": "A person speaking to the camera",
      "aspect_ratio": "9:16",
      "resolution": "540p"
    }
  }'

Step 4: Poll for completion

Avatar videos are asynchronous. Check progress (0-1) while polling:

curl https://api.hedra.com/web-app/public/generations/{generation_id}/status \
  -H "X-API-Key: $HEDRA_API_KEY"

When status is "complete", the response includes an asset_id for the generated video.

Getting Started

Guides

API Reference

Generate an Avatar Video

Step 1: Upload your audio

Step 2: Upload your portrait image

Step 3: Generate the avatar video

Inline audio generation

Step 4: Poll for completion

​Step 1: Upload your audio

​Step 2: Upload your portrait image

​Step 3: Generate the avatar video

​Inline audio generation

​Step 4: Poll for completion

Step 1: Upload your audio

Step 2: Upload your portrait image

Step 3: Generate the avatar video

Inline audio generation

Step 4: Poll for completion