> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.app/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.

Styles are curated visual templates that control how the [Video Agent](/docs/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

Full schema: [`GET /v3/video-agents/styles`](/reference/list-video-agent-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

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

  ```python Python theme={null}
  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"])
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "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`](/reference/create-video-agent-session) 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:

```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.
</Tip>

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

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

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

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