Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
# SPDX-License-Identifier: Apache-2.0
"""Grok video modes wired into `sprite-gen video` / `video-extend` / `video-edit`:
request bodies per mode, the unchanged image-to-video body, local pre-checks that
run before any call, and the report's `mode` / `inputs`. No network — HTTP is a fake."""
from __future__ import annotations
import json
import re
from pathlib import Path
import pytest
from PIL import Image
from sprite_gen.gen import video
MP4 = b"\x00\x00\x00\x18ftypisom" + b"\x00" * 64
CRED = video.Credential(token="tok", source=video.AUTH_SOURCE_GROK_LOGIN)
def _still(tmp_path: Path, name: str = "still.png", size=(8, 8)) -> Path:
path = tmp_path / name
Image.new("RGBA", size, (255, 120, 0, 255)).save(path)
return path
def _clip(tmp_path: Path, name: str = "in.mp4", payload: bytes = MP4) -> Path:
path = tmp_path / name
path.write_bytes(payload)
return path
class _FakeApi:
def __init__(self, post=(200, {"request_id": "req-1"}), done=None):
self.post = post
self.done = done or {"status": "done", "video": {"url": "https://vidgen.x.ai/v/1.mp4", "duration": 5.04}, "model": "grok-imagine-video-1.5"}
self.calls: list[tuple[str, str, str, dict | None]] = []
def call(self, method, url, token, body, *, deadline=None):
self.calls.append((method, url, token, body))
return self.post if method == "POST" else (200, self.done)
def download(self, url, token, *, deadline=None):
return MP4
def kw(self):
return dict(credential=CRED, call=self.call, download=self.download, sleep=lambda s: None)
@property
def body(self) -> dict:
return self.calls[0][3]
@property
def endpoint(self) -> str:
return self.calls[0][1]
def _gen(tmp_path: Path, **overrides) -> video.VideoRequest:
kwargs = dict(image=None, prompt="she charges at the oni", out=tmp_path / "clip.mp4")
kwargs.update(overrides)
return video.VideoRequest(**kwargs)
# --- the image-to-video body is what it was -------------------------------------
def test_image_only_body_is_the_pre_modes_snapshot(tmp_path: Path) -> None:
still = _still(tmp_path)
api = _FakeApi()
result = video.generate_video(_gen(tmp_path, image=still, duration=6, resolution="720p"), **api.kw())
assert api.endpoint == "https://api.x.ai/v1/videos/generations"
assert list(api.body) == ["model", "prompt", "duration", "resolution", "image"]
assert api.body == {
"model": "grok-imagine-video-1.5",
"prompt": "she charges at the oni",
"duration": 6,
"resolution": "720p",
"image": {"url": video._data_url(still)},
}
assert result.mode == "image-to-video"
payload = result.to_dict()
assert payload["mode"] == "image-to-video" and payload["inputs"] == {"image": str(still.resolve())}
assert payload["image"] == str(still.resolve()) # the pre-modes field stays
assert "input_duration" not in payload
def test_image_only_body_with_aspect_and_audio_keeps_its_key_order(tmp_path: Path) -> None:
api = _FakeApi()
video.generate_video(_gen(tmp_path, image=_still(tmp_path), aspect_ratio="1:1", generate_audio=False), **api.kw())
assert list(api.body) == ["model", "prompt", "duration", "resolution", "image", "aspect_ratio", "generate_audio"]
assert "last_frame" not in api.body and "reference_images" not in api.body
def test_report_keeps_every_pre_modes_field(tmp_path: Path) -> None:
api = _FakeApi()
payload = video.generate_video(_gen(tmp_path, image=_still(tmp_path)), **api.kw()).to_dict()
assert set(payload) >= {
"kind", "provider", "auth_source", "model", "request_id", "image", "prompt", "out", "bytes", "host",
"duration_requested", "duration_reported", "resolution", "aspect_ratio", "generate_audio", "elapsed_seconds", "polls",
}
# --- first/last frame and reference bodies --------------------------------------
def test_first_and_last_frame_posts_image_and_last_frame(tmp_path: Path) -> None:
first, last = _still(tmp_path, "first.png"), _still(tmp_path, "last.png")
api = _FakeApi()
result = video.generate_video(_gen(tmp_path, image=first, last_frame=last, resolution="480p", duration=5, aspect_ratio="16:9"), **api.kw())
assert api.endpoint.endswith("/videos/generations") and api.body["model"] == "grok-imagine-video-1.5"
assert api.body["image"] == {"url": video._data_url(first)}
assert api.body["last_frame"] == {"url": video._data_url(last)}
assert "reference_images" not in api.body
assert result.mode == "first-last"
assert result.to_dict()["inputs"] == {"image": str(first.resolve()), "last_frame": str(last.resolve())}
def test_last_frame_alone_posts_no_image(tmp_path: Path) -> None:
last = _still(tmp_path, "last.png")
api = _FakeApi()
result = video.generate_video(_gen(tmp_path, last_frame=last), **api.kw())
assert "image" not in api.body and api.body["last_frame"] == {"url": video._data_url(last)}
assert result.mode == "last-frame"
payload = result.to_dict()
assert payload["image"] is None and payload["inputs"] == {"last_frame": str(last.resolve())}
def test_reference_to_video_posts_reference_images_in_order(tmp_path: Path) -> None:
refs = [_still(tmp_path, f"ref{i}.png") for i in range(3)]
api = _FakeApi()
result = video.generate_video(
_gen(tmp_path, prompt="<IMAGE_0> fights <IMAGE_1> in <IMAGE_2>", reference_images=refs, resolution="480p"), **api.kw()
)
assert api.body["reference_images"] == [{"url": video._data_url(r)} for r in refs]
assert "image" not in api.body and "last_frame" not in api.body
assert result.mode == "reference"
payload = result.to_dict()
assert payload["inputs"] == {"reference_images": [str(r.resolve()) for r in refs]}
assert "data:" not in json.dumps(payload) and "vidgen.x.ai/v/1.mp4" not in json.dumps(payload)
def test_reference_with_image_keeps_both(tmp_path: Path) -> None:
api = _FakeApi()
result = video.generate_video(_gen(tmp_path, image=_still(tmp_path, "a.png"), reference_images=[_still(tmp_path, "r.png")], prompt="<IMAGE_0>"), **api.kw())
assert "image" in api.body and len(api.body["reference_images"]) == 1
assert result.mode == "reference"
# --- local pre-checks run before any call ---------------------------------------
@pytest.mark.parametrize(
("build", "expected"),
[
(lambda t: _gen(t), "pass --image, --last-frame and/or --reference"),
(lambda t: _gen(t, last_frame=t / "missing.png"), "--last-frame still image not found"),
(lambda t: _gen(t, reference_images=[t / "missing.png"], prompt="<IMAGE_0>"), "--reference still image not found"),
(lambda t: _gen(t, reference_images=[_still(t, f"r{i}.png") for i in range(8)]), "at most 7 --reference"),
(lambda t: _gen(t, reference_images=[_still(t)], resolution="1080p"), "capped at 720p"),
(lambda t: _gen(t, reference_images=[_still(t), _still(t, "b.png")], prompt="<IMAGE_0> and <IMAGE_2>"), "<IMAGE_2> but only 2 --reference"),
(lambda t: _gen(t, image=_still(t), prompt="<IMAGE_0> walks"), "<IMAGE_0> but no --reference"),
(lambda t: _gen(t, image=_still(t), last_frame=_still(t, "l.png"), model=video.CLASSIC_MODEL), "classic grok-imagine-video rejects last_frame"),
(lambda t: _gen(t, image=_still(t), reference_images=[_still(t, "r.png")], model=video.CLASSIC_MODEL), "rejects --image combined with --reference"),
],
)
def test_mode_precheck_rejects_before_any_call(tmp_path: Path, build, expected) -> None:
api = _FakeApi()
with pytest.raises(SystemExit, match=expected):
video.generate_video(build(tmp_path), **api.kw())
assert api.calls == []
def test_seven_references_and_tag_zero_to_six_are_accepted(tmp_path: Path) -> None:
refs = [_still(tmp_path, f"r{i}.png") for i in range(7)]
api = _FakeApi()
video.generate_video(_gen(tmp_path, reference_images=refs, prompt=" ".join(f"<IMAGE_{i}>" for i in range(7))), **api.kw())
assert len(api.body["reference_images"]) == 7
# --- video-extend ----------------------------------------------------------------
def _ext(tmp_path: Path, **overrides) -> video.ExtendRequest:
kwargs = dict(video=_clip(tmp_path), prompt="she presses the attack", out=tmp_path / "longer.mp4")
kwargs.update(overrides)
return video.ExtendRequest(**kwargs)
def _probe(input_seconds: float, output_seconds: float):
"""ffprobe stand-in: the input clip vs the staged `.part` download."""
return lambda clip: output_seconds if clip.name.endswith(".part") else input_seconds
def test_extend_posts_classic_model_to_extensions_and_inherits_the_rest(tmp_path: Path) -> None:
# Live 2026-09-13: the poll's video.duration is the seconds ADDED (5), the bytes are 20.04 s.
api = _FakeApi(done={"status": "done", "video": {"url": "https://vidgen.x.ai/v/2.mp4", "duration": 5}, "model": "grok-imagine-video"})
result = video.extend_video(_ext(tmp_path, duration=5), probe=_probe(15.04, 20.04), **api.kw())
assert api.endpoint == "https://api.x.ai/v1/videos/extensions"
assert list(api.body) == ["model", "prompt", "duration", "video"]
assert api.body["model"] == "grok-imagine-video" and api.body["duration"] == 5
assert api.body["video"]["url"].startswith("data:video/mp4;base64,")
assert "resolution" not in api.body and "aspect_ratio" not in api.body
payload = result.to_dict()
assert payload["mode"] == "extend" and payload["inputs"] == {"video": str((tmp_path / "in.mp4").resolve())}
assert payload["input_duration"] == 15.04 and payload["output_duration"] == 20.04
assert payload["duration_reported"] == 5 and payload["duration_requested"] == 5
assert result.out.read_bytes() == MP4
def test_extend_refuses_a_result_shorter_than_the_input_measured_from_bytes(tmp_path: Path) -> None:
# The poll claims 17 s; the downloaded bytes are 5 s. Bytes win, nothing is published.
api = _FakeApi(done={"status": "done", "video": {"url": "https://vidgen.x.ai/v/2.mp4", "duration": 17.0}, "model": "grok-imagine-video"})
request = _ext(tmp_path)
with pytest.raises(SystemExit, match="returned clip is 5.00s for a 12.00s input — not an extension"):
video.extend_video(request, probe=_probe(12.0, 5.0), **api.kw())
assert not request.out.exists() and not list(tmp_path.glob("*.part"))
@pytest.mark.parametrize(
("build", "seconds", "expected"),
[
(lambda t: _ext(t, prompt=" "), 5.0, "empty prompt"),
(lambda t: _ext(t, model=video.DEFAULT_MODEL), 5.0, "only the classic grok-imagine-video supports extension"),
(lambda t: _ext(t, duration=1), 5.0, "2..10 seconds"),
(lambda t: _ext(t, duration=11), 5.0, "2..10 seconds"),
(lambda t: _ext(t, video=_clip(t, "in.mov")), 5.0, "must be an .mp4"),
(lambda t: _ext(t, video=t / "nope.mp4"), 5.0, "input clip not found"),
(lambda t: _ext(t, video=_clip(t, "bad.mp4", b"<html>")), 5.0, "not an mp4"),
(lambda t: _ext(t), 1.5, "extends clips of 2..15s"),
(lambda t: _ext(t), 15.11, "extends clips of 2..15s"),
],
)
def test_extend_precheck_rejects_before_any_call(tmp_path: Path, build, seconds, expected) -> None:
api = _FakeApi()
with pytest.raises(SystemExit, match=expected):
video.extend_video(build(tmp_path), probe=lambda clip: seconds, **api.kw())
assert api.calls == []
# --- video-edit ------------------------------------------------------------------
def _edit(tmp_path: Path, **overrides) -> video.EditRequest:
kwargs = dict(video=_clip(tmp_path), prompt="change her hakama to solid black", out=tmp_path / "edited.mp4")
kwargs.update(overrides)
return video.EditRequest(**kwargs)
def test_edit_posts_classic_model_to_edits_without_duration(tmp_path: Path) -> None:
api = _FakeApi(done={"status": "done", "video": {"url": "https://vidgen.x.ai/v/3.mp4", "duration": 7.71}, "model": "grok-imagine-video"})
result = video.edit_video(_edit(tmp_path), probe=_probe(8.0, 7.71), **api.kw())
assert api.endpoint == "https://api.x.ai/v1/videos/edits"
assert list(api.body) == ["model", "prompt", "video"]
assert api.body["model"] == "grok-imagine-video"
payload = result.to_dict()
assert payload["mode"] == "edit" and payload["input_duration"] == 8.0 and payload["output_duration"] == 7.71
assert payload["inputs"] == {"video": str((tmp_path / "in.mp4").resolve())}
@pytest.mark.parametrize(
("build", "seconds", "expected"),
[
(lambda t: _edit(t), 8.71, "at most 8.7s"),
(lambda t: _edit(t, video=_clip(t, "in.webm")), 5.0, "must be an .mp4"),
(lambda t: _edit(t, model=video.DEFAULT_MODEL), 5.0, "only the classic grok-imagine-video supports editing"),
(lambda t: _edit(t, prompt=""), 5.0, "empty prompt"),
],
)
def test_edit_precheck_rejects_before_any_call(tmp_path: Path, build, seconds, expected) -> None:
api = _FakeApi()
with pytest.raises(SystemExit, match=expected):
video.edit_video(build(tmp_path), probe=lambda clip: seconds, **api.kw())
assert api.calls == []
@pytest.mark.parametrize("spelling", ["same", "capitals"])
@pytest.mark.parametrize("verb", ["extend", "edit"])
def test_the_result_is_never_published_over_the_clip_it_is_made_from(tmp_path: Path, verb: str, spelling: str) -> None:
"""`--out` naming the input clip — as given, or spelt in capitals on a volume that ignores case — is refused before
any call: the result is published over `--out`, which would replace the clip."""
given = MP4 + b"the input clip"
api = _FakeApi(done={"status": "done", "video": {"url": "https://vidgen.x.ai/v/4.mp4", "duration": 5}, "model": "grok-imagine-video"})
clip = tmp_path / "take.mp4"
out = clip if spelling == "same" else tmp_path / "TAKE.MP4"
request = _ext(tmp_path, video=clip, out=out) if verb == "extend" else _edit(tmp_path, video=clip, out=out)
_clip(tmp_path, "take.mp4", given) # after the request: `_ext`/`_edit` write their own default clip, `in.mp4`
if not out.exists():
pytest.skip("대소문자를 가리는 볼륨 — 철자가 다르면 다른 파일이다")
make = video.extend_video if verb == "extend" else video.edit_video
try:
make(request, probe=_probe(5.0, 10.0), **api.kw())
said = "published"
except SystemExit as refusal:
said = str(refusal)
assert clip.read_bytes() == given, f"video-{verb} 이 입력 클립 위에 결과를 내놓았다 ({said}, calls {len(api.calls)})"
assert re.search(rf"video-{verb}: --video and --out are the same file", said), said
assert api.calls == []
@pytest.mark.parametrize("verb", ["extend", "edit"])
def test_the_download_is_never_staged_through_a_link_to_the_clip(tmp_path: Path, verb: str) -> None:
"""The result is downloaded to `<out>.part` before it is published over `--out`: a `<out>.part` already there as a
link to the input clip is refused before any call — the download would be written through it, over the clip."""
given = MP4 + b"the input clip"
api = _FakeApi(done={"status": "done", "video": {"url": "https://vidgen.x.ai/v/5.mp4", "duration": 5}, "model": "grok-imagine-video"})
clip, out = tmp_path / "take.mp4", tmp_path / "result.mp4"
request = _ext(tmp_path, video=clip, out=out) if verb == "extend" else _edit(tmp_path, video=clip, out=out)
_clip(tmp_path, "take.mp4", given)
(tmp_path / "result.mp4.part").symlink_to(clip)
make = video.extend_video if verb == "extend" else video.edit_video
try:
make(request, probe=_probe(5.0, 10.0), **api.kw())
said = "published"
except SystemExit as refusal:
said = str(refusal)
assert clip.read_bytes() == given, f"video-{verb} 이 <out>.part 링크를 지나 입력 클립 위에 내려받았다 ({said}, calls {len(api.calls)})"
assert re.search(rf"video-{verb}: --video and result\.mp4\.part beside --out are the same file", said), said
assert api.calls == []
@pytest.mark.parametrize("verb", ["extend", "edit"])
def test_the_report_is_never_written_over_the_clip_it_is_made_from(tmp_path: Path, monkeypatch, verb: str) -> None:
"""`--report` naming the input clip is refused before any call: the report is written once the result is made, and
would replace the clip."""
given = MP4 + b"the input clip"
api = _FakeApi(done={"status": "done", "video": {"url": "https://vidgen.x.ai/v/6.mp4", "duration": 5}, "model": "grok-imagine-video"})
monkeypatch.setattr(video, "resolve_credential", lambda **_: CRED)
monkeypatch.setattr(video, "http_json", api.call)
monkeypatch.setattr(video, "http_download", api.download)
monkeypatch.setattr(video.time, "sleep", lambda s: None)
monkeypatch.setattr(video, "probe_duration_seconds", lambda clip, *, verb: 11.0 if clip.name.endswith(".part") else 6.0)
clip = _clip(tmp_path, "take.mp4", given)
run = video.run_extend if verb == "extend" else video.run_edit
try:
run(video=clip, prompt="go on", prompt_file=None, out=tmp_path / "result.mp4", report=clip,
**({"duration": 5} if verb == "extend" else {}))
said = "written"
except SystemExit as refusal:
said = str(refusal)
assert clip.read_bytes() == given, f"video-{verb} 이 입력 클립 위에 보고서를 썼다 ({said}, calls {len(api.calls)})"
assert re.search(rf"video-{verb}: --video and --report are the same file", said), said
assert api.calls == []
def test_edit_accepts_exactly_the_limit(tmp_path: Path) -> None:
api = _FakeApi()
video.edit_video(_edit(tmp_path), probe=lambda clip: 8.7, **api.kw())
assert len(api.calls) >= 1
# --- ffprobe ---------------------------------------------------------------------
def test_missing_ffprobe_is_loud(tmp_path: Path, monkeypatch) -> None:
monkeypatch.setattr(video.shutil, "which", lambda name: None)
with pytest.raises(SystemExit, match="ffprobe is required"):
video.probe_duration_seconds(_clip(tmp_path), verb="video-edit")
def test_probe_reads_ffprobe_output(tmp_path: Path, monkeypatch) -> None:
class Proc:
returncode, stdout, stderr = 0, "8.004000\n", ""
monkeypatch.setattr(video.shutil, "which", lambda name: "/usr/bin/ffprobe")
monkeypatch.setattr(video.subprocess, "run", lambda *a, **k: Proc())
assert video.probe_duration_seconds(_clip(tmp_path), verb="video-edit") == pytest.approx(8.004)
# --- CLI parsers and the unified CLI ---------------------------------------------
def test_video_parser_takes_last_frame_and_repeated_references() -> None:
parser = video._build_parser()
args = parser.parse_args(["--last-frame", "b.png", "--prompt", "p", "--out", "o.mp4"])
assert args.image is None and args.last_frame == Path("b.png") and args.reference_images is None
args = parser.parse_args(["--reference", "x.png", "--reference", "y.png", "--image", "a.png", "--prompt", "<IMAGE_0>", "--out", "o.mp4"])
assert args.reference_images == [Path("x.png"), Path("y.png")] and args.image == Path("a.png")
def test_extend_and_edit_parsers_have_no_resolution_aspect_or_model_flags() -> None:
extend = video._build_extend_parser()
args = extend.parse_args(["--video", "in.mp4", "--prompt", "p", "--out", "o.mp4"])
assert args.duration == video.EXTEND_DURATION_DEFAULT == 6
for bad in (["--resolution", "480p"], ["--aspect-ratio", "16:9"], ["--model", "grok-imagine-video-1.5"]):
with pytest.raises(SystemExit):
extend.parse_args(["--video", "in.mp4", "--prompt", "p", "--out", "o.mp4", *bad])
edit = video._build_edit_parser()
edit.parse_args(["--video", "in.mp4", "--prompt", "p", "--out", "o.mp4"])
for bad in (["--duration", "5"], ["--resolution", "480p"], ["--aspect-ratio", "16:9"], ["--model", "x"]):
with pytest.raises(SystemExit):
edit.parse_args(["--video", "in.mp4", "--prompt", "p", "--out", "o.mp4", *bad])
def test_unified_cli_exposes_extend_and_edit_under_gen() -> None:
from sprite_gen import cli
assert {"video-extend", "video-edit"} <= set(cli.COMMANDS)
assert {"video", "video-extend", "video-edit"} <= set(cli.command_domains()["gen"])
assert not ({"video-extend", "video-edit"} & set(cli.command_domains().get("video", [])))
parser = cli._build_parser()
assert parser.parse_args(["video-extend", "--video", "in.mp4", "--prompt", "p", "--out", "o.mp4", "--duration", "5"]).command == "video-extend"
assert parser.parse_args(["video-edit", "--video", "in.mp4", "--prompt", "p", "--out", "o.mp4"]).command == "video-edit"
assert parser.parse_args(["video", "--last-frame", "b.png", "--prompt", "p", "--out", "o.mp4"]).command == "video"
def test_pipeline_verbs_are_untouched_by_the_new_modes() -> None:
from sprite_gen import _modules
pipeline_b = next(p for p in _modules.PIPELINES if p["key"] == "B")
assert "video-extend" not in pipeline_b["verbs"] and "video-edit" not in pipeline_b["verbs"]
def test_run_extend_kwargs_writes_report(tmp_path: Path, monkeypatch) -> None:
api = _FakeApi(done={"status": "done", "video": {"url": "https://vidgen.x.ai/v/2.mp4", "duration": 11.0}, "model": "grok-imagine-video"})
monkeypatch.setattr(video, "resolve_credential", lambda **_: CRED)
monkeypatch.setattr(video, "http_json", api.call)
monkeypatch.setattr(video, "http_download", api.download)
monkeypatch.setattr(video.time, "sleep", lambda s: None)
monkeypatch.setattr(video, "probe_duration_seconds", lambda clip, *, verb: 11.0 if clip.name.endswith(".part") else 6.0)
out, report = tmp_path / "longer.mp4", tmp_path / "longer.report.json"
rc = video.run_extend(video=_clip(tmp_path), prompt="go on", prompt_file=None, out=out, duration=5, report=report)
assert rc == 0 and out.read_bytes() == MP4
payload = json.loads(report.read_text(encoding="utf-8"))
assert payload["mode"] == "extend" and payload["model"] == "grok-imagine-video"
assert payload["input_duration"] == 6.0 and payload["output_duration"] == 11.0
with pytest.raises(TypeError, match="unexpected keyword"):
video.run_edit(video=_clip(tmp_path), prompt="p", prompt_file=None, out=out, report=None, duration=5)