Styles & References

Steer HeyGen AI video output with style presets and reference images. Apply cinematic looks, brand colors, and visual consistency across generations.

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

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

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.