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

```bash
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:

```bash
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:

```bash
# 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
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
{
  "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.