Styles & References

Styles are curated visual templates that control how the Video Agent composes your video — scene layout, script structure, pacing, and overall aesthetic. Apply a style by passing its style_id when creating a video. For a fully custom look, you can also describe a style directly in your prompt — see the Prompting Guide.

List available styles

Full schema: GET /v3/video-agents/styles. Returns a paginated list of styles — each includes a name, thumbnail, preview video, tags, and aspect ratio.

Query parameters

Parameter	Type	Default	Description
`tag`	string	—	Filter by tag. Available tags: `cinematic`, `retro-tech`, `iconic-artist`, `pop-culture`, `handmade`, `print`.
`limit`	integer	20	Results per page (1–100).
`token`	string	—	Opaque cursor from a previous response’s `next_token` for pagination.

Example request

curl "https://api.heygen.com/v3/video-agents/styles?tag=cinematic&limit=5" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

import requests

resp = requests.get(
    "https://api.heygen.com/v3/video-agents/styles",
    headers={"X-Api-Key": HEYGEN_API_KEY},
    params={"tag": "cinematic", "limit": 5},
)
styles = resp.json()["data"]
for style in styles:
    print(style["style_id"], style["name"])

Response

{
  "data": [
    {
      "style_id": "style_noir_detective",
      "name": "Noir Detective",
      "thumbnail_url": "https://files.heygen.ai/styles/noir_thumb.jpg",
      "preview_video_url": "https://files.heygen.ai/styles/noir_preview.mp4",
      "tags": ["cinematic"],
      "aspect_ratio": "16:9"
    },
    {
      "style_id": "style_retro_crt",
      "name": "Retro CRT",
      "thumbnail_url": "https://files.heygen.ai/styles/retro_crt_thumb.jpg",
      "preview_video_url": "https://files.heygen.ai/styles/retro_crt_preview.mp4",
      "tags": ["retro-tech"],
      "aspect_ratio": "16:9"
    }
  ],
  "has_more": true,
  "next_token": "eyJsYXN0X2lkIjoic3R5bGVfcmV0cm9fY3J0In0="
}

Style object

Field	Type	Description
`style_id`	string	Unique identifier. Pass this to `POST /v3/video-agents` as `style_id`.
`name`	string	Display name of the style.
`thumbnail_url`	string \| null	Thumbnail image URL (public CDN).
`preview_video_url`	string \| null	Preview video URL (public CDN, mp4).
`tags`	array \| null	Tags for categorization (e.g. `cinematic`, `retro-tech`, `handmade`).
`aspect_ratio`	string \| null	Aspect ratio the style is designed for: `"16:9"`, `"9:16"`, or `"1:1"`.

Apply a style to a video

Pass the style_id when creating a video with the Video Agent:

curl -X POST "https://api.heygen.com/v3/video-agents" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Explain the history of jazz music in 60 seconds",
    "style_id": "style_noir_detective"
  }'

The style influences the visual template the agent uses — scenes, transitions, text overlays, and pacing will follow the style’s design system. Your prompt still controls the content and narration.

Preview styles before using them. The preview_video_url on each style object shows a sample video rendered in that style — use it to pick the right look before generating.

Pagination

The styles endpoint uses cursor-based pagination. When has_more is true, pass the next_token value as the token query parameter in your next request:

# Page 1
curl "https://api.heygen.com/v3/video-agents/styles?limit=10" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

# Page 2
curl "https://api.heygen.com/v3/video-agents/styles?limit=10&token=eyJsYXN0X2lkIjo..." \
  -H "X-Api-Key: $HEYGEN_API_KEY"

Filter by tag

Use the tag parameter to narrow results to a specific category:

Tag	Description
`cinematic`	Film-inspired looks with dramatic lighting and composition.
`retro-tech`	Vintage technology aesthetics (CRT screens, pixel art, etc.).
`iconic-artist`	Styles inspired by iconic artistic movements.
`pop-culture`	Bold, colorful styles drawn from pop culture.
`handmade`	Handcrafted, organic textures (paper, watercolor, stop-motion).
`print`	Magazine, newspaper, and print-inspired layouts.

curl "https://api.heygen.com/v3/video-agents/styles?tag=handmade" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

Using file references with styles

Styles and file attachments work together. Attach reference images or documents alongside a style to combine the style’s visual template with your own content:

{
  "prompt": "Create a product demo using the attached screenshots",
  "style_id": "style_retro_crt",
  "files": [
    { "type": "url", "url": "https://example.com/screenshot-1.png" },
    { "type": "url", "url": "https://example.com/screenshot-2.png" }
  ]
}

The agent will render your screenshots within the retro CRT visual template, applying the style’s transitions and framing to your content.

Auth

User Info

Models

Video Generation

Video Composition

On Brand

Realtime Video

Video Translation

Lipsync

Tools

Avatar Management

Voice Management

Asset Management

Batches

Webhook

Limits

Pricing

Socials

For Agents

Integrations

List available styles

Query parameters

Example request

Response

Style object

Apply a style to a video

Filter by tag

Using file references with styles

​List available styles

​Query parameters

​Example request

​Response

​Style object

​Apply a style to a video

​Pagination

​Filter by tag

​Using file references with styles

List available styles

Query parameters

Example request

Response

Style object

Apply a style to a video

Pagination

Filter by tag

Using file references with styles