# Generate Video

Create a video from an avatar or image with Avatar IV. Supports photo avatars, digital twins, and direct image input. The video is generated asynchronously — poll status via GET /v2/videos/{video_id}.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "heygen-api",
    "version": "4.0.8"
  },
  "servers": [
    {
      "url": "https://api.heygen.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "apiKey",
        "name": "x-api-key",
        "in": "header",
        "x-default": "<your-api-key>"
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/v2/videos": {
      "post": {
        "description": "",
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "video_id": {
                      "type": "string",
                      "description": "Unique identifier for the created video."
                    },
                    "status": {
                      "type": "string",
                      "description": "Initial video status (e.g. 'waiting')."
                    }
                  },
                  "required": [
                    "video_id",
                    "status"
                  ]
                }
              }
            }
          }
        },
        "parameters": [],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "avatar_id": {
                    "type": "string",
                    "description": "HeyGen avatar ID (photo avatar or video avatar). Mutually exclusive with image_url and image_asset_id."
                  },
                  "image_url": {
                    "type": "string",
                    "description": "\"Public URL of an image to animate. Mutually exclusive with avatar_id and image_asset_id."
                  },
                  "image_asset_id": {
                    "type": "string",
                    "description": "HeyGen asset ID of an uploaded image. Mutually exclusive with avatar_id and image_url."
                  },
                  "script": {
                    "type": "string",
                    "description": "Text script for the avatar to speak. Requires voice_id."
                  },
                  "voice_id": {
                    "type": "string",
                    "description": "Voice ID for text-to-speech or speech-to-speech. Required when script is provided."
                  },
                  "audio_url": {
                    "type": "string",
                    "default": "",
                    "description": "Public URL of an audio file to lip-sync. Mutually exclusive with script."
                  },
                  "audio_asset_id": {
                    "type": "string",
                    "description": "HeyGen asset ID of an uploaded audio file. Mutually exclusive with script."
                  },
                  "title": {
                    "type": "string",
                    "description": "Display title for the video in the HeyGen dashboard."
                  },
                  "resolution": {
                    "type": "string",
                    "default": "1080p",
                    "enum": [
                      "1080p",
                      "720p"
                    ],
                    "description": "Output video resolution."
                  },
                  "aspect_ratio": {
                    "type": "string",
                    "default": "16:9",
                    "enum": [
                      "16:9",
                      "9:16"
                    ],
                    "description": "Output video aspect ratio."
                  },
                  "motion_prompt": {
                    "type": "string",
                    "description": "Natural-language prompt controlling avatar body motion. Photo avatars only"
                  },
                  "expressiveness": {
                    "type": "string",
                    "enum": [
                      "low",
                      "medium",
                      "high"
                    ],
                    "description": "Avatar expressiveness level: 'high', 'medium', or 'low'. Photo avatars only. Defaults to 'low' when omitted."
                  },
                  "remove_background": {
                    "type": "boolean",
                    "description": "Remove the avatar background. Video avatars must be trained with matting enabled.",
                    "default": "false"
                  },
                  "background": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "description": "Background type. 'color' uses a solid hex color; 'image' uses an image from url or asset_id.",
                        "enum": [
                          "color",
                          "image"
                        ]
                      },
                      "value": {
                        "type": "string",
                        "description": "Hex color code (e.g. '#ff0000'). Required when type is 'color'."
                      },
                      "url": {
                        "type": "string",
                        "description": "URL of the background image. Used when type is 'image'. Mutually exclusive with asset_id."
                      },
                      "asset_id": {
                        "type": "string",
                        "description": "HeyGen asset ID of the background image. Used when type is 'image'. Mutually exclusive with url."
                      }
                    },
                    "description": "Background settings for the video.",
                    "required": [
                      "type"
                    ]
                  },
                  "voice_settings": {
                    "type": "object",
                    "properties": {
                      "speed": {
                        "type": "number",
                        "default": "1.0",
                        "description": "Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed)."
                      },
                      "pitch": {
                        "type": "number",
                        "description": "Pitch adjustment in semitones. -50 to +50.",
                        "default": "0.0"
                      },
                      "locale": {
                        "type": "string",
                        "description": "Locale/accent hint for multi-lingual voices (e.g. 'en-US')."
                      }
                    },
                    "description": "Voice tuning parameters (speed, pitch, locale)."
                  }
                }
              }
            }
          }
        },
        "operationId": "post_v2-videos"
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```