ATH-MaaS/Pixelle-Video · error · ValueError

frame_template is required to determine media size

Error message

frame_template is required to determine media size

What it means

The /video/generate/sync endpoint requires the request body to include frame_template because media_width and media_height are auto-detected from the template's HTML meta tags via HTMLFrameGenerator.get_media_size(). If frame_template is missing, null, or an empty string, generate_video_sync raises ValueError before any generation starts. This is an intentional fail-fast guard, not a bug.

Source

Thrown at api/routers/video.py:112

    """
    Generate video synchronously
    
    This endpoint blocks until video generation is complete.
    Suitable for small videos (< 30 seconds).
    
    **Note**: May timeout for large videos. Use `/generate/async` instead.
    
    Request body includes all video generation parameters.
    See VideoGenerateRequest schema for details.
    
    Returns path to generated video, duration, and file size.
    """
    try:
        logger.info(f"Sync video generation: {request_body.text[:50]}...")
        
        # Auto-determine media_width and media_height from template meta tags (required)
        if not request_body.frame_template:
            raise ValueError("frame_template is required to determine media size")
        
        from pixelle_video.services.frame_html import HTMLFrameGenerator
        from pixelle_video.utils.template_util import resolve_template_path
        template_path = resolve_template_path(request_body.frame_template)
        generator = HTMLFrameGenerator(template_path)
        media_width, media_height = generator.get_media_size()
        logger.debug(f"Auto-determined media size from template: {media_width}x{media_height}")
        
        # Build video generation parameters
        video_params = {
            "text": request_body.text,
            "mode": request_body.mode,
            "title": request_body.title,
            "n_scenes": request_body.n_scenes,
            "min_narration_words": request_body.min_narration_words,
            "max_narration_words": request_body.max_narration_words,
            "min_image_prompt_words": request_body.min_image_prompt_words,
            "max_image_prompt_words": request_body.max_image_prompt_words,

View on GitHub (pinned to 848b054e4f)

Solutions

  1. Add frame_template to the request body with the name of an existing template (e.g. "default"), letting the endpoint derive media size from its meta tags
  2. Ensure the field is a non-empty string, not null or "" (falsy values are rejected)
  3. Verify against the current VideoGenerateRequest schema (api/schemas/video.py) that frame_template is populated; update stale client code or saved request templates
  4. Check available templates in the templates directory and confirm resolve_template_path can find the one you pass (a valid template is needed immediately after this check)

Example fix

// before
{"text": "Hello world", "mode": "standard"}
// after
{"text": "Hello world", "mode": "standard", "frame_template": "default"}
Defensive patterns

Strategy: validation

Validate before calling

def build_sync_request(body: dict) -> dict:
    template = body.get("frame_template")
    if not template or not isinstance(template, str) or not template.strip():
        raise ValueError("frame_template is required and must be a non-empty template name")
    return {**body, "frame_template": template.strip()}

Type guard

def has_frame_template(body: dict) -> bool:
    return isinstance(body.get("frame_template"), str) and bool(body["frame_template"].strip())

Try / catch

try:
    resp = requests.post(f"{BASE}/api/video/generate/sync", json=payload, timeout=300)
    resp.raise_for_status()
except requests.HTTPError as e:
    detail = e.response.json().get("detail", str(e))
    if "frame_template is required" in detail:
        payload["frame_template"] = "default"
        resp = requests.post(f"{BASE}/api/video/generate/sync", json=payload, timeout=300)
    else:
        raise

Prevention

When it happens

Trigger: POST /api/video/generate/sync with a VideoGenerateRequest body that omits frame_template or sets it to null/empty string; the check at api/routers/video.py:111-112 fires before resolve_template_path is called.

Common situations: Clients built against an older API version where media_width/media_height were passed explicitly and frame_template was optional; hand-written curl/JSON payloads missing the field; SDK defaults that leave the field unset; copying a minimal example payload that predates the template-based sizing requirement.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

AI-assisted analysis of ATH-MaaS/Pixelle-Video@848b054e4f (2026-08-30). Data as JSON: /api/errors/30f5dc0396bde645. Report an issue: GitHub.