Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

docs(gen, capabilities): provider addresses and subscription logins off in docs/gen.md, docs/capabilities.md for the new verb, pointers from video, pixel-draw and sound, the SKILL.md route and the CHANGELOG's Unreleased (v3.9.0)

Soohong Kimc535d74e1a9b
diff --git a/CHANGELOG.md b/CHANGELOG.md
index fbc09cb..889c9ce 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,17 @@
All notable public changes to `sprite-gen` are recorded here. Versions track the `version:` field in `SKILL.md` and `pyproject.toml`.
+## Unreleased (v3.9.0)
+
+**Upgrading from 3.8.0: nothing changes unless you set one of the new variables. Each provider's calls can go to another address (`SPRITE_GEN_OPENAI_BASE_URL`, `SPRITE_GEN_XAI_BASE_URL`, `SPRITE_GEN_ANTHROPIC_BASE_URL`, `SPRITE_GEN_ELEVENLABS_BASE_URL`), `SPRITE_GEN_LOGINS=off` runs every call on its API key, and the new verb `sprite-gen capabilities` prints every verb and argument as one JSON line. Unset, every request goes where it went with the same bytes, and every output keeps its bytes except `sprite-gen --help`, which lists the new verb.**
+
+- **New: provider addresses.** Each of the four providers sprite-gen calls over HTTP has a variable that replaces its documented address (the API root with its version path, `https://api.openai.com/v1`, `https://api.x.ai/v1`, `https://api.anthropic.com/v1`, `https://api.elevenlabs.io/v1`). It is read when each request is made, not at import, so a value set or changed after the engine is imported is followed. Unset, empty or blank is the documented address. It moves every direct call: OpenAI images, edits and vision checks; Grok images, edits and vision checks, the video facing check, the video requests, polls and `video-resume`; Anthropic messages and Message Batches; ElevenLabs sound. A value that is not an `http://` or `https://` address with no query or fragment stops the call naming the variable.
+- **New: a URL a provider hands back is fetched through the same address.** With `SPRITE_GEN_XAI_BASE_URL` set, the finished clip is downloaded as `GET <value>/sprite-gen/fetch?url=<the clip's URL, percent-encoded>`, first without a token and once more with the bearer token after a 401 or 403, as before. With `SPRITE_GEN_ANTHROPIC_BASE_URL` set, a batch's results file comes the same way with the API key. A relay that forwards the provider's API forwards these too. Unset, the URL is fetched where it points.
+- **New: `SPRITE_GEN_LOGINS=off`.** No subscription login is read: the grok login file (and `GROK_HOME`) is not looked at and `XAI_API_KEY` is used, `claude auth status` is not run and `ANTHROPIC_API_KEY` is used, and codex is not usable (`codex login status` is not run; a default codex asks or runs what you chose for a codex that cannot run, naming the variable, and `--provider codex` stops). Each key keeps its rule: set but empty is refused, and a missing key stops the call naming the key and the variable. Unset or empty is `on`, the order as before; any other value is refused.
+- **New: `sprite-gen capabilities`.** One JSON line: every verb (domain, description, old names, sub-verbs) and every argument as the CLI's parser holds it (spellings, type, how many values, default, required, choices, groups of which one is given), the providers each verb may call and whether it may be billed (`video-resume` calls xAI and buys nothing), and the provider and login variables. It is read off the parser, so a verb or flag added to the CLI is listed with nothing else written. At this release it is 42,025 bytes, where every `--help` together is 156,490.
+- Python callers: new module `sprite_gen.gen.address` (`PROVIDERS`, `base`, `url`, `fetched`, `FETCH_PATH`), `sprite_gen.gen.base.LOGINS_ENV`, `LOGINS_OFF` and `logins_on`, new module `sprite_gen.workflow.capabilities` (`document`, `PROVIDER_CALLS`, `NO_PURCHASE`). Removed: the module constants `xai.API_BASE`, `openai_provider.API_BASE`, `anthropic_api.API_BASE` and `sprite_gen.audio.provider.BASE`, which kept a provider's address where a variable could not move it; `video` no longer copies the xAI address at import.
+- **Tests**: `tests/gen/test_provider_address.py` (every call site against a local relay, the address unset, empty and blank, a value changed after import, the relay given the request's bytes, the clip and results file fetched through it, refused values, no module but the registry naming an address and none reading it at import), `tests/gen/test_logins_off.py` (each route on and off, the empty key refusal kept, codex's question and refusals, the access check), `tests/workflow/test_capabilities.py` (the document against the parser and every verb's printed options, a verb or flag added is listed, the providers, the size against every `--help`).
+
## v3.8.0 - Held cells found and filled with in-betweens by default, and a cut given above its clip's frame rate (--out-fps)
**Upgrading from 3.7.0: `video-loop` (and so `video-set`) now finds neighbour cells of a cut that show the same picture and, by default, makes them again with RIFE's frames between. A cut with no such cell comes out byte for byte as before. A cut with them comes out with its held cells made, its length, beat, first and last cells and wrap unchanged. `--fill-held off` cuts as before. Every cut's report and strip metadata gain `held_fill`.**
diff --git a/SKILL.md b/SKILL.md
index 7e65e4c..91b497a 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -122,6 +122,7 @@ front-facing observations also remain unchanged. Mirroring does not preserve lef
| Standalone projected shadow | `shadow` | [asset-tools](docs/asset-tools.md#projected-shadows) |
| Duplicate poses, foot contact and stride measurement | `inspect-motion` | [asset-tools](docs/asset-tools.md#motion-and-contact-evidence) |
| Optional scene placement, lighting, camera and render | `scene-render`, `scene-inspect` | [scene](docs/scene.md) |
+| What the engine can do, for an agent or a tool to read once: every verb and argument, the providers each may call and be billed by (one JSON line, a quarter of every `--help`); a sandbox that reaches the providers through a relay: `SPRITE_GEN_<PROVIDER>_BASE_URL` (`OPENAI`, `XAI`, `ANTHROPIC`, `ELEVENLABS`) moves a provider's calls and the files it hands back, `SPRITE_GEN_LOGINS=off` runs every call on its API key | `capabilities` | [capabilities](docs/capabilities.md), [provider addresses](docs/gen.md#provider-addresses) |
| Defaults | `defaults show`, `defaults save` (`--codex-unavailable ask\|grok\|openai`: what to do when codex cannot run), `defaults clear` | [user-workflow](docs/user-workflow.md#one-settings-owner) |
Say a thing once: what an option says, leave out of the prompt. `--direction`, `--facing`, `--handed`, the key background and `video --direction side` each add their own sentence after your text, in one place. Your prompt carries the subject, its design and its pose. Text that says the opposite of an option ("facing left" with `--facing right`, the item on the other wrist) is sent as written with a warning (`extra.prompt_notes`, `video-prompt`'s `warnings`): fix the prompt, do not send it — [prompt-assembly](docs/prompt-assembly.md).
diff --git a/docs/README.md b/docs/README.md
index 49f049f..5efa006 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -78,7 +78,7 @@ grouping is derived from `sprite_gen/_modules.py`, the one taxonomy table.
| Doc | Owns |
|---|---|
-| [gen.md](gen.md) | `sprite-gen gen` / `gen-set`: providers, default resolution and what a default codex that cannot run turns into, transparency strategy per provider, when a refused provider request is sent again, row usage |
+| [gen.md](gen.md) | `sprite-gen gen` / `gen-set`: providers, default resolution and what a default codex that cannot run turns into, transparency strategy per provider, where every direct provider call goes (`SPRITE_GEN_<PROVIDER>_BASE_URL`) and subscription logins off (`SPRITE_GEN_LOGINS`), when a refused provider request is sent again, row usage |
| [`sprite-gen sound`](sound.md) | Generate normalized SFX and BGM audio assets with Opus and AAC encoding, SQLite raw request caching, and Web Audio loop metadata. |
| [pixel-draw.md](pixel-draw.md) | `sprite-gen pixel-draw` (experimental): Claude Opus draws 8–48 px pixel art as a pixel grid — the inputs, the safe area, the style (`--style`), a set of up to 64 frames drawn four at a time and one motion (`--motion`), the run folder and its report, gates G1–G8, the row repair and the one redraw, the pick between candidates, Message Batches and `--resume`, re-rendering an edited `grid.txt` |
| [logo.md](logo.md) | `sprite-gen logo`: a title logo or wordmark lettered by the model into a title screen or poster, only its lettering redrawn on a chroma key, cut out with its glow kept — the steps, files, report, text check and refusals, the key choice, the logo matte and its known limit |
@@ -132,6 +132,7 @@ grouping is derived from `sprite_gen/_modules.py`, the one taxonomy table.
| Doc | Owns |
|---|---|
+| [capabilities.md](capabilities.md) | `sprite-gen capabilities`: every verb and argument as one JSON line read off the CLI's parser, the providers each verb may call and be billed by, the provider address and login variables |
| [interpreter.md](interpreter.md) | Why the project venv is the only interpreter (no global `python3`, no NumPy fallback) |
| [rename-gate.md](rename-gate.md) | What must move together when a vocabulary word or key is renamed |
| [release.md](release.md) | How a vX.Y.Z tag becomes a release page, what the lane builds and the publisher attaches, and what stays manual |
diff --git a/docs/capabilities.md b/docs/capabilities.md
new file mode 100644
index 0000000..fcc2830
--- /dev/null
+++ b/docs/capabilities.md
@@ -0,0 +1,76 @@
+# `sprite-gen capabilities`: what the engine can do, for a machine to read
+
+> Owns: `sprite-gen capabilities`: the machine-readable list of every verb and argument, read off the CLI's parser, the providers each verb may call and be billed by, and the provider address and login variables · Index: [docs/README.md](README.md)
+
+```bash
+sprite-gen capabilities > capabilities.json
+```
+
+It prints one JSON line and takes no arguments. An agent driving the engine reads
+it once instead of running `--help` for every verb. It is about a quarter of the
+bytes of the top-level help and every verb's and old name's `--help` together (piped,
+at the default width).
+
+Every verb and every argument is read off the parser the CLI runs (`cli.COMMANDS`
+and the parser built from it). A verb or flag added to the CLI is listed with
+nothing else written, and an argument `--help` hides is not listed either. The one
+fact the parser does not hold is which providers a verb may call. That is the table
+`PROVIDER_CALLS` in `sprite_gen/workflow/capabilities.py`, the only place it is
+written. `tests/workflow/test_capabilities.py` checks the list against the parser and
+against every verb's printed options.
+
+## The document
+
+| Key | What it holds |
+|---|---|
+| `kind` | `sprite-gen-capabilities` |
+| `version` | the installed package's version (`unknown` from a bare checkout) |
+| `providers` | per provider (`openai`, `xai`, `anthropic`, `elevenlabs`): `base_url_env` (the variable that moves its calls), `base_url` (the documented address used when it is unset), `key_env` (its API key); docs/gen.md, [provider addresses](gen.md#provider-addresses) |
+| `logins_env` | `SPRITE_GEN_LOGINS`, where `off` turns subscription logins off ([subscription logins off](gen.md#subscription-logins-off)) |
+| `verbs` | every verb, in the order of `sprite-gen --help`'s table |
+
+The document says what the engine can do, not how this process is set up: a variable
+set in the environment does not change it.
+
+Each verb:
+
+| Key | What it holds |
+|---|---|
+| `domain` | its group in `sprite-gen --help` (`sprite_gen/_modules.py`) |
+| `description` | the line `sprite-gen --help` prints for it |
+| `providers` | the providers it may call over HTTP; absent when it calls none |
+| `paid` | whether running it may be billed by a provider: true for every verb that calls one, except `video-resume`, which asks for a clip an earlier run bought |
+| `old_names` | earlier names that still run it (`video-follow` for `video-sway`) |
+| `args` | its arguments, in the order `--help` lists them |
+| `exclusive` | groups of which at most one is given: `one_of` (argument names), `required` when one must be |
+| `commands` | its own sub-verbs (`rife install`), each with `description`, `args` and `exclusive` |
+
+Each argument holds only what applies:
+
+| Key | What it holds |
+|---|---|
+| `name` | its long spelling (`--out`), or its name for a positional one |
+| `aliases` | its other spellings (`-o`, `--no-loop`) |
+| `positional` | true for a positional argument |
+| `type` | `path`, `int`, `float`, `flag` (takes no value), or the name of the reading function the parser uses (`grid` for `COLSxROWS`, `region`, `box`, ...); absent for text |
+| `nargs` | how many values, as argparse says it (`*`, `?`) |
+| `repeat` | true when it may be given more than once |
+| `default` | its default; a flag's only when it is not off |
+| `required` | true when it must be given |
+| `choices` | the values it takes |
+
+Paths are written with `/`. A verb's argument meanings, units and examples are in
+its `--help` and its doc ([docs/README.md](README.md)).
+
+## The providers each verb may call
+
+| Verb | Providers | Paid |
+|---|---|---|
+| `gen`, `gen-set`, `logo` | `openai` (`--provider openai`), `xai` (`--provider grok`); codex runs on its own login | yes |
+| `pixel-draw` | `anthropic` | yes |
+| `sound` | `elevenlabs` | yes |
+| `curation` | `xai` (the reroll and in-between buttons on grok; codex on its own login) | yes |
+| `video`, `video-extend`, `video-edit`, `video-set` | `xai` | yes |
+| `video-resume` | `xai` | no |
+
+Every other verb calls no provider.
diff --git a/docs/gen.md b/docs/gen.md
index 0e735a9..ed997a5 100644
--- a/docs/gen.md
+++ b/docs/gen.md
@@ -1,6 +1,6 @@
# `sprite-gen gen` — provider-backed image generation (engine SSoT)
-> Owns: `sprite-gen gen` / `gen-set`: providers, default resolution and what a default codex that cannot run turns into, transparency strategy per provider, the billed knobs (`--quality`, `--resolution`), when a refused provider request is sent again (every direct provider call), row usage · Index: [docs/README.md](README.md)
+> Owns: `sprite-gen gen` / `gen-set`: providers, default resolution and what a default codex that cannot run turns into, transparency strategy per provider, the billed knobs (`--quality`, `--resolution`), where every direct provider call goes (`SPRITE_GEN_<PROVIDER>_BASE_URL`) and turning subscription logins off (`SPRITE_GEN_LOGINS`), when a refused provider request is sent again (every direct provider call), row usage · Index: [docs/README.md](README.md)
Generation is a first-class engine module (`sprite_gen/gen/`). One call = a prompt (+ optional reference images) → one **verified** PNG on
disk, with an optional transparent output whose strategy is decided per provider
@@ -143,6 +143,63 @@ by the local filename.
API contract: [OpenAI Images](https://developers.openai.com/api/images/).
+## Provider addresses
+
+sprite-gen calls four providers over HTTP itself, with no SDK. Each provider's calls go
+to one base address, and one environment variable replaces it. The variable is read
+when each request is made, not at import, so a process that sets or changes it after
+importing the engine is followed. Unset, empty or blank is the documented address, as
+before. Any other value must be an `http://` or `https://` address with no query or
+fragment, or the call stops naming the variable.
+
+| Provider | Variable | Default | Calls |
+|---|---|---|---|
+| OpenAI | `SPRITE_GEN_OPENAI_BASE_URL` | `https://api.openai.com/v1` | `gen --provider openai` images and edits, its vision checks (facing, the logo's text) |
+| xAI | `SPRITE_GEN_XAI_BASE_URL` | `https://api.x.ai/v1` | `gen --provider grok` images and edits, its vision checks, the video facing check, `video` / `video-extend` / `video-edit` requests and polls, `video-resume` polls, the clip's download |
+| Anthropic | `SPRITE_GEN_ANTHROPIC_BASE_URL` | `https://api.anthropic.com/v1` | `pixel-draw` messages, Message Batches, a batch's results file |
+| ElevenLabs | `SPRITE_GEN_ELEVENLABS_BASE_URL` | `https://api.elevenlabs.io/v1` | `sound` effects and music |
+
+The value is the API root with its version path, as the default is: a request for
+`/images/generations` goes to `<value>/images/generations` with the same method,
+headers and body it would have sent to the provider. The verbs that run others as
+child processes (`gen-set`, `video-set`, the curation view's reroll and in-between
+buttons) pass the environment on, so their children follow it too.
+
+A URL the provider hands back to be fetched points at the provider's own hosts: the
+finished clip xAI names, and the results file of an Anthropic Message Batch. With the
+provider's variable set it is fetched through the same base, as
+`GET <value>/sprite-gen/fetch?url=<the URL, percent-encoded>`, with the headers it
+would have carried: the clip first without a token and once more with the bearer
+token after a 401 or 403, the results file with the API key. A relay that forwards
+the provider's API forwards these too, so a sandbox with no network of its own needs
+nothing else. Without the variable the URL is fetched where it points, as before.
+
+The variables reach the engine's own calls. A subscription login (`codex`, `claude`)
+runs in its own binary on its own network and does not read them; with
+`SPRITE_GEN_LOGINS=off` none is used ([below](#subscription-logins-off)). The one
+place that builds these URLs is `sprite_gen/gen/address.py`, and no other module
+names a provider's address (`tests/gen/test_provider_address.py`).
+
+Whoever sets a variable sends that provider's key, or the grok login's token, to the
+address it names. Leave them unset unless a relay you run is there.
+
+## Subscription logins off
+
+`SPRITE_GEN_LOGINS=off` reads no subscription login, so every provider call runs on
+its API key, as in a container that holds a key and no login. Unset or empty is `on`,
+the order as before; any other value stops the call naming the variable.
+
+| Route | `on` (unset) | `off` |
+|---|---|---|
+| xAI (`gen --provider grok`, the video verbs, Grok vision) | the grok login file first (`~/.grok/auth.json`, `GROK_HOME`); `XAI_API_KEY` only without one | `XAI_API_KEY`; the login file and `GROK_HOME` are not looked at |
+| Anthropic (`pixel-draw`) | `claude auth status` first; `ANTHROPIC_API_KEY` only without a subscription login, and for `--batch` | `ANTHROPIC_API_KEY`; `claude` is not run |
+| codex (`gen --provider codex`, its vision checks) | `codex login status`, then `codex exec` | not usable: `codex login status` is not run; a default codex [asks, or runs what you chose](#when-codex-cannot-run--ask-or-what-you-chose), naming `SPRITE_GEN_LOGINS=off`; `--provider codex` stops |
+| OpenAI (`gen --provider openai`), ElevenLabs (`sound`) | the key; neither has a login | the same |
+
+Each key keeps its own rule either way: set but empty is refused naming it, and a
+missing key stops the call naming the key (and, with `off`, the variable). A login
+that is there is never traded for the key while logins are on.
+
## A refused request sent again
One rule for every direct provider call — the OpenAI and Grok image calls here, the
diff --git a/docs/pixel-draw.md b/docs/pixel-draw.md
index 3780aee..f8ab7c9 100644
--- a/docs/pixel-draw.md
+++ b/docs/pixel-draw.md
@@ -424,6 +424,11 @@ refused here.
said on stderr before the first request leaves.
3. Neither is a refusal naming both, before the run folder is made.
+`SPRITE_GEN_LOGINS=off` skips the first step: `claude` is not run and the key is the one route
+([subscription logins off](gen.md#subscription-logins-off)). `SPRITE_GEN_ANTHROPIC_BASE_URL` sends the
+messages, the batches and a batch's results file through another address
+([provider addresses](gen.md#provider-addresses)).
+
The child never sees `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN` — in print mode the binary uses a
key whenever one is present — nor the calling Claude Code session's own variables. A login that is
here but refuses a call, has expired or has reached its usage limit fails that call as it came; the
diff --git a/docs/sound.md b/docs/sound.md
index 77e6e8f..3fca011 100644
--- a/docs/sound.md
+++ b/docs/sound.md
@@ -15,7 +15,7 @@ sprite-gen sound --kind sfx|bgm --prompt TEXT (or --prompt-file PATH) --duration
- `--cache-dir`: Defaults to `$XDG_CACHE_HOME/sprite-gen/audio` or `~/.cache/sprite-gen/audio` (never inside `--out-dir`; local by default but can be copied; no cross-cache-directory or cross-machine duplicate-request guarantee).
- `--target-lufs`: Target integrated loudness within `-36..-9` LUFS.
- `--crossfade`: Overlap duration in seconds.
-- **Environment & PATH**: `ELEVENLABS_API_KEY` is required only for new paid requests (offline work needs none); ElevenLabs has no subscription login, so every new request is billed per call and says so on stderr before it leaves (`[gen] elevenlabs: running on ELEVENLABS_API_KEY — this is a per-call API charge …`, the line every metered route prints), and the receipt records `auth_source`. `ffmpeg` (with `libopus` and `aac` encoders) and `ffprobe` are required on `PATH` and checked before paid calls.
+- **Environment & PATH**: `ELEVENLABS_API_KEY` is required only for new paid requests (offline work needs none); ElevenLabs has no subscription login, so every new request is billed per call and says so on stderr before it leaves (`[gen] elevenlabs: running on ELEVENLABS_API_KEY — this is a per-call API charge …`, the line every metered route prints), and the receipt records `auth_source`. `SPRITE_GEN_ELEVENLABS_BASE_URL` sends new requests through another address ([provider addresses](gen.md#provider-addresses)). `ffmpeg` (with `libopus` and `aac` encoders) and `ffprobe` are required on `PATH` and checked before paid calls.
## Provider APIs and Cost Accounting
diff --git a/docs/video.md b/docs/video.md
index a65265c..15040c9 100644
--- a/docs/video.md
+++ b/docs/video.md
@@ -43,6 +43,10 @@ login wins**, even when `XAI_API_KEY` is set. `GROK_HOME` relocates `~/.grok`.
Only when no login file exists can the configured API key use console credits.
An expired, unreadable, corrupt or API-rejected login stops the request; it never
switches to API credit.
+`SPRITE_GEN_LOGINS=off` reads no login and runs on `XAI_API_KEY` alone.
+`SPRITE_GEN_XAI_BASE_URL` sends the requests, polls and the clip's download through
+another address ([provider addresses](gen.md#provider-addresses) and
+[subscription logins off](gen.md#subscription-logins-off) in docs/gen.md).
### The login token expires — and this tool does not refresh it