Styles & References

Browse and apply curated visual styles to Video Agent videos.

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.

List available styles

GET https://api.heygen.com/v3/video-agents/styles

Returns a paginated list of styles. Each style 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://cdn.heygen.com/styles/noir_thumb.jpg",
      "preview_video_url": "https://cdn.heygen.com/styles/noir_preview.mp4",
      "tags": ["cinematic"],
      "aspect_ratio": "16:9"
    },
    {
      "style_id": "style_retro_crt",
      "name": "Retro CRT",
      "thumbnail_url": "https://cdn.heygen.com/styles/retro_crt_thumb.jpg",
      "preview_video_url": "https://cdn.heygen.com/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.