pixelkiln 0.83.0 → 0.85.0

package/docs/MANIFEST.md

@@ -64,7 +64,7 @@ not merely a label edit.
 | `source` | string | Manifest-relative committed art used instead of generation. For a set of PNG outputs (a `frames` animation, a `tiles` set) a path that is not a file is the stem of a hand edit laid beside the generated members (`<stem>-<role>.png` each); the set still generates. Mutually exclusive with `revision`. |
 | `sourceByStyle` | object | Per-style `source`, keyed by style id; wins over `source` for that style. Written by `pixelkiln edit` for a hand edit of an asset that is in several styles. |
 | `remoteId` | string | The provider's own id for art that already exists on the account, so `adopt` maps it without matching bytes: an object id, a character id, or `<character id>#<animation group id>`. Not part of the spec's identity. |
-| `revision` | object | Controlled dependency on another asset: `image-to-image`, `inpaint`, or `outpaint`; on PixelLab also `reduce-colors`, `correct-pixelart`, the animate modes (`animate`, `animate-pixminimax`, `animate-skeleton`), `interpolate`, and `edit-animation`. `engine: "pro-flash"` selects PixelLab's Pro Flash tier for `image-to-image`/`inpaint`. See [controlled revisions](REVISIONS.md). |
+| `revision` | object | Controlled dependency on another asset: `image-to-image`, `inpaint`, or `outpaint`; on PixelLab also `reduce-colors`, `correct-pixelart`, `remove-background`, the animate modes (`animate`, `animate-pixminimax`, `animate-skeleton`), `interpolate`, and `edit-animation`. `engine: "pro-flash"` selects PixelLab's Pro Flash tier for `image-to-image`/`inpaint`. See [controlled revisions](REVISIONS.md). |
 | `state` | object | `character` styles: a pose or outfit of another character asset. See [Characters](./CHARACTERS.md). |
 | `animation` | object | `character` styles: a loop of another character asset in one direction. `directions` (a list, instead of `direction`) declares the loop for several directions at once and fills the unnamed flips with mirrors; see [One loop, several directions](./CHARACTERS.md#one-loop-several-directions). |
 | `portrait` | object | `character` styles: a bust of a base or state's south sprite, `{ "of": "<asset>", "size": 64 }`; `size` is 16, 32, 48, 64 (default), 128, or 160. See [Portraits](./CHARACTERS.md#portraits). |
@@ -471,22 +471,26 @@ their own page: [Characters](./CHARACTERS.md) and
 
 | Revision field | Type | Meaning |
 |---|---|---|
-| `mode` | enum, required | `image-to-image`, `inpaint`, `outpaint`, `reduce-colors`, `correct-pixelart`, `animate`, `animate-pixminimax`, `animate-skeleton`, `interpolate`, or `edit-animation`. The selected provider must opt into the mode. |
+| `mode` | enum, required | `image-to-image`, `inpaint`, `outpaint`, `reduce-colors`, `correct-pixelart`, `remove-background`, `animate`, `animate-pixminimax`, `animate-skeleton`, `interpolate`, or `edit-animation`. The selected provider must opt into the mode. |
 | `from` | asset id, required | Parent asset in the same style. Self-references, unknown ids, and cycles are rejected. A parent written as a set (a character's directions, an animation's frames) is read as every member: `reduce-colors`, `correct-pixelart`, and `edit-animation` take the whole set in one call; the other modes refuse it. See [Revising a whole set at once](./REVISIONS.md#revising-a-whole-set-at-once). |
 | `mask` | string | Manifest-relative PNG required for `inpaint`; rejected for the other modes. Its dimensions must match an available source. |
-| `strength` | number 0–1 | Workflow edit/denoise strength (`image-to-image`, `correct-pixelart`); rejected for `reduce-colors`, `animate`, `animate-pixminimax`, `interpolate`, and `edit-animation`. Interpretation is provider- and model-specific. |
+| `strength` | number 0–1 | Workflow edit/denoise strength (`image-to-image`, `correct-pixelart`); rejected for `reduce-colors`, `remove-background`, `animate`, `animate-pixminimax`, `interpolate`, and `edit-animation`. Interpretation is provider- and model-specific. |
 | `numColors` | integer 2–256 | `reduce-colors` only. Target palette size; mutually exclusive with `paletteImage`. |
+| `removalTask` | `simple` or `complex` | `remove-background` only. `simple` (PixelLab's default) is faster for flat backgrounds; `complex` handles detailed edges. |
 | `paletteImage` | string | `reduce-colors` only. Manifest-relative image whose colors become the palette; unlike `mask`, no size relationship to the source is required. |
 | `dithering` | enum | `reduce-colors` only. `none` (default), `2x2`, `4x4`, or `8x8`. |
 | `ditheringStrength` | number 0–10 | `reduce-colors` only. Ignored when `dithering` is `none`. |
-| `frames` | integer 4–40, even | `animate`/`animate-pixminimax` only. `animate` caps at 16; `animate-pixminimax` allows up to 40. Rejected for `animate-skeleton` (frame count comes from `keypointsFile` instead), `interpolate`, and `edit-animation`. |
+| `frames` | integer 4–40, even | `animate`/`animate-pixminimax` only. `animate` caps at 16 (even); `animate-pixminimax` allows up to 40 in multiples of 4. Rejected for `animate-skeleton` (frame count comes from `keypointsFile` instead), `interpolate`, and `edit-animation`. |
 | `fps` | integer 1–60 | `animate`/`animate-pixminimax`/`interpolate`/`edit-animation` only. Playback rate recorded with the frames; the provider does not store one. Defaults to the parent's own rate when it is a loop, else 8. |
 | `lastFrame` | string | `animate`/`animate-pixminimax`: manifest-relative image pinning where the motion ends, turning an open-ended animation into an interpolation. `interpolate`: required, the ending keyframe (the parent is the start); it must match the parent's size. |
-| `direction` | enum | `animate-pixminimax`/`animate-skeleton`. Optional (alongside `enhancePrompt`) for the former; **required** for the latter. |
+| `direction` | enum | `animate-pixminimax`/`animate-skeleton`. Optional for the former (a caption field PixelLab otherwise reads off the image); **required** for the latter. |
 | `enhancePrompt` | boolean | `animate`/`animate-pixminimax` only. Lets the provider expand the prompt into a fuller motion description first, for an extra documented +0.05-generation surcharge. |
+| `driftThreshold` | number ≥ 0 | `animate`/`animate-pixminimax` only. Colour de-flicker sensitivity: frames drifting from the first beyond it are corrected toward it; `0` corrects every frame. Omit for PixelLab's default. |
+| `subjectDescription` | string ≤ 300 | `animate-pixminimax` only. What the parent shows, one noun phrase; PixelLab reads it off the image when omitted and can decline some images. |
+| `initialPose` | string ≤ 300 | `animate-pixminimax` only. The pose the parent is in; read off the image when omitted. |
 | `keypointsFile` | string, required for `animate-skeleton` | Manifest-relative JSON file (`src/skeleton.ts`'s `SkeletonSetSchema`): the pose the source is already in, plus 3–15 per-frame poses. See [Skeleton-driven animation](./REVISIONS.md#skeleton-driven-animation). |
 | `skeletonTemplate` | string | `animate-skeleton` only. Body a joint's missing `depth` is taken from: `mannequin` (default), `bear`, `cat`, `dog`, `horse`, or `lion`. |
-| `description` | string | `animate-skeleton` only. What the subject *looks like* (colours, clothing, held items) — the asset's own `prompt` is sent as the motion's short label instead. |
+| `description` | string | `animate-skeleton`: what the subject *looks like* (colours, clothing, held items) — the asset's own `prompt` is sent as the motion's short label instead. `remove-background`: a hint naming the foreground. Rejected on other modes. |
 | `engine` | enum | `image-to-image`/`inpaint` only. `pro-flash` draws the edit with PixelLab's Pro Flash edit or inpaint endpoint instead of the default Pro one: 5–9 generations instead of 20–40, 32 to 256px per side in multiples of 4, no `strength`. Omit for the default. |
 
 The parent may use committed `source`, downloaded generated output, or a

package/docs/REVISIONS.md

@@ -5,14 +5,16 @@ The parent may be committed art, a downloaded generation, or an approved
 quality output. PixelKiln hashes the exact parent and mask bytes, blocks stale
 dependencies before submission, and records the lineage in the lockfile.
 
-The manifest and pipeline are provider-neutral. ComfyUI and PixelLab implement
+The manifest and pipeline are provider-neutral. ComfyUI, PixelLab and Scenario implement
 it; PixelLab covers `image-to-image`, `inpaint`, `reduce-colors`,
-`correct-pixelart`, `animate`, `animate-pixminimax`, `animate-skeleton`,
-`interpolate`, and `edit-animation`, not `outpaint` (its API has no
+`correct-pixelart`, `remove-background`, `animate`, `animate-pixminimax`,
+`animate-skeleton`, `interpolate`, and `edit-animation`, not `outpaint` (its API has no
 canvas-expansion endpoint). ComfyUI covers every mode generically except the
 five frame-set modes (`animate`, `animate-pixminimax`, `animate-skeleton`,
 `interpolate`, `edit-animation`), which need an ordered frame set its
-revision path cannot produce. Retro Diffusion and Scenario reject revision
+revision path cannot produce. Scenario covers `image-to-image` only, by uploading the parent as a reference
+image to its editing models ([Set up Scenario](./SCENARIO.md#reference-images-and-edits)).
+Retro Diffusion rejects revision
 work during offline resolution instead of silently starting a fresh
 text-to-image job.
 
@@ -59,17 +61,28 @@ input to the provider workflow, not a cross-model quality guarantee.
 **From the gallery** (`pixelkiln gallery --edit`): open a completed or
 committed asset's drawer and use "+ New revision" under "Revisions from this
 asset" to create a child of it. On a PixelLab sprite the mode picker offers
-`image-to-image`, `animate`, `animate-pixminimax`, `reduce-colors`, and
-`correct-pixelart`; on a PixelLab frame set (or a character's directions) it
-offers `edit-animation`, `reduce-colors`, and `correct-pixelart`, which take
-the whole set. Other providers get `image-to-image`. The form asks only for
-the new asset id, the instruction or motion, and the mode's own options
-(strength, frames, fps, colours, dithering). The button only
+`image-to-image`, `inpaint`, `animate`, `animate-pixminimax`, `interpolate`,
+`reduce-colors`, `correct-pixelart`, and `remove-background`; on a PixelLab
+frame set (or a character's directions) it offers `edit-animation`,
+`reduce-colors`, and `correct-pixelart`, which take the whole set. ComfyUI
+sprites get `image-to-image` and `inpaint`; other providers get
+`image-to-image`. The form asks only for the new asset id, the instruction or
+motion, and the mode's own options (strength, frames, fps, colours,
+dithering, removal task).
+
+`inpaint` opens a mask editor over the sprite: paint the area to repaint with
+a brush sized in sprite pixels, erase, invert, undo. Saving writes the mask
+as a black-and-white PNG of the sprite's size at the path you give (default
+`masks/<asset-id>.png`) and declares the revision in one step; if the manifest
+refuses the asset the mask file is removed again. The sprite must be 32 to 512
+pixels per side. `interpolate` offers the project's other single-image
+records of the same style and size as the ending keyframe (the parent is the
+start), for sprites 16 to 128 pixels per side; it appears only when there is
+one. The button only
 appears once the parent has usable pixels (committed `source`, a current
 downloaded generation, or a current approved quality output); the plan still
 reports `blocked` with the real reason if that turns out wrong once the asset
-exists. `inpaint` needs a mask upload and `interpolate` an ending keyframe, and
-the gallery offers neither, so those still have to be added by hand.
+exists. `outpaint` is not offered; no provider implements it.
 
 "+ Skeleton animation", beside it on a single PixelLab sprite, creates an
 `animate-skeleton` child instead. The poses come from a keypoints file already
@@ -165,6 +178,31 @@ photographs and 3-D renders, not for reprocessing" pixel art):
 `strength` (0–1, PixelLab's own default 0.1) is how far the model may move
 from the source; start low and only raise it for real repair.
 
+### Remove a background
+
+`remove-background` calls PixelLab's `/remove-background` and returns the
+same sprite on a transparent background. It is synchronous like the other
+cleanup modes, takes one image of at most 400 by 400 pixels, and refuses a
+set parent. Our measurements found it the one utility that leaves a locked
+palette intact (it also drops stray fringe pixels; see
+[ENDPOINTS](./ENDPOINTS.md#post-processing-utilities-measured)); cost is 1
+generation.
+
+```jsonc
+{
+  "revision": {
+    "mode": "remove-background",
+    "from": "hero",
+    "removalTask": "complex",
+    "description": "a knight holding a sword"
+  }
+}
+```
+
+`removalTask` is `simple` (PixelLab's default: faster, for flat backgrounds)
+or `complex` (slower, for detailed edges). `description` is an optional hint
+naming the foreground. Both are rejected on other modes, as is `strength`.
+
 ### Revising a whole set at once
 
 Both modes also take a parent that is a **set** rather than one image: a
@@ -233,8 +271,18 @@ pixels the same way `image-to-image` does:
 `animate` calls `/animate-with-text-v3` (4–16 frames, even). `animate-pixminimax`
 calls `/animate-pixminimax` — PixelLab's MiniMax-powered engine, beta and
 gated to a tier 1 subscription or higher — for 4 to 40 frames and two extra
-knobs: `direction` (the sprite's facing, used only alongside `enhancePrompt`
-to aim motion the right way on screen) and the same `enhancePrompt`. Both
+knobs: `direction` (the sprite's facing, which also aims `enhancePrompt`'s
+motion the right way on screen) and the same `enhancePrompt`. It also takes
+two caption fields, `subjectDescription` (what the parent shows, one noun
+phrase) and `initialPose` (the pose it is in). PixelLab reads any caption
+field you leave out off the image with an AI model, and can decline some
+images, failing the job until you send them yourself; sending all of them,
+with `enhancePrompt` off, rewrites nothing. The style's `view` is sent as the
+view caption. `frames` must be a multiple of 4 for this mode, which is
+checked at plan time. Both modes take `driftThreshold`, PixelLab's colour
+de-flicker sensitivity: frames whose foreground drifts from the first frame
+beyond it are corrected toward it, `0` corrects every frame, and omitting it
+keeps PixelLab's default. Both
 reject a declared `strength` (there is no denoise knob here, same as
 `image-to-image`) and both send the asset's own `prompt` as the motion
 description — `action` for `animate`, `description` for `animate-pixminimax`.
@@ -369,7 +417,10 @@ inline pixels. It must match the shape `src/skeleton.ts`'s `SkeletonSetSchema`
 validates: `{"firstFrameKeypoints": [...18 joints], "frames": [[...18
 joints], ...3 to 15 of them]}`, each joint `{"label": "RIGHT KNEE", "x": 0.52,
 "y": 0.71, "z_index": 9, "depth": 4}` (`depth` optional — PixelLab fills it
-from `skeletonTemplate`, default `mannequin`, when omitted). `label` is one
+from `skeletonTemplate`, default `mannequin`, when omitted). The request also
+carries the style's `view` (`side`, `low top-down`, or `high top-down`) so the
+motion is posed for the sprite's own camera; PixelLab assumes `low top-down`
+otherwise. `label` is one
 of PixelLab's 18 joints (`NOSE`, `NECK`, `RIGHT`/`LEFT` `SHOULDER`, `ELBOW`,
 `ARM` for the wrist, `HIP`, `KNEE`, `LEG` for the ankle, `EYE`, `EAR`), each
 exactly once per pose; a misspelled or repeated joint fails when the manifest

package/docs/SCENARIO.md

@@ -31,8 +31,12 @@ override the production API root. Ordinary projects should leave it unset.
 PixelKiln calls `POST /generate/custom/{modelId}`. Scenario model inputs vary;
 inspect the model's current parameter reference before adding optional inputs.
 The initial PixelKiln contract sends `prompt`, `width`, `height`, `numOutputs`,
-and an optional `seed`. It accepts dimensions from 128–2048px in multiples of
-16 and one to four PNG outputs.
+and an optional `seed`. It accepts whole-number dimensions from 16 to 4096px and one to four PNG
+outputs. Each model has its own tighter bounds (FLUX takes 128 to 2048 in
+steps of 16, Retro Diffusion Plus 16 to 384); the free dry run that precedes
+every paid request reports them, for example "Input width must be at least
+672", before anything is spent. A model may also return a different canvas than
+the one requested, so check real dimensions.
 
 The public `model_bfl-flux-2-dev` profile documents that input shape. A custom
 LoRA used with that base can be supplied as `parameters.modelId` when the
@@ -78,9 +82,146 @@ keeps job and asset lookup scoped to the intended Scenario project.
 replace PixelKiln-owned `prompt`, dimensions, seed, output count, project, or
 budget fields.
 
-Style reference uploads are not implemented. A `styleImages` entry fails
-during free manifest resolution rather than uploading the same image on every
-run. Train or reuse a Scenario model for the first integration.
+## Reference images and edits
+
+Most Scenario image models take reference images, which serve both as style
+guidance and as the image to edit. PixelKiln uploads each local image to
+Scenario once (`POST /assets`, free), keeps the returned asset id by content
+hash in a temporary cache so a rerun does not upload it again, and sends the ids
+as the model's `referenceImages` input. Two things use this:
+
+- A style's `styleImages` are sent as references with every asset in the style.
+- An `image-to-image` revision sends its parent first, then any style images.
+  The prompt is the edit instruction, as in
+  [controlled revisions](./REVISIONS.md). Masked `inpaint` and the
+  PixelLab animation and cleanup modes are not available, and `strength` is
+  refused because Scenario has no common one; use the model's own `parameters`.
+
+```jsonc
+{
+  "styles": {
+    "edit": {
+      "generator": "map",
+      "size": 512,
+      "outDir": "assets/generated",
+      "providerOptions": {
+        "scenario": { "modelId": "model_bfl-flux-2-klein-9b", "maxComputeUnits": 1 }
+      }
+    }
+  },
+  "assets": {
+    "keep": { "prompt": "a stone mountain keep", "source": "art/keep.png" },
+    "keep-snow": {
+      "prompt": "the same keep in winter: snow on the roofs, pixel art",
+      "revision": { "mode": "image-to-image", "from": "keep" }
+    }
+  }
+}
+```
+
+The adapter does not know each model's input names, so a model whose image
+input is not called `referenceImages` needs `referenceParameter` (for example
+`"image"`), and `referenceArray: false` if it takes one image rather than a
+list. `parameters` may not also set that input. A model must accept images at
+all: the free dry run, which now includes the references, rejects one that
+does not before anything is spent. A reference can add to the quote (GPT Image 2
+priced one text-only 512×512 request at 11 CU and the same request with a
+reference at 12).
+
+On October 5, 2026 a one-image `image-to-image` revision of the bake-off's GPT
+Image 2 keep through `model_bfl-flux-2-klein-9b` quoted and billed 1 CU and
+returned the same keep with snow on its roofs and battlements, banners and
+layout intact. The committed
+[Scenario edit smoke](../benchmarks/provider-scenario-edit/README.md) has the
+manifest, lockfile, and both images. That is one sample on one model.
+
+### Tool models as image-to-image
+
+Scenario's single-image tools (pixel snapper, pixelate, background removal,
+upscalers) are models like any other, so they run through the same
+`image-to-image` revision with no extra mode: point the style at the tool's
+model, name its input `image`, and put its settings in `parameters`. The
+adapter's other fields (`prompt`, `width`, `height`, `numOutputs`, `seed`) are
+accepted and ignored by these tools, and the free dry run prices the exact
+request. Free dry runs on October 5, 2026 quoted these on a `cu-basic` account:
+
+| Model | CU | Inputs besides `image` |
+|---|---:|---|
+| `model_birefnet-background-removal` | 2 | none |
+| `model_recraft-crisp-upscale` | 2 | none |
+| `model_bria-remove-background`, `model_photoroom-background-removal` | 3 | none |
+| `model_pixel-snapper` | 5 | `colors` 8 to 256 (default 16) |
+| `model_sc-pixelate` | 5 | `pixelGridSize` 1 to 512, `removeNoise`, `colorPalette`, `colorPaletteSize` |
+| `model_upscale-v3`, `model_topaz-image-upscale` | 10 | none |
+
+```jsonc
+{
+  "styles": {
+    "snap": {
+      "generator": "map",
+      "size": 512,
+      "outDir": "assets/snapped",
+      "providerOptions": {
+        "scenario": {
+          "modelId": "model_pixel-snapper",
+          "maxComputeUnits": 5,
+          "referenceParameter": "image",
+          "referenceArray": false,
+          "parameters": { "colors": 16 }
+        }
+      }
+    }
+  },
+  "assets": {
+    "keep-snapped": {
+      "prompt": "snap to the pixel grid",
+      "revision": { "mode": "image-to-image", "from": "keep" }
+    }
+  }
+}
+```
+
+Birefnet and Pixel Snapper were then run once each through the adapter (7 CU,
+quoted and billed identically; see the
+[tool-model smoke](../benchmarks/provider-scenario-tools/README.md)). Pixel
+Snapper returned an 83×83, exactly-16-colour native-grid version of a 512×512
+image, a different size than the manifest's canvas, and Birefnet's cutout kept
+its subject at alpha 254 rather than 255. The other tools were only quoted. They overlap PixelKiln's own offline work: `pixelkiln refine` snaps
+the grid and palette for free, and PixelLab's `remove-background` revision costs
+one generation. Reach for these when the art is already on Scenario.
+
+### Retro Diffusion on Scenario
+
+Scenario hosts three Retro Diffusion models, and they are the most pixel-art-specific
+models in its catalog: `model_retrodiffusion-plus` (18 styles from `default` and
+`retro` to `isometric_asset`, `topdown_asset`, `character_turnaround`, and
+`ui_element`), `model_retrodiffusion-tile` (`tileset`, `tileset_advanced`,
+`single_tile`, `tile_variation`, `tile_object`, `scene_object`), and
+`model_retrodiffusion-animation` (`four_angle_walking`, `walking_and_idle`,
+`small_sprites`, `vfx`). On a `cu-basic` account every dry run answered
+`ModelAccessRestrictedError` with `requiredPlan: cu-pro-q3-25`, so none of this
+has been run, and no price is known until the plan is upgraded.
+
+Judging from Scenario's parameter reference (nothing here was exercised), what
+the adapter already supports and what it does not:
+
+| Need | Status |
+|---|---|
+| `style`, `removeBg`, `tileX`, `tileY`, `strength`, `bypassPromptExpansion` | Pass-through `parameters`. |
+| 16 to 384 px canvas | Accepted now; the model's bound comes from the free dry run. |
+| `image` (image-to-image) | Supported through an `image-to-image` revision with `referenceParameter: "image"` and `referenceArray: false`. |
+| `inputPalette` (a palette image) | Not supported: the adapter has one reference input. |
+| More than 4 outputs (Plus and Tile allow 10) | Not supported: `numOutputs` stops at 4. |
+| Animation as a PNG spritesheet (`returnSpritesheet: true`) | Lands as one still image; there is no frame-set output for Scenario, so a person would slice it. The default GIF output is refused. |
+| Tilesets | Land as one still; PixelKiln's tile roles and exports do not apply. |
+
+PixelKiln also has a direct [Retro Diffusion](./RETRO_DIFFUSION.md) provider
+with live-tested single stills. Choosing between them is a billing and plan
+question (Retro Diffusion's USD credits against Scenario's compute units), not a
+feature one, until the Scenario route is measured. The first live check after
+upgrading should be one `model_retrodiffusion-plus` still at 64×64 with the
+default style: quote, billed amount, dimensions, and whether it comes back as
+PNG.
 
 ## Plan before spending
 
@@ -114,6 +255,12 @@ quote stops the run before paid work. Scenario's `costDetails` already sum to
 `creativeUnitsCost`; PixelKiln records both without double-counting. A separate
 IP-detection charge is additive when Scenario reports one.
 
+A 429 on a generation request means the account's concurrent-job limit
+refused it: nothing was accepted or billed, and the adapter retries for about
+80 seconds. Past that, rerun `gen`; the assets that landed are kept. A finished
+job whose asset is not a PNG (some models return JPEG) is billed, so that asset
+is marked failed rather than polled again.
+
 The command budget is still a hard ceiling over the whole selected run. The
 manifest ceiling protects each request from a changed live quote.
 
@@ -123,6 +270,24 @@ closed palette, and require named approval before pack or mount. This offline
 policy does not change the Scenario request or CU quote. See
 [Manifest quality profiles](./MANIFEST.md#quality-profiles).
 
+### Models and what they cost
+
+A free survey on October 5, 2026 quoted every non-deprecated text-to-image
+model with a prompt-only 512×512 dry run on a `cu-basic` account. 37 were
+usable and 19 were refused with `ModelAccessRestrictedError` (the Retro
+Diffusion Plus, Tile, and Animation models need the `cu-pro-q3-25` plan).
+Quotes ran from 1 CU (FLUX.2 Klein 9b, FLUX.1 Schnell, P-Image) through 2 to 6
+for the Krea 2, Recraft V4.1 Flash, Meta Muse, Ernie, Z-Image, and Qwen Image
+models, 11 to 12 for GPT Image 2 and Gemini 3.1 Flash, to 16 for the FLUX.2 Dev
+this page was first validated on. The
+[model bake-off](../benchmarks/provider-scenario-bakeoff/README.md) ran ten of
+them once: price did not predict fit, several models ignore the requested
+canvas size, and one returned a JPEG, which the adapter refuses.
+
+Scenario's catalog also lists pixel-art LoRAs, background-removal and upscale
+models, and a `pixel-snapper` cleanup tool. LoRA models answer a different
+endpoint than `/generate/custom/{modelId}`, which this adapter does not call.
+
 ### Current live validation
 
 On September 5, 2026, PixelKiln authenticated against the read-only model
@@ -184,9 +349,11 @@ for every style:
 | `numOutputs` | One to four PNG candidates; defaults to one. |
 | `projectId` | Optional Scenario ownership/routing project. |
 | `parameters` | Additional model-specific JSON inputs. PixelKiln-owned request fields cannot be overridden. |
+| `referenceParameter` | The model input that takes images, default `referenceImages`. |
+| `referenceArray` | `false` when that input takes one image rather than a list. |
 
-The current adapter supports `map`, dimensions from 128–2048px in multiples of
-16, optional seed, and no style-image uploads. Every paid request is preceded
+The current adapter supports `map`, whole-number dimensions from 16 to 4096px,
+optional seed, style images and `image-to-image` revisions as reference uploads. Every paid request is preceded
 by an identical `dryRun=true` request. See [Set up Scenario](SCENARIO.md) for
 credentials, cost semantics, recovery, and the paid live-test boundary.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixelkiln",
-  "version": "0.83.0",
+  "version": "0.85.0",
   "description": "Manifest-driven pixel-art generation, review, recovery, and packaging with deterministic provenance.",
   "type": "module",
   "sideEffects": false,

package/schema/manifest.schema.json

@@ -1010,6 +1010,7 @@
                       "outpaint",
                       "reduce-colors",
                       "correct-pixelart",
+                      "remove-background",
                       "animate",
                       "animate-pixminimax",
                       "animate-skeleton",
@@ -1067,6 +1068,20 @@
                     "type": "string",
                     "minLength": 1
                   },
+                  "driftThreshold": {
+                    "type": "number",
+                    "minimum": 0
+                  },
+                  "subjectDescription": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 300
+                  },
+                  "initialPose": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 300
+                  },
                   "direction": {
                     "type": "string",
                     "enum": [
@@ -1091,6 +1106,13 @@
                     "type": "string",
                     "minLength": 1
                   },
+                  "removalTask": {
+                    "type": "string",
+                    "enum": [
+                      "simple",
+                      "complex"
+                    ]
+                  },
                   "description": {
                     "type": "string",
                     "minLength": 1

package/skills/pixelkiln/references/pixellab-roadmap.md

@@ -275,6 +275,16 @@ and which tutorial(s) demonstrated real (not hypothetical) demand for it.
   automates. Neither `animate-with-skeleton-v3` nor `estimate-skeleton` has
   been exercised against a live account; request field names come from the
   MCP tool schema, not an observed call.
+- **Remove background** (`/remove-background`, a transparent cutout of one
+  image up to 400x400, `simple` or `complex` task, optional foreground text
+  hint) — closed by the `revision` asset shape's `remove-background` mode.
+  Cost is the measured 1 generation from docs/ENDPOINTS.md's utilities
+  table; the `complex` task and the text hint have not been exercised live.
+- **The legacy `/animate-with-skeleton`** (no `-v3`) is deliberately not
+  wrapped: its live schema takes exactly 3 skeleton frames per call (other
+  counts are a 422), plus view, direction, init-image and inpainting
+  parameters, while v3 takes 3 to 15 frames. `animate-skeleton` covers the
+  same job.
 
 - **Fonts** (`/generate-font-pro`, an 80-glyph atlas plus a `.ttf` from a
   style description) — no tutorial demonstrated it in depth, so demand is

package/skills/pixelkiln/references/pixellab.md

@@ -408,7 +408,9 @@ contained a generated signature-like glyph.
 An asset that declares `revision` against a PixelLab style calls `inpaint`
 (masked), `image-to-image` (whole-image, no mask), `reduce-colors`
 (palette quantize, `/reduce-colors`), `correct-pixelart` (edge/noise
-cleanup, `/correct-pixelart`), `animate` (`/animate-with-text-v3`),
+cleanup, `/correct-pixelart`), `remove-background` (transparent cutout,
+`/remove-background`, one image up to 400x400, 1 generation measured),
+`animate` (`/animate-with-text-v3`),
 `animate-pixminimax` (`/animate-pixminimax`, beta, tier 1 subscription or
 higher), `animate-skeleton` (`/animate-with-skeleton-v3`, also beta/tier
 1+ — poses the source frame-by-frame from a supplied 18-joint skeleton per
@@ -416,8 +418,9 @@ frame, via a committed `keypointsFile` rather than a text motion
 description), `interpolate` (`/interpolation-v2`, in-betweens from the parent
 to a required `lastFrame` keyframe), or `edit-animation` (`/edit-animation-v2`,
 one edit across a whole frame set); `outpaint` is refused, since PixelLab has
-no canvas-expansion endpoint. `reduce-colors`/`correct-pixelart` send no
-prompt to PixelLab at all — they are mechanical, not described — and complete
+no canvas-expansion endpoint. `reduce-colors`/`correct-pixelart`/
+`remove-background` send no prompt (`remove-background` sends only its
+optional `description` as a foreground hint) to PixelLab at all — they are mechanical, not described — and complete
 synchronously with no background job, unlike every other PixelLab call this
 adapter makes. `animate`/`animate-pixminimax`/`animate-skeleton` DO send the
 asset's own prompt, as the motion description (`animate-skeleton` calls it

package/skills/pixelkiln/references/revisions.md

@@ -17,6 +17,10 @@ Read this reference when an asset declares `revision`.
   5 generations up to 96px, 6 up to 208px, 9 beyond (provisional quotes),
   against 20–40. The parent must be 32–256px per side in multiples of 4, and
   `strength` is refused. Other modes reject `engine`.
+- `remove-background` (PixelLab, one image up to 400x400, `removalTask`
+  `simple` or `complex`, optional `description` hint) cuts the background out
+  to transparency and leaves a locked palette intact; 1 generation measured.
+  It refuses a set parent.
 - `reduce-colors` and `correct-pixelart` send no prompt to the provider — the
   asset's `prompt` stays a manifest-only label. `numColors`/`paletteImage`
   are mutually exclusive; a `paletteImage` has no size relationship to the
@@ -83,17 +87,19 @@ Read this reference when an asset declares `revision`.
   silhouette or layout drift before post-processing.
 - `pixelkiln gallery --edit` can create a revision directly from a parent's
   drawer ("+ New revision" under "Revisions from this asset"), once the parent
-  has usable pixels: on a PixelLab sprite `image-to-image`, `animate`,
-  `animate-pixminimax`, `reduce-colors`, or `correct-pixelart`; on a PixelLab
-  frame set (or a character's directions) `edit-animation`, `reduce-colors`,
-  or `correct-pixelart`; on other providers `image-to-image`. On a single
-  PixelLab sprite, "+ Skeleton animation" creates an `animate-skeleton`
+  has usable pixels: on a PixelLab sprite `image-to-image`, `inpaint` (a
+  paint-over-the-sprite mask editor that writes the mask PNG into the project),
+  `animate`, `animate-pixminimax`, `interpolate` (another same-size sprite as
+  the ending keyframe), `reduce-colors`, `correct-pixelart`, or
+  `remove-background`; on a PixelLab frame set (or a character's directions)
+  `edit-animation`, `reduce-colors`, or `correct-pixelart`; on ComfyUI
+  `image-to-image` or `inpaint`; on other providers `image-to-image`. On a
+  single PixelLab sprite, "+ Skeleton animation" creates an `animate-skeleton`
   revision: poses from a project file, pasted JSON, or "Estimate poses" (one
   confirmed, un-budgeted PixelLab call), edited in a drag-to-edit pose editor
   over the sprite, written into the project on save. "Edit poses" on an
   existing `animate-skeleton` record reopens the editor on its keypoints file.
-  It does not offer `inpaint` (needs a mask upload), `outpaint`, or
-  `interpolate` (needs an ending keyframe), so add those by hand.
+  Only `outpaint` is not offered; no provider implements it.
 - Before an outside image becomes a `styleImages` or `reference` path,
   suggest `pixelkiln unzoom --from <file>`: upscaled pixel art (every art
   pixel a block of screen pixels) degrades every reference-taking PixelLab

package/skills/pixelkiln/references/scenario.md

@@ -20,11 +20,15 @@ schemas remain unverified. Require a one-asset smoke before widening a batch.
   existing Scenario asset and must not trigger another generation.
 - Treat `scenario://` job and asset references as the recovery contract.
   Temporary signed Scenario URLs must not remain in a settled lockfile.
-- Verify the chosen model returns PNG. The MVP rejects other media formats,
-  style-image uploads, animation, and tiles.
+- Verify the chosen model returns PNG. The adapter rejects other media
+  formats, animation, and tiles.
+- Style images and `image-to-image` revisions are uploaded once (free) and sent
+  as the model's `referenceImages` input; set `referenceParameter` and
+  `referenceArray` for a model that names it differently. Other revision modes
+  and `strength` are refused.
 
-Scenario model parameters vary. The MVP supplies prompt, 128–2048px dimensions
-in multiples of 16, one to four outputs, and optional seed. Put only documented
+Scenario model parameters vary. The MVP supplies prompt, 16–4096px dimensions
+(each model has tighter bounds, reported by the free dry run), one to four outputs, and optional seed. Put only documented
 model inputs in `parameters`; PixelKiln rejects attempts to override its prompt,
 dimensions, seed, output count, project routing, or CU ceiling.