---
title: "Create Custom Agent Video"
method: POST
path: "/v3/custom-agents/{agent_id}/videos"
tags: ["Custom Agents"]
---

# Create Custom Agent Video

`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: one of:
  - API key in header `x-api-key`
  - HTTP bearer

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

## Path parameters

- `agent_id` string, required

## Headers

- `Idempotency-Key` string

## Request body

- CustomAgentVideoCreateRequest: Body for POST /v3/custom-agents/{agent_id}/videos. Screenshots, the screen recording, and Orchard's product heroes are referenced by asset id: upload via `POST /v3/assets/direct-uploads`, then pass the `asset_id`. A presenter clip is referenced by the id of a completed video. The remaining media (still, wallpaper, presenter background) are passed as URLs. This endpoint does NOT accept multipart file uploads.
  - `topic` string, required: What the video should be about.
  - `lane` 'mac' | 'iphone' | 'watch', nullable: Device lane. Agent infers from the topic when omitted.
  - `wallpaper` string, nullable: `neo-green` / `neo-purple` / `neo-pink` / `wwdc26`, or a user-supplied HTTP(S) URL.
  - `avatar_id` string, nullable: HeyGen avatar id for the on-camera presenter.
  - `avatar_still_url` string, nullable: URL of a still image (from `/v3/assets/direct-uploads`) for talking-photo inference.
  - `voice_id` string, nullable: Voice id for narration (HeyGen or ElevenLabs).
  - `watch_model` string, nullable: Watch lane only: `<size> <finish> + <band>` selector.
  - `script` string, nullable: Verbatim voice-over script; agent generates one when omitted.
  - `screen_recording_asset_id` string, nullable: Asset id of a screen-recording video in your space, from `POST /v3/assets/direct-uploads`.
  - `screenshot_asset_ids` string[], 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_url` string, nullable: URL of an image to composite behind the matted avatar.
  - `presenter_background_video_url` string, nullable: URL of a looping video to composite behind the matted avatar.
  - `roll_video_id` string, 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 `202`

Accepted — submission acknowledged; poll for completion.

- object
  - `data` CustomAgentVideoCreateResponse: 202 response body for POST /v3/custom-agents/{agent_id}/videos.
    - `video_id` string, required: Opaque id; poll GET /v3/custom-agents/videos/{video_id}.
    - `status` string: Initial workflow status.

## Other responses

- `400`: Invalid request parameters
- `401`: Authentication failed
- `404`: Resource not found
- `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

## Changes

- **2026-11-03** `7dfa5e59b4f5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/heygen/apis/heygen-external-api/changes/v3/custom-agents/:agent_id/videos/post.md)

---

[API](https://skmtc.dev/heygen/apis/heygen-external-api.md) - [All operations](https://skmtc.dev/heygen/apis/heygen-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/heygen/apis/heygen-external-api/revisions/7dfa5e59b4f5?raw)