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

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 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, this field accepts paths in the format <WIDTH>x<HEIGHT>/<template_name>.html.

Path resolution rules:

• Standard format: 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.

The template_params Dictionary

Custom template parameters pass through the template_params field defined in 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:

<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 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 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 router exposes the GET /frame/template/params endpoint.

Request Format

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

The parse_template_parameters() function in pixelle_video/services/frame_html.py processes the template file and returns structured metadata.

Response Structure

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

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

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 combines the template, parameters, and content into frame images.

HTTP API Request

Submit a generation request with explicit template configuration:

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.

Creating a Custom Template

To build a reusable template with exposed parameters:

1. Create the HTML file at templates/1080x1920/my_custom.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:

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 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 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, which defaults to 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}