# How to Configure Video Templates in Pixelle-Video: A Complete Parameter Guide

> Master Pixelle-Video template configuration. Learn how to set frame_template path and use template_params for custom HTML values. Optimize your video generation workflow today.

- Repository: [AIDC-AI/Pixelle-Video](https://github.com/AIDC-AI/Pixelle-Video)
- Tags: how-to-guide
- Published: 2026-04-23

---

**You configure video templates in Pixelle-Video by setting the `frame_template` path and optionally passing a `template_params` dictionary with custom values defined in the HTML template.**

The Pixelle-Video open-source framework uses HTML-based templates to control the visual layout, dimensions, and styling of every video frame. Understanding how to configure these templates correctly lets you customize everything from color schemes to background assets without modifying core code.

---

## Understanding the Core Template Configuration

Pixelle-Video stores template configuration in two primary locations: the request schema and the global configuration file. The system resolves template paths through `resolve_template_path()` in [`pixelle_video/utils/template_util.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/pixelle_video/utils/template_util.py) and parses dimensions using `parse_template_size()`.

### The `frame_template` Field

Every video generation request accepts a `frame_template` string that specifies which HTML template to render. According to [`api/schemas/video.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/api/schemas/video.py), this field accepts paths in the format `<WIDTH>x<HEIGHT>/<template_name>.html`.

**Path resolution rules:**

- **Standard format**: [`1080x1920/image_default.html`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/1080x1920/image_default.html) (portrait 1080×1920)
- **Absolute paths**: `templates/1080x1920/...` 
- **Legacy paths**: `data/templates/...` (normalized by `resolve_template_path()`)

The dimensions are automatically extracted from the folder name and validated by the size parser in [`pixelle_video/utils/template_util.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/pixelle_video/utils/template_util.py).

### The `template_params` Dictionary

Custom template parameters pass through the `template_params` field defined in [`api/schemas/video.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/api/schemas/video.py). This optional dictionary contains key-value pairs that override defaults embedded in the HTML template.

---

## Defining and Using Template Parameters

Template parameters use a specialized placeholder syntax directly in HTML files. The parser in `pixelle_video/services/frame_html.py::parse_template_parameters()` extracts these definitions and exposes them via the API.

### Parameter Syntax Reference

Templates declare parameters using double curly braces with optional type annotations and defaults:

| Syntax | Behavior |
|--------|----------|
| `{{param}}` | Text parameter, no default value |
| `{{param=value}}` | Text parameter with default |
| `{{param:type}}` | Explicitly typed parameter |
| `{{param:type=value}}` | Typed parameter with default |

**Example from a template HTML file:**

```html
<div style="color: {{accent_color:color=#ff0000}}">
  <h1>{{title:text=Untitled}}</h1>
  <p class="{{enable_glow:bool=false}}">Featured</p>
</div>

```

### Supported Parameter Types

The [`pixelle_video/services/frame_html.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/pixelle_video/services/frame_html.py) parser recognizes four core types:

1. **`text`** — Free-form string values
2. **`number`** — Integer or floating-point values
3. **`color`** — Hex color codes (`#rrggbb` or `#rgb`)
4. **`bool`** — Boolean values (`true`/`false`)

Type enforcement occurs during template rendering, with invalid values falling back to defaults or raising validation errors.

### Reserved Preset Parameters

The parser in [`pixelle_video/services/frame_html.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/pixelle_video/services/frame_html.py) excludes certain reserved keys from custom parameter extraction. The `PRESET_PARAMS` set includes:

| Parameter | Purpose |
|-----------|---------|
| `title` | Frame title text (auto-populated) |
| `text` | Narrative text content |
| `image` | Image URL or local path |
| `index` | Frame order index (internal use) |

These values are injected automatically by the rendering pipeline and should not be declared as custom parameters.

---

## Discovering Template Parameters via API

Before generating a video, you can inspect which parameters a template accepts. The [`api/routers/frame.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/api/routers/frame.py) router exposes the `GET /frame/template/params` endpoint.

### Request Format

```bash
GET /frame/template/params?template=1080x1920/image_fashion_vintage.html

```

The `parse_template_parameters()` function in [`pixelle_video/services/frame_html.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/pixelle_video/services/frame_html.py) processes the template file and returns structured metadata.

### Response Structure

```json
{
  "template": "1080x1920/image_fashion_vintage.html",
  "media_width": 1080,
  "media_height": 1920,
  "params": {
    "accent_color": {
      "type": "color",
      "default": "#ff0000",
      "label": "accent_color"
    },
    "background": {
      "type": "text",
      "default": "",
      "label": "background"
    },
    "enable_overlay": {
      "type": "bool",
      "default": true,
      "label": "enable_overlay"
    }
  }
}

```

Use this response to build dynamic UIs or validate parameter values before submission.

---

## Global Default Template Configuration

When `frame_template` is omitted from a request, Pixelle-Video falls back to the global default specified in [`config.example.yaml`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/config.example.yaml).

```yaml
template:
  default_template: "1080x1920/image_default.html"

```

This value is read at startup and used when `resolve_template_path()` receives no explicit template argument. Override it by:

1. Copying [`config.example.yaml`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/config.example.yaml) to [`config.yaml`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/config.yaml)
2. Modifying the `template.default_template` value
3. Restarting the Pixelle-Video service

---

## Practical Implementation Examples

### Python SDK Usage

The `pixelle_video` package accepts template configuration directly:

```python
import pixelle_video

result = pixelle_video.generate_video(
    text="A cinematic journey through mountain peaks at sunrise.",
    frame_template="1080x1920/image_fashion_vintage.html",
    template_params={
        "accent_color": "#e74c3c",
        "background": "https://cdn.example.com/mountains.jpg",
        "enable_overlay": False
    }
)

print(f"Video ready: {result.video_url}")

```

The `generate_video()` function delegates to the rendering pipeline, where [`frame_html.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/frame_html.py) combines the template, parameters, and content into frame images.

### HTTP API Request

Submit a generation request with explicit template configuration:

```bash
POST /video/generate
Content-Type: application/json

{
  "text": "Modern architecture showcase",
  "frame_template": "1080x1920/image_minimal.html",
  "template_params": {
    "primary_color": "#2c3e50",
    "font_family": "Helvetica Neue",
    "show_watermark": false
  }
}

```

The response follows the `VideoGenerateResponse` schema defined in [`api/schemas/video.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/api/schemas/video.py).

### Creating a Custom Template

To build a reusable template with exposed parameters:

1. **Create the HTML file** at [`templates/1080x1920/my_custom.html`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/templates/1080x1920/my_custom.html):

```html
<!DOCTYPE html>
<html>
<head>
  <style>
    body {
      margin: 0;
      background: url('{{background_image:text=}}') center/cover;
      font-family: {{font_family:text=Arial}};
    }
    .content {
      color: {{text_color:color=#ffffff}};
      padding: {{padding:number=40}}px;
      opacity: {{transparency:number=1.0}};
    }
    .highlight {
      display: {{show_highlight:bool=true}};
    }
  </style>
</head>
<body>
  <div class="content">
    <h1>{{title}}</h1>
    <p>{{text}}</p>
    <span class="highlight">Featured</span>
  </div>
</body>
</html>

```

2. **Deploy the template** to your Pixelle-Video instance's `templates/` directory.

3. **Reference and validate** via the API:

```bash
GET /frame/template/params?template=1080x1920/my_custom.html

```

4. **Use in generation** with your defined parameters.

---

## Summary

- **Template selection** happens through the `frame_template` field, using paths like [`1080x1920/image_default.html`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/1080x1920/image_default.html) where dimensions are extracted from the folder name.
- **Custom parameters** are declared in HTML templates using `{{param:type=default}}` syntax and passed at runtime via the `template_params` dictionary.
- **Parameter discovery** is available through the `GET /frame/template/params` endpoint, which parses templates using `pixelle_video/services/frame_html.py::parse_template_parameters()`.
- **Global defaults** can be configured in [`config.yaml`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/config.yaml) under `template.default_template` to avoid repeating template paths in every request.
- **Four parameter types** are supported: `text`, `number`, `color`, and `bool`.

---

## Frequently Asked Questions

### What is the default template if I don't specify `frame_template`?

Pixelle-Video reads the `template.default_template` value from [`config.yaml`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/config.yaml), which defaults to [`1080x1920/image_default.html`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/1080x1920/image_default.html) in the example configuration. This fallback is used whenever a generation request omits the `frame_template` field.

### How do I find out what parameters a template accepts?

Call the `GET /frame/template/params` endpoint with the template path as a query parameter. The response returns each parameter's name, type, default value, and label. Internally, this endpoint invokes `parse_template_parameters()` in [`pixelle_video/services/frame_html.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/pixelle_video/services/frame_html.py) to scan the HTML file for placeholder syntax.

### Can I create my own template with custom parameters?

Yes. Create an HTML file in the `templates/<WIDTH>x<HEIGHT>/` directory and use the `{{param:type=default}}` syntax to declare configurable values. Deploy the file to your Pixelle-Video instance, then reference it by path in `frame_template` or discover its parameters via the API before use.

### What parameter types are supported in templates?

Pixelle-Video supports four types: `text` for strings, `number` for integers and floats, `color` for hex color codes, and `bool` for true/false values. These types are enforced during rendering, with invalid values falling back to declared defaults or raising validation errors.