Skip to main content
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

ParameterTypeDefaultDescription
tagstring—Filter by tag. Available tags: cinematic, retro-tech, iconic-artist, pop-culture, handmade, print.
limitinteger20Results per page (1–100).
tokenstring—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"

​
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

FieldTypeDescription
style_idstringUnique identifier. Pass this to POST /v3/video-agents as style_id.
namestringDisplay name of the style.
thumbnail_urlstring | nullThumbnail image URL (public CDN).
preview_video_urlstring | nullPreview video URL (public CDN, mp4).
tagsarray | nullTags for categorization (e.g. cinematic, retro-tech, handmade).
aspect_ratiostring | nullAspect 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:
TagDescription
cinematicFilm-inspired looks with dramatic lighting and composition.
retro-techVintage technology aesthetics (CRT screens, pixel art, etc.).
iconic-artistStyles inspired by iconic artistic movements.
pop-cultureBold, colorful styles drawn from pop culture.
handmadeHandcrafted, organic textures (paper, watercolor, stop-motion).
printMagazine, 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.