> ## Documentation Index
> Fetch the complete documentation index at: https://developers.heygen.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Styles & References

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

![](https://mintcdn.com/heygen-1fa696a7/hfMXXwJzjE7vBSYZ/images/theme/research-9.webp?fit=max\&auto=format\&n=hfMXXwJzjE7vBSYZ\&q=85\&s=9afc7a8acf73c8f9ec670dde494e9931)

Styles are curated visual templates that control how the [Video Agent](https://developers.heygen.com/docs/video-agent.md) 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](https://developers.heygen.com/docs/prompting-guide.md).

## List available styles

[`GET /v3/video-agents/styles`](https://developers.heygen.com/reference/list-video-agent-styles) returns a paginated list (`limit` 1–100, default 20; pass `next_token` back as `token` while `has_more` is `true`). Each style carries a `style_id`, `name`, `thumbnail_url`, `preview_video_url`, `tags`, and the `aspect_ratio` it is designed for (`"16:9"`, `"9:16"`, or `"1:1"`).

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

Filter with `tag`:

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

## Apply a style to a video

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

```bash theme={null}
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.

> [!TIP]
>
> 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.

## 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:

```json theme={null}
{
  "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.