{"record":{"id":"c8e683cd9f32cc5c","repo":"sgl-project/sglang","slug":"ref2va-keyframes-require-at-least-one-reference-co","errorCode":null,"errorMessage":"ref2va keyframes require at least one reference condition; use task 'fl2va' for keyframe-only generation","messagePattern":"ref2va keyframes require at least one reference condition; use task 'fl2va' for keyframe-only generation","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/request_validation.py","lineNumber":272,"sourceCode":"    \"\"\"Enforce the shared first/last-frame contract after schema validation.\"\"\"\n\n    keyframes = [\n        condition\n        for condition in conditions\n        if condition[\"role\"] == MINIMAX_H3_CONDITION_ROLE_KEYFRAME\n    ]\n    frame_indices = tuple(condition.get(\"frame_index\") for condition in keyframes)\n    if frame_indices not in MINIMAX_H3_FL2VA_KEYFRAME_SIGNATURES:\n        raise ValueError(\n            f\"conditions for task {task!r} must include one or two ordered \"\n            \"image/keyframe entries with frame_index [0], [-1], or [0, -1], \"\n            f\"got {list(frame_indices)!r}\"\n        )\n    if task == MINIMAX_H3_TASK_REF2VA and not any(\n        condition[\"role\"] == MINIMAX_H3_CONDITION_ROLE_REFERENCE\n        for condition in conditions\n    ):\n        raise ValueError(\n            \"ref2va keyframes require at least one reference condition; \"\n            \"use task 'fl2va' for keyframe-only generation\"\n        )\n\n\ndef minimax_h3_validate_canonical_request(\n    *,\n    task: Any,\n    prompt: Any,\n    conditions: Any,\n    target: Any,\n    flow_shift: Any = None,\n    audio_flow_shift: Any = None,\n    seed: Any = None,\n    **_extra_kwargs: Any,\n) -> dict[str, Any]:\n    \"\"\"Validate and normalize a `minimax_h3.request/v1` canonical request.\n","sourceCodeStart":254,"sourceCodeEnd":290,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/request_validation.py#L254-L290","documentation":"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.","triggerScenarios":"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.","commonSituations":"Prototyping with the fl2va-style payload and switching the task string to ref2va without adding a reference image; misunderstanding that ref2va = reference + keyframes.","solutions":["Add at least one {role:'reference', type:'image', ...} condition to the request","If you only want first/last-frame animation, use task 'fl2va' instead of 'ref2va'"],"exampleFix":"// before\n{\"task\":\"ref2va\",\"conditions\":[{\"role\":\"keyframe\",\"type\":\"image\",\"uri\":\"f.png\",\"frame_index\":0}]}\n// after\n{\"task\":\"ref2va\",\"conditions\":[{\"role\":\"reference\",\"type\":\"image\",\"uri\":\"ref.png\"},{\"role\":\"keyframe\",\"type\":\"image\",\"uri\":\"f.png\",\"frame_index\":0}]}","handlingStrategy":"validation","validationCode":"def ref2va_ok(task, conditions):\n    return task != \"ref2va\" or any(c.get(\"role\") == \"reference\" for c in conditions)","typeGuard":"null","tryCatchPattern":"null","preventionTips":["Use fl2va when no reference image is intended"],"tags":["minimax-h3","ref2va","task-validation","conditions"],"backgroundTag":"request-schema-validation-failed","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}