Create Video

cURL

curl --request POST \
  --url https://api.heygen.com/v3/videos \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '\n{\n  "type": "<string>",\n  "avatar_id": "<string>",\n  "title": "<string>",\n  "resolution": "4k",\n  "aspect_ratio": "16:9",\n  "background": {\n    "type": "color",\n    "value": "<string>",\n    "url": "<string>",\n    "asset_id": "<string>"\n  },\n  "remove_background": true,\n  "callback_url": "<string>",\n  "callback_id": "<string>",\n  "watermark": {\n    "image": {\n      "type": "<string>",\n      "url": "<string>"\n    }\n  },\n  "caption": {\n    "file_format": "srt",\n    "style": "default"\n  },\n  "output_format": "mp4",\n  "script": "<string>",\n  "voice_id": "<string>",\n  "audio_url": "<string>",\n  "audio_asset_id": "<string>",\n  "voice_settings": {\n    "speed": 1,\n    "pitch": 0,\n    "volume": 1,\n    "locale": "<string>",\n    "engine_settings": {\n      "engine_type": "<string>",\n      "model": "eleven_multilingual_v2",\n      "similarity_boost": 0.5,\n      "stability": 0.5,\n      "style": 0.5,\n      "use_speaker_boost": true\n    }\n  },\n  "motion_prompt": "<string>",\n  "expressiveness": "high"\n}\n'  

Response

Successful Response

{
  "data": {
    "video_id": "<string>",
    "status": "<string>",
    "output_format": "mp4"
  }
}

Authorizations

ApiKeyAuthBearerAuth

• x-api-key
• type: string
• location: header
• required
• Description: HeyGen API key. Obtain from your HeyGen dashboard.

Body

CreateVideoFromAvatar

• Type: string

  • required
  • Must be 'avatar' for avatar-based video creation.
  • Allowed value: "avatar"

• avatar_id: string

  • required
  • HeyGen avatar ID (video avatar or photo avatar look ID).

• title: string | null

  • Display title for the video in the HeyGen dashboard.

• resolution: enum<string> | null

  • Output video resolution.
  • Available options: 4k, 1080p, 720p

• aspect_ratio: enum<string> | null

  • Output video aspect ratio.
  • Available options: 16:9, 9:16

• background:
  BackgroundSetting · object

• remove_background: boolean | null

  • Remove the avatar background. Video avatars must be trained with matting enabled.

• callback_url: string | null

  • Webhook URL to receive a POST notification when the video is ready.

• callback_id: string | null

  • Caller-defined identifier echoed back in the webhook payload.

• watermark: WatermarkInput · object

  • Custom watermark image to overlay on the video.

• caption: CaptionSetting · object

  • Caption generation settings.

• output_format: enum<string>

  • default: mp4
  • Output container.
  • Available options: mp4, webm

• script: string | null

  • Text script for the avatar to speak.

• voice_id: string | null

  • Voice ID for text-to-speech.

• audio_url: string | null

  • Public URL of an audio file to lip-sync.

• audio_asset_id: string | null

  • HeyGen asset ID of an uploaded audio file.

• voice_settings: VoiceSettingsInput · object

• motion_prompt: string | null

  • Natural-language prompt controlling avatar body motion.

• expressiveness: enum<string> | null

  • Avatar expressiveness level.
  • Available options: high, medium, low.