sgl-project/sglang · error · ValueError

ref2va keyframes require at least one reference condition; u

Error message

ref2va keyframes require at least one reference condition; use task 'fl2va' for keyframe-only generation

What it means

For task 'ref2va' the model needs at least one condition with role='reference' in addition to the required keyframes; keyframe-only input belongs to the 'fl2va' task. The validator rejects a ref2va request whose conditions contain no reference role.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/request_validation.py:272

    """Enforce the shared first/last-frame contract after schema validation."""

    keyframes = [
        condition
        for condition in conditions
        if condition["role"] == MINIMAX_H3_CONDITION_ROLE_KEYFRAME
    ]
    frame_indices = tuple(condition.get("frame_index") for condition in keyframes)
    if frame_indices not in MINIMAX_H3_FL2VA_KEYFRAME_SIGNATURES:
        raise ValueError(
            f"conditions for task {task!r} must include one or two ordered "
            "image/keyframe entries with frame_index [0], [-1], or [0, -1], "
            f"got {list(frame_indices)!r}"
        )
    if task == MINIMAX_H3_TASK_REF2VA and not any(
        condition["role"] == MINIMAX_H3_CONDITION_ROLE_REFERENCE
        for condition in conditions
    ):
        raise ValueError(
            "ref2va keyframes require at least one reference condition; "
            "use task 'fl2va' for keyframe-only generation"
        )


def minimax_h3_validate_canonical_request(
    *,
    task: Any,
    prompt: Any,
    conditions: Any,
    target: Any,
    flow_shift: Any = None,
    audio_flow_shift: Any = None,
    seed: Any = None,
    **_extra_kwargs: Any,
) -> dict[str, Any]:
    """Validate and normalize a `minimax_h3.request/v1` canonical request.

View on GitHub (pinned to 0132848349)

Solutions

1. Add at least one {role:'reference', type:'image', ...} condition to the request
2. If you only want first/last-frame animation, use task 'fl2va' instead of 'ref2va'

Example fix

// before
{"task":"ref2va","conditions":[{"role":"keyframe","type":"image","uri":"f.png","frame_index":0}]}
// after
{"task":"ref2va","conditions":[{"role":"reference","type":"image","uri":"ref.png"},{"role":"keyframe","type":"image","uri":"f.png","frame_index":0}]}

def ref2va_ok(task, conditions):
    return task != "ref2va" or any(c.get("role") == "reference" for c in conditions)

null

null

When it happens

Trigger: Calling minimax_h3_validate_canonical_request with task='ref2va' but conditions containing only keyframe-role entries (frame_index 0 / -1) and no role='reference' condition.

Common situations: Prototyping with the fl2va-style payload and switching the task string to ref2va without adding a reference image; misunderstanding that ref2va = reference + keyframes.

Related errors

• {context}video block token counts and timestamps must align
• {name} must be an int or a sequence of ints
• video block token counts and timestamps must align
• image_token_count required for an image reference
• video reference requires block token counts and timestamps

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/c8e683cd9f32cc5c. Report an issue: GitHub.