--- title: "Create Video Batch" method: POST path: "/v3/videos/batches" tags: ["Batches"] --- # Create Video Batch `POST /v3/videos/batches` Submit up to 100 video creation payloads in one request and return a batch id immediately. Videos are created asynchronously; poll GET /v3/videos/batches/{batch_id} for per-item video ids and statuses. ## Headers - `Idempotency-Key` string ## Request body - CreateVideoBatchRequest - `title` string, nullable — Display name for the batch, shown in the HeyGen app. - `callback_url` string, nullable — Webhook URL invoked once when every item in the batch reaches a terminal state. - `videos` union[], required — Video creation requests, identical in shape to POST /v3/videos (avatar / image / cinematic_avatar). Max 100 per batch. - union - CreateVideoFromAvatar — Create a video from a HeyGen avatar (video or photo avatar). Provide an avatar_id to use a previously created avatar. Supports all avatar types: studio_avatar, digital_twin, and photo_avatar. Optionally set ``engine`` to select Avatar V for eligible avatars; when omitted, the server defaults to Avatar IV. - `title` string, nullable — Display title for the video in the HeyGen dashboard. - `resolution` '4k' | '1080p' | '720p' — Output video resolution. - `aspect_ratio` '16:9' | '9:16' | '4:5' | '5:4' | '1:1' | 'auto', nullable — Output video aspect ratio. - ``16:9`` / ``9:16``: classic landscape / portrait. - ``4:5`` / ``5:4`` / ``1:1``: social-media-friendly ratios. Output is short-edge anchored to the requested resolution (e.g. ``1080p`` 1:1 → 1080x1080, ``1080p`` 4:5 → 1080x1350). - ``auto``: preserve the source's aspect ratio. The dimensions are derived from the avatar's source frames (``avatar_id``) or the uploaded image (``image_url`` / ``image_asset_id``), short-edge anchored to the requested resolution and capped at the tier's long edge. Falls back to ``16:9`` when source dimensions can't be read. - `fit` 'contain' | 'cover' — How the avatar is scaled to the output canvas. - `background` BackgroundSetting — Background configuration for the generated video. - `type` 'color' | 'image', required — Background type. 'color' uses a solid hex color; 'image' uses an image from url or asset_id. - `value` string, nullable — Hex color code (e.g. '#ff0000'). Required when type is 'color'. - `url` string, nullable — URL of the background image. Used when type is 'image'. Mutually exclusive with asset_id. - `asset_id` string, nullable — HeyGen asset ID of the background image. Used when type is 'image'. Mutually exclusive with url. - `remove_background` boolean, nullable — Remove the avatar background. Video avatars must be trained with matting enabled. - `callback_url` string, nullable — Webhook URL to receive a POST notification when the video is ready. - `callback_id` string, nullable — Caller-defined identifier echoed back in the webhook payload. - `watermark` object, nullable — Watermark configuration for video creation. - `image` union, required — Image asset to use as the watermark overlay (PNG or JPEG). - AssetUrl — Asset input via publicly accessible HTTPS URL. - … - AssetId — Asset input via HeyGen asset ID from the asset upload endpoint. - … - AssetBase64 — Asset input via base64-encoded content. - … - `scale` number — Scale multiplier for the watermark image. 1.0 renders at native size. - `opacity` number — Watermark opacity. 0.0 is fully transparent, 1.0 is fully opaque. - `placement` WatermarkPlacement — Watermark placement configuration. - `position` 'top_left' | 'top_right' | 'bottom_left' | 'bottom_right' — Anchor corner for a custom watermark overlay. - `offset_x` number, nullable — Fine-tune horizontal position. Fraction of frame width; 0.05 shifts 5% rightward, -0.05 shifts 5% leftward. - `offset_y` number, nullable — Fine-tune vertical position. Fraction of frame height; 0.05 shifts 5% downward, -0.05 shifts 5% upward. - `caption` CaptionSetting — Caption generation settings for video creation. A sidecar subtitle file is always generated and returned via ``subtitle_url`` in the chosen ``file_format``. When ``style`` is also set, captions are additionally burned into the rendered video — the sidecar is still delivered. - `file_format` 'srt' — Supported caption file output formats. - `style` 'default' — Visual style applied when burning captions into the rendered video. - `output_format` 'mp4' | 'webm' — Output container for the generated video. - `script` string, nullable — Text script for the avatar to speak. Pair with voice_id, or omit voice_id when using avatar_id to use the avatar's default voice. Mutually exclusive with audio_url/audio_asset_id. - `voice_id` string, nullable — Voice ID for text-to-speech. Required when script is provided, unless avatar_id is set (the avatar's default voice is used as fallback). - `audio_url` string, nullable — Public URL of an audio file to lip-sync. Mutually exclusive with script. - `audio_asset_id` string, nullable — HeyGen asset ID of an uploaded audio file. Mutually exclusive with script. - `voice_settings` VoiceSettingsInput — Voice tuning parameters for text-to-speech. Applies only when 'script' + 'voice_id' are provided — not when audio_url/audio_asset_id is used (uploaded audio bypasses TTS). - `speed` number — Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed). - `pitch` number — Pitch adjustment in semitones. -50 to +50. - `volume` number — Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio. - `locale` string, nullable — Locale/accent hint for multi-lingual voices (e.g. 'en-US'). - `engine_settings` union — Engine-specific voice tuning, discriminated by 'engine_type'. Use the variant matching the engine backing the chosen voice (e.g. engine_type='elevenlabs' for ElevenLabs-backed voices). The request is rejected if the voice_id is not compatible with the selected engine. - ElevenLabsEngineSettings — Engine-specific voice settings for ElevenLabs-backed voices. Inherits the ElevenLabs tuning fields (model, stability, similarity_boost, style, use_speaker_boost) along with the eleven_v3 stability validator from :class:`movio.api_service.app.api_types.video.ElevenLabsSettings`. - … - FishEngineSettings — Engine-specific voice settings for Fish Audio-backed voices. Inherits Fish's tuning fields (model, stability, similarity). - … - StarfishEngineSettings — Engine-selection for Starfish-backed voices. Starfish has no user-tunable settings today; set ``engine_type='starfish'`` to force Starfish routing on voices that support multiple engines. - … - `type` 'avatar', required — Must be 'avatar' for avatar-based video creation. - `avatar_id` string, required — HeyGen avatar ID (video avatar or photo avatar look ID). - `motion_prompt` string, nullable — Natural-language prompt controlling avatar body motion and hand gestures. Supported for photo avatars on either engine, and for video avatars when engine.type is 'avatar_v'. Rejected for video avatars on the default Avatar IV engine. - `expressiveness` 'high' | 'medium' | 'low' — Avatar expressiveness level for photo avatars. - `engine` union — Engine configuration for video generation. Pass {"type": "avatar_v"} to enable cross-reference-driven animation for higher quality. Check supported_api_engines on the avatar look to confirm eligibility. Defaults to Avatar IV when omitted. - AvatarVEngineConfig — Avatar V engine configuration with cross-reference-driven animation. - `type` 'avatar_v', required — Engine type discriminator. Must be 'avatar_v'. Check supported_api_engines on the avatar look to confirm eligibility. - `reference_look_id` string, nullable — Optional instant_avatar look to use as the animation reference. Must be an `instant_avatar` look (studio / photo / other look types are rejected) belonging to the same avatar group as `avatar_id`. When omitted, video avatars self-reference and photo avatars auto-select the best instant_avatar sibling in their group. - AvatarIVEngineConfig — Avatar IV engine configuration (default behavior). - `type` 'avatar_iv', required — Engine type discriminator. Must be 'avatar_iv'. - AvatarIIIEngineConfig — Avatar III engine configuration. A single engine value that resolves to the right product by the avatar's look type (mirrors how ``avatar_iv`` already serves both photo and video avatars): - video avatar looks (``digital_twin``, ``studio_avatar``) -> Digital Twin (supports 4K) - ``photo_avatar`` look -> Photo Avatar (no 4K output) Not supported for raw image input (``type: "image"``). ``motion_prompt`` and ``expressiveness`` are not supported with this engine. - `type` 'avatar_iii', required — Engine type discriminator. Must be 'avatar_iii'. Resolves to Digital Twin for video avatar looks (digital_twin, studio_avatar) and Photo Avatar for photo_avatar looks; not supported for raw image input. Check supported_api_engines on the avatar look to confirm eligibility. - CreateVideoFromImage — Create a video by animating an arbitrary image. Provide an image via URL, asset ID, or inline base64. The image will be animated with lip-sync to the provided audio or generated speech. - `title` string, nullable — Display title for the video in the HeyGen dashboard. - `resolution` '4k' | '1080p' | '720p' — Output video resolution. - `aspect_ratio` '16:9' | '9:16' | '4:5' | '5:4' | '1:1' | 'auto', nullable — Output video aspect ratio. - ``16:9`` / ``9:16``: classic landscape / portrait. - ``4:5`` / ``5:4`` / ``1:1``: social-media-friendly ratios. Output is short-edge anchored to the requested resolution (e.g. ``1080p`` 1:1 → 1080x1080, ``1080p`` 4:5 → 1080x1350). - ``auto``: preserve the source's aspect ratio. The dimensions are derived from the avatar's source frames (``avatar_id``) or the uploaded image (``image_url`` / ``image_asset_id``), short-edge anchored to the requested resolution and capped at the tier's long edge. Falls back to ``16:9`` when source dimensions can't be read. - `fit` 'contain' | 'cover' — How the avatar is scaled to the output canvas. - `background` BackgroundSetting — Background configuration for the generated video. - `type` 'color' | 'image', required — Background type. 'color' uses a solid hex color; 'image' uses an image from url or asset_id. - `value` string, nullable — Hex color code (e.g. '#ff0000'). Required when type is 'color'. - `url` string, nullable — URL of the background image. Used when type is 'image'. Mutually exclusive with asset_id. - `asset_id` string, nullable — HeyGen asset ID of the background image. Used when type is 'image'. Mutually exclusive with url. - `remove_background` boolean, nullable — Remove the avatar background. Video avatars must be trained with matting enabled. - `callback_url` string, nullable — Webhook URL to receive a POST notification when the video is ready. - `callback_id` string, nullable — Caller-defined identifier echoed back in the webhook payload. - `watermark` object, nullable — Watermark configuration for video creation. - `image` union, required — Image asset to use as the watermark overlay (PNG or JPEG). - AssetUrl — Asset input via publicly accessible HTTPS URL. - … - AssetId — Asset input via HeyGen asset ID from the asset upload endpoint. - … - AssetBase64 — Asset input via base64-encoded content. - … - `scale` number — Scale multiplier for the watermark image. 1.0 renders at native size. - `opacity` number — Watermark opacity. 0.0 is fully transparent, 1.0 is fully opaque. - `placement` WatermarkPlacement — Watermark placement configuration. - `position` 'top_left' | 'top_right' | 'bottom_left' | 'bottom_right' — Anchor corner for a custom watermark overlay. - `offset_x` number, nullable — Fine-tune horizontal position. Fraction of frame width; 0.05 shifts 5% rightward, -0.05 shifts 5% leftward. - `offset_y` number, nullable — Fine-tune vertical position. Fraction of frame height; 0.05 shifts 5% downward, -0.05 shifts 5% upward. - `caption` CaptionSetting — Caption generation settings for video creation. A sidecar subtitle file is always generated and returned via ``subtitle_url`` in the chosen ``file_format``. When ``style`` is also set, captions are additionally burned into the rendered video — the sidecar is still delivered. - `file_format` 'srt' — Supported caption file output formats. - `style` 'default' — Visual style applied when burning captions into the rendered video. - `output_format` 'mp4' | 'webm' — Output container for the generated video. - `script` string, nullable — Text script for the avatar to speak. Pair with voice_id, or omit voice_id when using avatar_id to use the avatar's default voice. Mutually exclusive with audio_url/audio_asset_id. - `voice_id` string, nullable — Voice ID for text-to-speech. Required when script is provided, unless avatar_id is set (the avatar's default voice is used as fallback). - `audio_url` string, nullable — Public URL of an audio file to lip-sync. Mutually exclusive with script. - `audio_asset_id` string, nullable — HeyGen asset ID of an uploaded audio file. Mutually exclusive with script. - `voice_settings` VoiceSettingsInput — Voice tuning parameters for text-to-speech. Applies only when 'script' + 'voice_id' are provided — not when audio_url/audio_asset_id is used (uploaded audio bypasses TTS). - `speed` number — Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed). - `pitch` number — Pitch adjustment in semitones. -50 to +50. - `volume` number — Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio. - `locale` string, nullable — Locale/accent hint for multi-lingual voices (e.g. 'en-US'). - `engine_settings` union — Engine-specific voice tuning, discriminated by 'engine_type'. Use the variant matching the engine backing the chosen voice (e.g. engine_type='elevenlabs' for ElevenLabs-backed voices). The request is rejected if the voice_id is not compatible with the selected engine. - ElevenLabsEngineSettings — Engine-specific voice settings for ElevenLabs-backed voices. Inherits the ElevenLabs tuning fields (model, stability, similarity_boost, style, use_speaker_boost) along with the eleven_v3 stability validator from :class:`movio.api_service.app.api_types.video.ElevenLabsSettings`. - … - FishEngineSettings — Engine-specific voice settings for Fish Audio-backed voices. Inherits Fish's tuning fields (model, stability, similarity). - … - StarfishEngineSettings — Engine-selection for Starfish-backed voices. Starfish has no user-tunable settings today; set ``engine_type='starfish'`` to force Starfish routing on voices that support multiple engines. - … - `type` 'image', required — Must be 'image' for image-based video creation. - `image` union, required — Image to animate. Accepts URL, asset ID, or base64-encoded data. - AssetUrl — Asset input via publicly accessible HTTPS URL. - `type` 'url', required — Input type discriminator - `url` string, required — Publicly accessible HTTPS URL for the asset - AssetId — Asset input via HeyGen asset ID from the asset upload endpoint. - `type` 'asset_id', required — Input type discriminator - `asset_id` string, required — HeyGen asset ID from the asset upload endpoint - AssetBase64 — Asset input via base64-encoded content. - `type` 'base64', required — Input type discriminator - `media_type` string, required — MIME type of the encoded content (e.g. "image/png") - `data` string, required — Base64-encoded file content - `motion_prompt` string, nullable — Natural-language prompt controlling avatar body motion. Photo avatars only. - `expressiveness` 'high' | 'medium' | 'low' — Avatar expressiveness level for photo avatars. - CreateVideoFromCinematicAvatar — Create a video from a text prompt plus avatar and asset references (Cinematic Avatar). Cinematic Avatar generates a video from a natural-language ``prompt`` guided by reference content: one to three avatar looks and optional reference assets (images / videos / audio). Unlike the ``avatar`` and ``image`` modes there is no script or voice — motion and speech are driven entirely by the prompt and the supplied references. Backed by the Seedance generation pipeline. - `type` 'cinematic_avatar', required — Must be 'cinematic_avatar' for prompt-and-reference video creation. - `prompt` string, required — Natural-language prompt describing the video to generate. - `avatar_id` string[], required — Avatar look ID(s) used as visual references. Provide 1 to 3 look IDs. - `references` union[], nullable — Reference assets (images, videos, or audio) guiding the generation. Each accepts a URL, an asset_id, or inline base64. Combined limits: at most 3 videos and 9 images across avatars and references. - union - AssetUrl — Asset input via publicly accessible HTTPS URL. - … - AssetId — Asset input via HeyGen asset ID from the asset upload endpoint. - … - AssetBase64 — Asset input via base64-encoded content. - … - `aspect_ratio` '16:9' | '9:16' | '4:5' | '5:4' | '1:1' | 'auto' — Output video aspect ratio. - ``16:9`` / ``9:16``: classic landscape / portrait. - ``4:5`` / ``5:4`` / ``1:1``: social-media-friendly ratios. Output is short-edge anchored to the requested resolution (e.g. ``1080p`` 1:1 → 1080x1080, ``1080p`` 4:5 → 1080x1350). - ``auto``: preserve the source's aspect ratio. The dimensions are derived from the avatar's source frames (``avatar_id``) or the uploaded image (``image_url`` / ``image_asset_id``), short-edge anchored to the requested resolution and capped at the tier's long edge. Falls back to ``16:9`` when source dimensions can't be read. - `resolution` '720p' | '1080p' — Output resolution. Supported for cinematic_avatar: '720p', '1080p'. Defaults to '720p'. - `auto_duration` boolean — Let the model choose the video length. When true, omit duration. - `duration` integer, nullable — Video length in seconds (4–15). Defaults to 10. Omit when auto_duration is true. - `enhance_prompt` boolean — Enable server-side prompt enhancement. - `title` string, nullable — Display title for the video in the HeyGen dashboard. - CreateVideoFromStudio — Create a single video by composing an ordered list of whole-frame scenes. The server owns layout and center-crops each scene to the global output canvas. Output settings are global (one per request); a single video_id is returned and rendering is all-or-nothing. MP4 only in v1 — the output container is fixed and ``output_format`` is not exposed. - `type` 'studio', required — Must be 'studio' for scene-composition video creation. - `title` string, nullable — Display title for the video in the HeyGen dashboard. - `aspect_ratio` '16:9' | '9:16' | '4:5' | '5:4' | '1:1' | 'auto', nullable — Output video aspect ratio. - ``16:9`` / ``9:16``: classic landscape / portrait. - ``4:5`` / ``5:4`` / ``1:1``: social-media-friendly ratios. Output is short-edge anchored to the requested resolution (e.g. ``1080p`` 1:1 → 1080x1080, ``1080p`` 4:5 → 1080x1350). - ``auto``: preserve the source's aspect ratio. The dimensions are derived from the avatar's source frames (``avatar_id``) or the uploaded image (``image_url`` / ``image_asset_id``), short-edge anchored to the requested resolution and capped at the tier's long edge. Falls back to ``16:9`` when source dimensions can't be read. - `resolution` '4k' | '1080p' | '720p' — Output video resolution. - `callback_url` string, nullable — Webhook URL to receive a POST notification when the video is ready. - `callback_id` string, nullable — Caller-defined identifier echoed back in the webhook payload. - `caption` CaptionSetting — Caption generation settings for video creation. A sidecar subtitle file is always generated and returned via ``subtitle_url`` in the chosen ``file_format``. When ``style`` is also set, captions are additionally burned into the rendered video — the sidecar is still delivered. - `file_format` 'srt' — Supported caption file output formats. - `style` 'default' — Visual style applied when burning captions into the rendered video. - `watermark` object, nullable — Watermark configuration for video creation. - `image` union, required — Image asset to use as the watermark overlay (PNG or JPEG). - AssetUrl — Asset input via publicly accessible HTTPS URL. - … - AssetId — Asset input via HeyGen asset ID from the asset upload endpoint. - … - AssetBase64 — Asset input via base64-encoded content. - … - `scale` number — Scale multiplier for the watermark image. 1.0 renders at native size. - `opacity` number — Watermark opacity. 0.0 is fully transparent, 1.0 is fully opaque. - `placement` WatermarkPlacement — Watermark placement configuration. - `position` 'top_left' | 'top_right' | 'bottom_left' | 'bottom_right' — Anchor corner for a custom watermark overlay. - `offset_x` number, nullable — Fine-tune horizontal position. Fraction of frame width; 0.05 shifts 5% rightward, -0.05 shifts 5% leftward. - `offset_y` number, nullable — Fine-tune vertical position. Fraction of frame height; 0.05 shifts 5% downward, -0.05 shifts 5% upward. - `scenes` union[], required — Ordered list of whole-frame scenes to concatenate. Each scene is one of 'avatar_video', 'image', or 'video'. Must contain 1 to 50 scenes. - union - AvatarVideoScene — A whole-frame speaking scene backed by an avatar. - … - ImageScene — A whole-frame still-image scene: either silent (held for ``duration``) or narrated. Exactly one mode must be chosen: - silent: set ``duration`` (seconds) and no audio source. - narrated: set exactly one audio source (script + voice_id, audio_url, or audio_asset_id) and omit ``duration`` — the scene length follows the audio. - … - VideoScene — A whole-frame scene backed by an existing video clip. Optional ``playback`` exposes the audio volume / mute capability (PRINFRA-271); when omitted the clip plays at its source volume. Optional voiceover / narration (PRINFRA-303 / 304): supply at most one audio source (``script`` + ``voice_id``, ``audio_url``, or ``audio_asset_id``) — the *same* audio inputs a narrated ``image`` scene accepts. When present, the narration drives the scene length and the clip is held/frozen behind it (mirroring the narrated-image timing path); when omitted the clip plays full-length as before. The clip's own audio level is still governed by ``playback`` (the two compose). - … ## Response `202` Accepted — submission acknowledged; poll for completion. - object - `data` CreateVideoBatchResponse - `batch_id` string, required — Identifier of the created batch. Poll GET /v3/videos/batches/{batch_id} for progress. ## Other responses - `400` — Invalid request parameters - `401` — Authentication failed - `409` — A prior request with this Idempotency-Key is still in progress. Wait for the original request to complete, then retry. - `429` — Rate limit exceeded --- [API](https://skmtc.net/heygen/apis/heygen-external-api.md) · [All operations](https://skmtc.net/heygen/apis/heygen-external-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/heygen/heygen-external-api/versions/e2e54726e210/schema)