Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
fix(video): a poll answered 429 or 5xx asks the same request again; past the poll timeout the run names it
Soohong Kimc56a70713bbf
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex e42d770..53d84c7 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -2,6 +2,12 @@All notable public changes to `sprite-gen` are recorded here. Versions track the `version:` field in `SKILL.md` and `pyproject.toml`.+## Unreleased++- **Fix: a poll xAI answers 429 or 5xx asks the same request again — the clip is bought once.** `video`, `video-extend` and `video-edit` ended the run on any non-2xx poll, after xAI had accepted the request and may bill it, and the line read `(HTTP 429)` — what `video-set`, and any caller that backs off on a refused submission, answers by submitting the clip again: a second clip paid for, the first never published. A poll answered `429`, `500`, `502`, `503` or `504` is now asked again on the same `request_id`, after a wait that doubles from 8 s up to 60 s while the polls are refused and goes back to 4 s on an answer; a stderr note says each, the status in plain digits. The poll timeout (`SPRITE_GEN_VIDEO_TIMEOUT_SECONDS`) still bounds the whole poll: no wait runs past it, a pending poll's last wait included, and one last poll is asked at it. A refused POST is still never sent again, and a `400`, `401` or `404` poll still ends the run with its status.+- **Output change: a generation the poll timeout cut short is unfinished, named by its `request_id`.** Polls still pending or still refused at the timeout end the run with a line that names `request_id=<id>`, says the generation may still finish and be billed, and carries no `(HTTP <n>)` — that marks a refused submission, which a caller may send again unbilled. The pending line keeps its front (`still 'pending' after N polls — poll timeout;`). With `--report` the run leaves a `sprite-gen-video-unfinished` report there (`verb`, `auth_source`, `model`, `request_id`, `out`, `polls`, `polls_refused`, `last_poll`, `elapsed_seconds`) and prints nothing on stdout; Python callers catch `GenerationUnfinished`, a `SystemExit`. The success report gains `polls_refused`, how many of its `polls` xAI answered 429 or 5xx (docs/video.md, An unfinished generation).+- **`tests/gen/test_video.py`** scripts the polls: each of the five statuses refused twice, then pending, then done, is asked on the one request with waits 8, 16, 4 and published with `polls_refused` 2; polls refused until a 300 s timeout wait 8, 16, 32, 60 × 4 and 4, ask a ninth poll at the timeout and end unfinished with no `(HTTP n)` and no `HTTP 429` on stderr; a pending timeout names the request; a 400, 401 or 404 poll ends at once; a refused POST is sent once; the CLI leaves the unfinished report and an empty stdout. The 500-poll case of the failure table is a 404 now, the status that still ends a run.+## v2.44.0 - A filmed ghost in a loop delivered as cut is given way, or named a take to film again; restoration reads the ghost; the RIFE lane runs every real-RIFE test**Upgrading from 2.43.0: the restoration contract moves with the version.** Source restoration is now metric `source-restoration-v5` under policy `key-protected-source-copy-one-step-cap-jump-ghost-guard-v1`, and writes repair report `schema_version` 4 and comparison `schema_version` 6 (`sprite_gen.video.restoration`: `METRIC`, `POLICY`, `REPAIR_SCHEMA`, `COMPARISON_SCHEMA`); a consumer that checks these values raises all four with its pin. Nothing `source-restoration-v4` (2.40.0 – 2.43.0) wrote is read as v5: a v4 repair report given to `video-loop-compare` is an input error, and a request whose baseline carries a v4 receipt in its loop report is shared `unknown`, `restoration-receipt-policy-unsupported`. A loop restored under v4 therefore goes on from its origin, not its v4 baseline: the origin itself is still a valid first request (the same five files as origin and baseline). Proposal IDs change with the versions. `video-loop-compare` without the origin and the source (`same-sample-defects-v1`) is unchanged.diff --git a/docs/gen.md b/docs/gen.mdindex 864459e..8137aaa 100644--- a/docs/gen.md+++ b/docs/gen.md@@ -137,7 +137,10 @@ documented policy block (`sprite_gen/gen/refusal.py` `POLICY_CODES`: openai`moderation_blocked`, followed by `moderation_stage=input|output|unknown`). The`(HTTP <n>)` part never changes shape. The video verbs use the same `code=` andreason, and a clip xAI reports with `respect_moderation: false` is that refusal-with `respect_moderation=false` in place of a code (docs/video.md).+with `respect_moderation=false` in place of a code (docs/video.md). A clip xAI+accepted and the poll timeout cut short is no refusal: its line names+`request_id=<id>` and carries no `(HTTP <n>)`, so nothing that sends a refused+request again sends it (docs/video.md, An unfinished generation).`<body>` is the provider's error body as received, last on the line: JSON on oneline, anything else as its text (line breaks written as `\n`), nothing when the bodydiff --git a/docs/video.md b/docs/video.mdindex ec603d1..7007487 100644--- a/docs/video.md+++ b/docs/video.md@@ -145,8 +145,15 @@ What happens, in order:credential source and its fix; any reply without a `request_id` fails with theAPI's own error text.3. `GET /v1/videos/{request_id}` every 4 s until `status` is `done`. `failed`,- `expired`, a non-2xx poll, or the timeout (`SPRITE_GEN_VIDEO_TIMEOUT_SECONDS`,- default 600) fail loudly. Nothing is written on any failure path.+ `expired` or a non-2xx poll fails loudly — except a poll answered `429` or `500`,+ `502`, `503`, `504`: the request was accepted, so that poll is asked again on the+ same `request_id` (a new POST would buy the clip twice), after a wait that doubles+ from 8 s up to 60 s while the polls are refused and goes back to 4 s on an answer.+ A `[video] poll N of generation <id> was refused (429); asking again in 8s` line goes+ to stderr each time. The poll timeout (`SPRITE_GEN_VIDEO_TIMEOUT_SECONDS`, default+ 600, counted from the POST's answer) bounds the whole poll: no wait runs past it, one+ last poll is asked at it, and a generation still pending or refused then is+ *unfinished* (below). No clip is written on any failure path.4. Download `video.url`, verify the bytes start with an mp4 `ftyp` box, then movethe file into `--out` atomically (`.part` staging).@@ -195,13 +202,43 @@ refused locally with an ffmpeg trim hint; there is no `--duration` at all.`inputs` (local paths by role: `image`, `last_frame`, `reference_images`,`video`), `bytes`, `host`, requested/reported duration (`input_duration` forextend / edit), resolution, aspect ratio, audio flag, `elapsed_seconds`, and-`polls`. The pre-modes `image` field stays. **Tokens and download URLs are never+`polls`, and `polls_refused` (how many of `polls` xAI answered 429 or 5xx, each asked+again). The pre-modes `image` field stays. **Tokens and download URLs are neverprinted or written** — only the download host (`vidgen.x.ai`).+### An unfinished generation++xAI accepted the request and the poll timeout came before it ended — its polls still+pending, or still refused. It may finish and be billed, so the run ends naming the+request to ask for again, never as a refusal to send again:++```+video: generation <id> was accepted, but its polls were refused (last answer 429) until the poll timeout (600s, 14 polls); it may still finish and be billed — ask for request_id=<id> again instead of submitting a new request; nothing was written+video: generation <id> still 'pending' after 151 polls — poll timeout; it may still finish and be billed — ask for request_id=<id> again instead of submitting a new request; nothing was written+```++The line carries no `(HTTP <n>)`: on a video line that marks a refused submission+(docs/gen.md), which a caller may send again unbilled; the stderr notes before it say+the status in plain digits for the same reason. With `--report` the run leaves a+`sprite-gen-video-unfinished` report there, and nothing on stdout:++```json+{"kind": "sprite-gen-video-unfinished", "provider": "grok-imagine", "verb": "video",+ "auth_source": "grok-login", "model": "grok-imagine-video-1.5", "request_id": "<id>",+ "out": "/abs/clip.mp4", "polls": 14, "polls_refused": 14,+ "last_poll": {"http": 429, "status": null}, "elapsed_seconds": 600.0}+```++`auth_source` is the credential that submitted it — the one that can ask for it again.+A report already at that path is replaced, as on success. Every verb that polls+(`video`, `video-extend`, `video-edit`) does the same, `verb` naming it.+## Quotas and limits- Imagine quota is a weekly SuperGrok allowance; when it is exhausted the API- refuses the POST and the run fails with that message (no retry loop here).+ refuses the POST and the run fails with that message. A refused POST is never sent+ again here — the provider may have taken it; only a poll of an accepted request is+ asked again (step 3).- A refused request or a failed poll names the provider's code after the status,`(HTTP 400) code=invalid_argument`, read from a top-level `code` or the `error`object. `invalid_argument` covers moderation and bad parameters alike, so it isdiff --git a/sprite_gen/gen/video.py b/sprite_gen/gen/video.pyindex 10d3c30..1bd13fc 100644--- a/sprite_gen/gen/video.py+++ b/sprite_gen/gen/video.py@@ -94,12 +94,56 @@ MODE_EXTEND = "extend"MODE_EDIT = "edit"POLL_INTERVAL_SECONDS = 4.0POLL_TIMEOUT_SECONDS = int(os.environ.get("SPRITE_GEN_VIDEO_TIMEOUT_SECONDS", "600"))+# A poll xAI throttles (429) or fails on its own side (5xx) is asked again, on the same request:+# the POST was accepted, so a new submission would buy the clip twice. The wait doubles from+# POLL_INTERVAL_SECONDS while the polls are refused, up to the ceiling; no wait runs past the+# poll timeout, which bounds the whole poll however its polls are answered.+POLL_RETRY_STATUSES = frozenset({429, 500, 502, 503, 504})+POLL_BACKOFF_MAX_SECONDS = 60.0# Every mp4/mov starts with a size-prefixed `ftyp` box: bytes 4..8 spell it.MP4_FTYP_OFFSET = 4MP4_FTYP = b"ftyp"_DONE_STATUSES = ("done", "complete", "completed")_FAILED_STATUSES = ("failed", "error", "expired")++class GenerationUnfinished(SystemExit):+ """xAI accepted the request (it may bill it) and the poll timeout came before it ended.++ The line names `request_id=<id>` and carries no `(HTTP n)`: that marks a refused submission,+ which a caller may send again unbilled; this request is asked for again by its id instead.+ `to_dict()` is the report the CLI leaves at `--report`."""++ def __init__(self, message: str, *, verb: str, request_id: str, auth_source: str, model: Any, out: Path,+ polls: int, polls_refused: int, last_http: int, last_status: Any, elapsed_seconds: float) -> None:+ super().__init__(message)+ self.verb = verb+ self.request_id = request_id+ self.auth_source = auth_source+ self.model = model+ self.out = out+ self.polls = polls+ self.polls_refused = polls_refused+ self.last_http = last_http+ self.last_status = last_status+ self.elapsed_seconds = elapsed_seconds++ def to_dict(self) -> dict[str, Any]:+ return {+ "kind": "sprite-gen-video-unfinished",+ "provider": "grok-imagine",+ "verb": self.verb,+ "auth_source": self.auth_source,+ "model": self.model,+ "request_id": self.request_id,+ "out": str(self.out),+ "polls": self.polls,+ "polls_refused": self.polls_refused,+ "last_poll": {"http": self.last_http, "status": self.last_status},+ "elapsed_seconds": round(self.elapsed_seconds, 3),+ }++def http_download(url: str, token: str) -> bytes:request = urllib.request.Request(url)try:@@ -248,6 +292,7 @@ class VideoResult:polls: intduration_requested: intduration_reported: float | None = None+ polls_refused: int = 0 # polls xAI answered 429 or 5xx, each asked againhost: str | None = Noneimage: Path | None = Noneprompt: str = ""@@ -284,6 +329,7 @@ class VideoResult:"generate_audio": self.generate_audio,"elapsed_seconds": round(self.elapsed_seconds, 3),"polls": self.polls,+ "polls_refused": self.polls_refused,**({"extra": self.extra} if self.extra else {}),**({"facing": self.facing} if self.facing is not None else {}),}@@ -368,6 +414,7 @@ class _Published:duration_reported: float | Nonehost: str | Nonepolls: int+ polls_refused: intelapsed_seconds: float@@ -421,8 +468,9 @@ def _submit_poll_publish(f"{verb}: {refused.reason('generation request refused')} (HTTP {status}){refused.suffix()}: {_error_detail(reply, credential.token)}")- deadline = time.monotonic() + (POLL_TIMEOUT_SECONDS if poll_timeout is None else poll_timeout)- polls = 0+ timeout = POLL_TIMEOUT_SECONDS if poll_timeout is None else poll_timeout+ deadline = time.monotonic() + timeout+ polls = polls_refused = refused_in_a_row = 0video_url: str | None = Noneduration_reported: float | None = Nonemodel_reported: str | None = None@@ -446,19 +494,38 @@ def _submit_poll_publish(duration_reported = video.get("duration") if isinstance(video, dict) else Nonemodel_reported = poll.get("model")break- if http not in (200, 202) or poll_status in _FAILED_STATUSES:+ if http in POLL_RETRY_STATUSES:+ polls_refused += 1+ refused_in_a_row += 1+ wait = min(POLL_INTERVAL_SECONDS * 2 ** refused_in_a_row, POLL_BACKOFF_MAX_SECONDS)+ elif http not in (200, 202) or poll_status in _FAILED_STATUSES:# A failed poll carries `error` as an object `{code, message}`.refused = refusal.read("grok", poll)raise SystemExit(f"{verb}: generation {request_id} {refused.reason(f'ended with status={poll_status!r}')} "f"(HTTP {http}){refused.suffix()}: {_error_detail(poll, credential.token)}")- if time.monotonic() >= deadline:- raise SystemExit(- f"{verb}: generation {request_id} still {poll_status!r} after {polls} polls — poll timeout; "- "nothing was written"+ else:+ refused_in_a_row = 0+ wait = POLL_INTERVAL_SECONDS+ now = time.monotonic()+ if now >= deadline:+ stopped = (f"was accepted, but its polls were refused (last answer {http}) until the poll timeout "+ f"({timeout:g}s, {polls} polls)" if refused_in_a_row+ else f"still {poll_status!r} after {polls} polls — poll timeout")+ raise GenerationUnfinished(+ f"{verb}: generation {request_id} {stopped}; it may still finish and be billed — ask for "+ f"request_id={request_id} again instead of submitting a new request; nothing was written",+ verb=verb, request_id=str(request_id), auth_source=credential.source, model=body.get("model"),+ out=out, polls=polls, polls_refused=polls_refused, last_http=http, last_status=poll_status,+ elapsed_seconds=now - started,)- sleep(POLL_INTERVAL_SECONDS)+ wait = min(wait, deadline - now)+ if refused_in_a_row:+ # The status in plain digits: `(HTTP n)` on this stream reads as a refused submission.+ print(f"[{verb}] poll {polls} of generation {request_id} was refused ({http}); "+ f"asking again in {wait:g}s", file=sys.stderr)+ sleep(wait)if not video_url:raise SystemExit(f"{verb}: generation {request_id} is done but reported no video url")@@ -478,7 +545,7 @@ def _submit_poll_publish(os.replace(tmp, out)return _Published(data=data, request_id=str(request_id), model=model_reported, duration_reported=duration_reported,- host=_redact_host(video_url), polls=polls, elapsed_seconds=elapsed,+ host=_redact_host(video_url), polls=polls, polls_refused=polls_refused, elapsed_seconds=elapsed,)@@ -542,6 +609,7 @@ def generate_video(auth_source=credential.source,elapsed_seconds=published.elapsed_seconds,polls=published.polls,+ polls_refused=published.polls_refused,duration_requested=request.duration,duration_reported=published.duration_reported,host=published.host,@@ -622,6 +690,7 @@ def extend_video(return VideoResult(out=out, bytes=len(published.data), model=published.model or request.model, request_id=published.request_id,auth_source=credential.source, elapsed_seconds=published.elapsed_seconds, polls=published.polls,+ polls_refused=published.polls_refused,duration_requested=request.duration, duration_reported=published.duration_reported, host=published.host,prompt=request.prompt, mode=MODE_EXTEND, inputs={"video": str(clip)}, input_duration=input_seconds,output_duration=measured.get("output"),@@ -682,6 +751,7 @@ def edit_video(return VideoResult(out=out, bytes=len(published.data), model=published.model or request.model, request_id=published.request_id,auth_source=credential.source, elapsed_seconds=published.elapsed_seconds, polls=published.polls,+ polls_refused=published.polls_refused,duration_requested=0, duration_reported=published.duration_reported, host=published.host,prompt=request.prompt, mode=MODE_EDIT, inputs={"video": str(clip)}, input_duration=input_seconds,output_duration=measured.get("output"),@@ -748,10 +818,18 @@ def _read_prompt(args: argparse.Namespace) -> str:return (prompt or "").strip()-def _publish_report(args: argparse.Namespace, result: VideoResult) -> int:+def _publish_report(args: argparse.Namespace, make: Callable[[], VideoResult]) -> int:+ report_path = Path(args.report).expanduser().resolve() if args.report else None+ try:+ result = make()+ except GenerationUnfinished as unfinished:+ # The request is xAI's now and may still finish: the report names it, so whoever ran this+ # asks for that id again instead of buying a second clip. Nothing goes to stdout.+ if report_path is not None:+ atomic_write_text(report_path, json.dumps(unfinished.to_dict(), ensure_ascii=False, indent=2) + "\n")+ raisepayload = result.to_dict()- if args.report:- report_path = Path(args.report).expanduser().resolve()+ if report_path is not None:atomic_write_text(report_path, json.dumps(payload, ensure_ascii=False, indent=2) + "\n")payload["report"] = str(report_path)_print_json(payload)@@ -772,17 +850,17 @@ def _run(args: argparse.Namespace) -> int:reference_images=list(args.reference_images or []),direction=args.direction, facing=args.facing, facing_fix=args.facing_fix,)- return _publish_report(args, generate_video(request))+ return _publish_report(args, lambda: generate_video(request))def _run_extend(args: argparse.Namespace) -> int:request = ExtendRequest(video=args.video, prompt=_read_prompt(args), out=args.out, duration=args.duration)- return _publish_report(args, extend_video(request))+ return _publish_report(args, lambda: extend_video(request))def _run_edit(args: argparse.Namespace) -> int:request = EditRequest(video=args.video, prompt=_read_prompt(args), out=args.out)- return _publish_report(args, edit_video(request))+ return _publish_report(args, lambda: edit_video(request))def _build_parser() -> argparse.ArgumentParser: