---
title: "Generate Heygen Video"
method: POST
path: "/api/v1/video/heygen-generate-video"
tags: ["video"]
---

# Generate Heygen Video

`POST /api/v1/video/heygen-generate-video`

Generate a video using HeyGen API.

**Video Inputs** (1-50 scenes):
- character: Avatar or Talking Photo settings (optional)
- voice: Text, Audio, or Silence voice settings (required)
- background: Color, Image, or Video background (optional)

**Character Types:**
- Avatar: avatar_id, scale (0-5), avatar_style (circle/normal/closeUp), offset, matting
- Talking Photo: talking_photo_id, scale (0-2), talking_photo_style, talking_style, expression

**Voice Types:**
- Text: voice_id, input_text, speed (0.5-1.5), pitch (-50 to 50), emotion, locale
- Audio: audio_url or audio_asset_id
- Silence: duration (1-100 seconds)

**Background Types:**
- Color: hex value (e.g., "#f6f6fc")
- Image: url or image_asset_id, fit (cover/crop/contain/none)
- Video: url or video_asset_id, play_style, fit

**Additional Options:**
- dimension: Video dimensions (default: 1280x720)
- title: Video title
- caption: Add captions (text voice only)
- callback_id: Custom callback ID
- callback_url: Dynamic callback URL
- folder_id: Output folder
- test: Test mode

Returns:
    video_id: The ID of the generated video task

## Request body

- HeygenGenerateVideoDTO
  - `video_inputs` HeygenVideoInputDTO[], required — Video inputs (1 to 50 scenes)
    - `character` union — Character configuration
      - AvatarSettingsDTO
        - `type` 'avatar' — Avatar character setting
        - `avatar_id` string, required — Avatar ID (not Avatar Group ID)
        - `scale` number — Avatar scale (0 to 5.0)
        - `avatar_style` string, nullable — Avatar style: circle, normal, closeUp
        - `offset` OffsetDTO
          - `x` number — X offset
          - `y` number — Y offset
        - `matting` boolean, nullable — Whether to do matting
        - `circle_background_color` string, nullable — Background color for circle style
      - TalkingPhotoSettingsDTO
        - `type` 'talking_photo' — Talking photo character setting
        - `talking_photo_id` string, required — Talking Photo ID
        - `scale` number — Talking Photo scale (0 to 2.0)
        - `talking_photo_style` string, nullable — Crop style: square, circle
        - `offset` OffsetDTO
          - `x` number — X offset
          - `y` number — Y offset
        - `talking_style` string, nullable — Talking style: stable, expressive
        - `expression` string, nullable — Expression style: default, happy
        - `super_resolution` boolean, nullable — Whether to enhance image
        - `matting` boolean, nullable — Whether to do matting
        - `circle_background_color` string, nullable — Background color for circle/square style
    - `voice` union, required — Voice configuration
      - TextVoiceSettingsDTO
        - `type` 'text' — Text voice setting
        - `voice_id` string, required — Voice ID
        - `input_text` string, required — Input text to be spoken
        - `speed` number, nullable — Voice speed (0.5 to 1.5)
        - `pitch` integer, nullable — Voice pitch (-50 to 50)
        - `emotion` string, nullable — Voice emotion: Excited, Friendly, Serious, Soothing, Broadcaster
        - `locale` string, nullable — Voice accent/locale (e.g., en-US, en-IN)
        - `elevenlabs_settings` ElevenLabsSettingsDTO
          - `model` string, required — ElevenLabs model (e.g., eleven_turbo_v2_5)
          - `similarity_boost` number — Similarity boost (0.0 to 1.0)
          - `stability` number — Stability (0.0 to 1.0)
          - `style` number — Style intensity (0.0 to 1.0)
      - AudioVoiceSettingsDTO
        - `type` 'audio' — Audio voice setting
        - `audio_url` string, nullable — Audio URL
        - `audio_asset_id` string, nullable — Audio asset ID
      - SilenceVoiceSettingsDTO
        - `type` 'silence' — Silence voice setting
        - `duration` number — Duration of silence (1.0 to 100.0)
    - `background` union — Background configuration
      - ColorBackgroundDTO
        - `type` 'color' — Color background setting
        - `value` string, nullable — Color value in hex format
      - ImageBackgroundDTO
        - `type` 'image' — Image background setting
        - `url` string, nullable — Image URL
        - `image_asset_id` string, nullable — Image asset ID
        - `fit` string, nullable — Image fit: cover, crop, contain, none
      - VideoBackgroundDTO
        - `type` 'video' — Video background setting
        - `url` string, nullable — Video URL
        - `video_asset_id` string, nullable — Video asset ID
        - `play_style` string, nullable — Video play style: fit_to_scene, freeze, loop, once
        - `fit` string, nullable — Video fit: cover, crop, contain, none
  - `dimension` HeygenDimensionDTO
    - `width` integer — Video width
    - `height` integer — Video height
  - `caption` boolean, nullable — Whether to add caption (only for text input)
  - `title` string, nullable — Title for the video
  - `callback_id` string, nullable — Custom ID for callback purposes
  - `folder_id` string, nullable — Video output folder destination
  - `callback_url` string, nullable — Optional callback URL for dynamic endpoints
  - `test` boolean, nullable — Test mode

## Response `200`

Successful Response

- unknown

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/brandbooster/apis/fastapi.md) · [All operations](https://skmtc.dev/brandbooster/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/brandbooster/fastapi/revisions/a9374f6fe96c/schema)