Skip to content

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.md
index 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.md
index 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=` and
reason, 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 one
line, anything else as its text (line breaks written as `\n`), nothing when the body
diff --git a/docs/video.md b/docs/video.md
index 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 the
API'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 move
the 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` for
extend / 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 never
printed 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 is
diff --git a/sprite_gen/gen/video.py b/sprite_gen/gen/video.py
index 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.0
POLL_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 = 4
MP4_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: int
duration_requested: int
duration_reported: float | None = None
+ polls_refused: int = 0 # polls xAI answered 429 or 5xx, each asked again
host: str | None = None
image: Path | None = None
prompt: 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 | None
host: str | None
polls: int
+ polls_refused: int
elapsed_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 = 0
video_url: str | None = None
duration_reported: float | None = None
model_reported: str | None = None
@@ -446,19 +494,38 @@ def _submit_poll_publish(
duration_reported = video.get("duration") if isinstance(video, dict) else None
model_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")
+ raise
payload = 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: