HEheygen
Custom Agents

Create Custom Agent Video

Changed on

Starts a custom-agent run from a topic prompt and returns a video_id; poll GET /v3/custom-agents/videos/{video_id} for status and the MP4 URL. Pass screenshots and screen recordings as asset ids, and the presenter clip as a completed roll_video_id.

post/v3/custom-agents/{agent_id}/videos

Request

  • Base URL
    https://api.heygen.com
  • URL
    https://api.heygen.com/v3/custom-agents/{agent_id}/videos
  • Auth
    • API key in header x-api-key
    • or HTTP bearer

Path parameters

agent_idstring required

Custom-agent id (e.g. chiron).

Headers

Idempotency-Keystring

Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent.

Request body

topicstring required

What the video should be about.

lane'mac' | 'iphone' | 'watch' nullable

Device lane. Agent infers from the topic when omitted.

wallpaperstring nullable

neo-green / neo-purple / neo-pink / wwdc26, or a user-supplied HTTP(S) URL.

avatar_idstring nullable

HeyGen avatar id for the on-camera presenter.

avatar_still_urlstring nullable

URL of a still image (from /v3/assets/direct-uploads) for talking-photo inference.

voice_idstring nullable

Voice id for narration (HeyGen or ElevenLabs).

watch_modelstring nullable

Watch lane only: <size> <finish> + <band> selector.

scriptstring nullable

Verbatim voice-over script; agent generates one when omitted.

screen_recording_asset_idstring nullable

Asset id of a screen-recording video in your space, from POST /v3/assets/direct-uploads.

screenshot_asset_idsstring[] nullable

Ordered list of image asset ids in your space, from POST /v3/assets/direct-uploads. The agent views each in list order via view_image and authors one beat per screenshot in that order. Cap 8. When set, takes priority over screen_recording_asset_id and the curated capture_screen reference library for beats it covers. For Orchard these are the product hero plates, one per numbered update in list order.

presenter_background_urlstring nullable

URL of an image to composite behind the matted avatar.

presenter_background_video_urlstring nullable

URL of a looping video to composite behind the matted avatar.

roll_video_idstring nullable

Id of a completed video in your space (for example one created with POST /v3/videos) to use as the presenter (aroll) clip. When set, the agent uses it directly and skips avatar generation.

density'simple' | 'dense' | 'hybrid' nullable

Orchard density lane. simple = Apple's rhythm (presenter full-frame); dense = heroes + demos; hybrid = b-roll/product on the top half + presenter on the bottom half plus a corner FaceTime-style PiP tile, choreographing full -> split -> full -> back-to-split -> pip across four updates. Defaults to simple. Orchard's per-update product hero plates are supplied via the shared screenshot_asset_ids field.

framing'showcase' | 'split' | 'presenter' nullable

Pomona opening framing. showcase = full-screen device under the lockup (the house opening); split = the 50/50, device in the top band and presenter in the bottom band; presenter = full-screen presenter. Only the OPENING framing — the film moves between all three by slide-morph. Defaults to showcase.

Response

Accepted — submission acknowledged; poll for completion.

Changes