---
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`

## Request

- Base URL: `https://api.brandbooster.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.brandbooster.ai/api/v1/video/heygen-generate-video`
- Auth: HTTP bearer

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/brandbooster-api.md) - [All operations](https://skmtc.dev/brandbooster/apis/brandbooster-api/llms.txt) - [OpenAPI document](https://skmtc.dev/brandbooster/apis/brandbooster-api/revisions/f84fc05f417b?raw)