pixelkiln 0.86.3 → 0.87.0

package/PROVIDERS.md

@@ -134,7 +134,7 @@ background. That distinction matters more than raw canvas size.
 
 | Asset type | PixelLab | Retro Diffusion | ComfyUI | Scenario |
 |---|---|---|---|---|
-| Isolated house, building, mountain, or landmark | Start with `map`: arbitrary dimensions up to 400×400 and a measured one-generation cost. Live benchmark outputs had opaque backgrounds, so plan for cleanup. Use `1dir` only when references or candidate variety justify 20–40 generations and a square canvas. | Start with `rd_plus__topdown_asset`, `rd_plus__isometric_asset`, or `rd_tile__scene_object`, depending on perspective. `rd_tile__scene_object` is intended for 64–384px objects placed on tile maps. | Choose a checkpoint or LoRA trained for the intended perspective, then keep background removal or segmentation in the workflow. For the tested Pixel Art XL stack, target 48–128px native components even though the adapter accepts larger working canvases. | Raw model output is opaque and anti-aliased (the BFL smoke keep used 19,619 colors), but a chain of render at four times the size, Pixelate to the target grid, Birefnet, and `refine` took a 960 px render of an alpine lodge to a 240×208 native grid at high confidence with 63 colors, for 18 CU (a 1 CU render can be nearly as good). Details and the Pixelate grid caveat are in [Set up Scenario](./docs/SCENARIO.md#large-and-illustrative-art-render-big-pixelate-refine). One sample per subject. |
+| Isolated house, building, mountain, or landmark | Start with `map`: arbitrary dimensions up to 400×400 and a measured one-generation cost. Live benchmark outputs had opaque backgrounds, so plan for cleanup. Use `1dir` only when references or candidate variety justify 10–25 generations and a square canvas. | Start with `rd_plus__topdown_asset`, `rd_plus__isometric_asset`, or `rd_tile__scene_object`, depending on perspective. `rd_tile__scene_object` is intended for 64–384px objects placed on tile maps. | Choose a checkpoint or LoRA trained for the intended perspective, then keep background removal or segmentation in the workflow. For the tested Pixel Art XL stack, target 48–128px native components even though the adapter accepts larger working canvases. | Raw model output is opaque and anti-aliased (the BFL smoke keep used 19,619 colors), but a chain of render at four times the size, Pixelate to the target grid, Birefnet, and `refine` took a 960 px render of an alpine lodge to a 240×208 native grid at high confidence with 63 colors, for 18 CU (a 1 CU render can be nearly as good). Details and the Pixelate grid caveat are in [Set up Scenario](./docs/SCENARIO.md#large-and-illustrative-art-render-big-pixelate-refine). One sample per subject. |
 | Full scenic background | Use `pixflux` with `noBackground: false` when an exact palette matters, or `map` for a simple scene; both top out at 400×400. `imagePro` reaches 792 wide or 688 tall for a flat 40 generations. | `rd_plus__environment` targets one-point-perspective scenes; `rd_plus__topdown_map` targets 3/4 top-down maps. These styles support up to 384×384. | Use composition controls only to establish the scene. Recover and review native components, then compose them at 1× with one grid and palette. A large model canvas is not a large native pixel-art canvas. | GPT Image 2 at four times the target size, then Pixelate, turned a course-cover brief into a convincing pixel scene with 31 colors and legible title text. It has not been put through the shared benchmark. A large model canvas is not native pixel resolution: pixelate to the grid you need and check it with `refine`. |
 | Style consistency across a set | `1dir` accepts a style reference and returns size-dependent candidates, but it is more expensive and capped at the square-object range. | RD Pro accepts up to nine references and has stronger prompt following, but its common styles top out at 256×256 and cost $0.18 per image. Environment-specific RD Plus styles trade references for a larger 384px canvas. | LoRAs, reference adapters, ControlNet, and shared latent settings can live in the committed workflow. Reproducibility also depends on external model and custom-node versions. | Scenario's project models and LoRAs are the main reason to use it for a set. PixelKiln can pin the model ID and parameters, but its first live run covers only the public BFL profile. |
 | Very large final scene | Generate reusable objects, terrain, and background layers separately; assemble them deterministically and integer-upscale the result. | Use the same layered approach. The API has a 512px overall ceiling, but the useful environment and scene-object styles currently cap at 384px. | The graph can tile, upscale, or composite beyond hosted-provider limits, but memory and seam quality become workflow concerns. Prefer reusable layers unless the scene truly needs one render. | Scenario can request a larger raster from a compatible model, but the same rule applies: generate reusable layers at their useful native detail, compose at 1×, and integer-upscale only the final scene. |
@@ -206,20 +206,20 @@ conversion to dollars:
 |---|---:|
 | `map` | 1 generation |
 | `pixflux` | 1 generation |
-| `1dir` | 20–40 generations |
-| `imagePro` | 40 generations |
+| `1dir` | 10–25 generations |
+| `imagePro` | 10–25 generations by canvas (a flat 40 before October 2026) |
 | `imageProFlash` | 5–9 generations (provisional quote) |
-| `tiles` | 20–40 generations |
-| `terrain` | 20–40 generations (unmeasured) |
+| `tiles` | 10–25 generations |
+| `terrain` | 10–25 generations (unmeasured) |
 | `isometricTile` | 1 generation (measured once) |
-| `character` base | 1 (standard), 2–9 (v3), 20–40 (pro), 6–17 (pro-flash; rotations only from a reference) |
-| `character` state or portrait | 20–40 generations |
-| `character` animation | 1 (template), 2–4 (`skeleton-v3`, budgeted at 4), 1 at 64px from text, 20–40 (pro) |
+| `character` base | 1 (standard), 2–9 (v3), 10–25 (pro), 6–17 (pro-flash; rotations only from a reference) |
+| `character` state or portrait | 10–25 generations |
+| `character` animation | 1 (template), 2–4 (`skeleton-v3`, budgeted at 4), 1 at 64px from text, 10–25 (pro) |
 | `character` outfit | 20 generations (one 2-frame, 92×92 job) |
 | `objectPro` base | 6 at 64px (unmeasured) |
 | `uiAsset` | 20 generations (measured once, at 256×192) |
-| `uiElement` | 20–40 generations (unmeasured) |
-| `image-to-image` / `inpaint` revision | 20–40 generations; 5–9 with `engine: "pro-flash"` (provisional quote) |
+| `uiElement` | 10–25 generations (unmeasured) |
+| `image-to-image` / `inpaint` revision | 10–25 generations; 5–9 with `engine: "pro-flash"` (provisional quote) |
 | `reduce-colors` / `correct-pixelart` revision | 0.1 generations (measured at 32×32) |
 
 Retro Diffusion publishes USD formulas and fixed prices. Examples relevant to

package/README.md

@@ -55,7 +55,7 @@ provenance and no long-lived npm token.
 | Hand edits | Touch-ups in your own editor or a pinned in-browser Pixelorama, kept beside the generated art with the generation still the record; frame and tile sets member by member. |
 | Controlled inputs | Hashed revision lineage (image-to-image and inpaint; on PixelLab also palette reduction, pixel cleanup, animation, skeleton posing, interpolation, and animation edits), fail-closed parent approval, source-versus-candidate review, and content-addressed per-asset ComfyUI bindings. |
 | Characters | A base in 4 or 8 directions from a prompt or your own sprite (four PixelLab engines), poses, loops, portraits, and outfit transfers as dependent assets generated in waves, free mirrored directions (one `directions` list declares a loop and mirrors the rest), account adoption and salvage, and SpriteFrames export. |
-| PixelLab utilities | `unzoom` returns upscaled reference art to its native grid, `font` generates a `.ttf` and glyph atlas, `estimate-skeleton` starts a keypoints file for skeleton animation, and `skeleton-preview` draws its poses over the sprite for free. |
+| PixelLab utilities | `unzoom` returns upscaled reference art to its native grid, `pixelate` turns a photo or render into pixel art (Image to Pixel Art Pro Flash, 6 generations), `font` generates a `.ttf` and glyph atlas, `estimate-skeleton` starts a keypoints file for skeleton animation, and `skeleton-preview` draws its poses over the sprite for free. |
 | Existing-art onboarding | Manifest scaffolding, exact-hash account adoption, and prompt recovery. |
 | Recovery | Safe stale-output replacement, validated caches, durable references, resumable paid jobs, and per-asset generation history with free restores. |
 | Shared-account safety | Cross-project claim files or a registered workspace catalog, sibling-style exclusion, reviewed salvage, keep/discard tags, separate confirmed purge. |
@@ -255,9 +255,9 @@ Measured PixelLab economics vary by 40×:
 |---|---|---:|
 | Standalone arbitrary-size prop/icon | `map` (default) | 1 generation |
 | Exact closed palette | `pixflux` | 1 generation |
-| Candidate variety/reference anchoring/future animation | `1dir` | 20–40 generations |
-| Independent or connectable ground tiles | `tiles` | 20–40 generations |
-| A character in 4 or 8 directions, its poses, its loops | `character` | 1 per base, 20–40 per pose, 1 per template loop per direction; a `mirror` of a loop is free |
+| Candidate variety/reference anchoring/future animation | `1dir` | 10–25 generations |
+| Independent or connectable ground tiles | `tiles` | 10–25 generations |
+| A character in 4 or 8 directions, its poses, its loops | `character` | 1 per base, 10–25 per pose, 1 per template loop per direction; a `mirror` of a loop is free |
 
 Start with the required capability, not the most expensive endpoint. Forty `map`
 re-rolls cost the same as one 64×64 `1dir` call; conversely, `map` cannot replace a

package/dist/cli.js

@@ -162,6 +162,7 @@ var COMMANDS = [
   "estimate-skeleton",
   "skeleton-preview",
   "unzoom",
+  "pixelate",
   "font",
   "help",
   "--help",
@@ -499,8 +500,12 @@ Commands
             add/remove/list/status/claims. Offline.
   unzoom    PixelLab: shrink an upscaled image (--from) back to its native
             pixel grid before using it as a style or reference image.
+  pixelate  PixelLab: convert a photo, painting, or render (--from) into
+            pixel art with Image to Pixel Art Pro Flash; PixelLab picks the
+            output size. Optional --description steers the style. 6
+            generations; asks first.
   font      PixelLab: generate a pixel font (--description, --out); writes a
-            .ttf and a glyph atlas PNG. 25 generations; asks first.
+            .ttf and a glyph atlas PNG. 15 generations; asks first.
 
 Options
   --columns <n>       pack/export: sprites or tiles per row (default: near-square)
@@ -523,7 +528,8 @@ Options
   --model-root <dir>  recipe verify: also hash required local model files
   --generation <n|hash>  restore: the previous generation to bring back (1 = newest)
   --quantize <n>      unzoom: 0 auto palette (default), -1 keep all colors, 2-256 exact
-  --description <text>  font: the style to draw, e.g. "warm orange arcade font"
+  --description <text>  font: the style to draw, e.g. "warm orange arcade font";
+                      pixelate: an optional style steer, e.g. "light dithering"
   --weight <w>        font: Bold or Regular (default)
   --glyph-px <n>      font: native glyph size, 8, 16 (default), 32, or 64
   --prune             cache: remove invalid/unreferenced local cache data
@@ -583,6 +589,7 @@ Examples
   pixelkiln quality snapshot --inputs quality-inputs.json --out pixelkiln.quality.json
   pixelkiln quality check --from pixelkiln.quality.json
   pixelkiln unzoom --from refs/knight-512.png --out refs/knight.png
+  pixelkiln pixelate --from renders/lodge.png --out art/lodge.png
   pixelkiln font --description "warm orange arcade font" --weight Bold --out fonts/arcade
   pixelkiln workspace add ../other-game/pixelkiln.manifest.json
   pixelkiln workspace status --json
@@ -849,17 +856,24 @@ function candidateCount(size) {
 }
 function generationCost(width, height, generator = "map") {
   if (generator === "map" || generator === "pixflux") return 1;
-  if (generator === "imagePro") return 40;
+  if (generator === "imagePro") return proTierCost(width, height);
   const px = width * height;
-  if (px <= 1024) return 20;
-  if (px <= 2048) return 25;
-  return 40;
+  if (px <= 1024) return PRO_TIER_PRICES[0];
+  if (px <= 2048) return PRO_TIER_PRICES[1];
+  return PRO_TIER_PRICES[2];
+}
+var PRO_TIER_PRICES = [10, 15, 25];
+function proTierCost(width, height) {
+  const px = width * height;
+  if (px <= 65536) return PRO_TIER_PRICES[0];
+  if (px <= 102400) return PRO_TIER_PRICES[1];
+  return PRO_TIER_PRICES[2];
 }
 function tilesCost(tileSize, variations) {
   const px = tileSize * tileSize * Math.max(1, variations);
-  if (px <= 1024) return 20;
-  if (px <= 2048) return 25;
-  return 40;
+  if (px <= 1024) return PRO_TIER_PRICES[0];
+  if (px <= 2048) return PRO_TIER_PRICES[1];
+  return PRO_TIER_PRICES[2];
 }
 function isometricTileCost() {
   return 1;
@@ -1375,7 +1389,7 @@ var MEMBER_SET_REVISION_MODES = ["reduce-colors", "correct-pixelart", "edit-anim
 var StyleObjectSchema = z.object({
   /** Generation backend for this style. Omit to inherit the manifest default. */
   provider: z.string().min(1).optional(),
-  // `map` is the default because it is 20-40x cheaper and correct for any
+  // `map` is the default because it is 10-25x cheaper and correct for any
   // asset that is not going to be rotated or animated.
   generator: GeneratorSchema.default("map"),
   /** Square edge length. The active provider owns its exact limit. */
@@ -6820,7 +6834,8 @@ var PixelLabClient = class {
    * A full-body sprite in, a bust portrait out (or the reverse, unused
    * today). Job-based like a state or `1dir`, not the couple-generations
    * "conversion" the name suggests: the smallest `resultSize` (16px) billed
-   * 20 generations live (docs/ENDPOINTS.md, "Characters, measured").
+   * 20 generations live (docs/ENDPOINTS.md, "Characters, measured"), the
+   * Pro floor before PixelLab's October 2026 cut put it at 10.
    */
   async createPortraitCharacterPro(args) {
     const raw = await this.request("/portrait-character-pro", {
@@ -6859,7 +6874,8 @@ var PixelLabClient = class {
    * everything else here, but the completed job returns the result frames
    * inline as base64 (`last_response.quantized_images`), not as storage
    * URLs — the one PixelLab character tool that works this way. A live
-   * 2-frame, 92x92 job billed 20 generations (docs/ENDPOINTS.md).
+   * 2-frame, 92x92 job billed 20 generations (docs/ENDPOINTS.md), before
+   * PixelLab's October 2026 Pro cut halved that floor to 10.
    */
   async transferOutfitV2(args) {
     const image = (img) => ({
@@ -6909,7 +6925,9 @@ var PixelLabClient = class {
    * far higher than this tiering assumes; 352x352 (123904px²), 384x384
    * (147456px²), and 512x512 (262144px², the tiering ceiling) all billed
    * 40. Both breakpoints are now tightly bracketed: 20->25 in
-   * (65536px², 82944px²], 25->40 in (102400px², 123904px²].
+   * (65536px², 82944px²], 25->40 in (102400px², 123904px²]. Those prices
+   * predate PixelLab's October 2026 Pro cut to 10/15/25; `proTierCost`
+   * keeps the breakpoints with the new prices.
    * `editImagesV2` below returns the same fields under `images`, plural
    * and array-wrapped, not `image` — do not assume the two endpoints share
    * one response shape. See docs/ENDPOINTS.md and docs/REVISIONS.md for
@@ -6962,8 +6980,9 @@ var PixelLabClient = class {
     );
   }
   /**
-   * PixelLab's Pro image tier, `/generate-image-v2`: a flat 40 generations
-   * (docs/ENDPOINTS.md, "Single-image generators, measured") for real style
+   * PixelLab's Pro image tier, `/generate-image-v2`: 10 to 25 generations by
+   * canvas since PixelLab's October 2026 Pro cut, a flat 40 before
+   * (docs/ENDPOINTS.md, "Single-image generators, measured"), for real style
    * transfer and non-square canvases up to 792x688, where `pixflux` is
    * limited to 400x400 and no style reference. Like a revision, this hands
    * back a plain background job with no resource of its own; unlike a
@@ -7049,6 +7068,24 @@ var PixelLabClient = class {
       "inpaint-image-pro-flash"
     );
   }
+  /**
+   * `/image-to-pixelart-pro-flash`: a photo, painting, or render in, pixel
+   * art out, with no size to pass: PixelLab detects the native pixel scale
+   * and picks the output size (a 256x256 render came back 108x109, on a
+   * transparent background). A flat 6 generations, billed exactly that live
+   * in October 2026. Sources over 2048px on the longer side are scaled down
+   * upstream. The finished job carries the image at `last_response.images[0]`.
+   */
+  async imageToPixelartProFlash(args) {
+    const body = { image: args.image };
+    if (args.description) body.description = args.description;
+    if (args.seed != null) body.seed = args.seed;
+    return validateResponse(
+      ProFlashImageSubmitSchema,
+      await this.request("/image-to-pixelart-pro-flash", { method: "POST", body: JSON.stringify(body) }),
+      "image-to-pixelart-pro-flash"
+    );
+  }
   /**
    * `/generate-ui-v2` ("Generate UI (Pro)"): one UI element (a button, a
    * health bar, an inventory slot, a dialogue box) from a description,
@@ -7443,7 +7480,7 @@ function characterCost(spec) {
   }
   if (character.kind === "state" || character.kind === "portrait") return generationCost(spec.width, spec.height, "1dir");
   if (character.kind === "outfit") {
-    return 20;
+    return PRO_TIER_PRICES[0];
   }
   if (character.mode === "standard") return 1;
   if (character.mode === "v3") {
@@ -7695,7 +7732,7 @@ var PixelLabProvider = class _PixelLabProvider {
     if (spec.revision) {
       const width = spec.revision.sourceWidth ?? spec.width;
       const height = spec.revision.sourceHeight ?? spec.height;
-      return { unit: "generations", amount: generationCost(width, height, "1dir"), candidates: 1 };
+      return { unit: "generations", amount: proTierCost(width, height), candidates: 1 };
     }
     if (spec.generator === "tiles" || spec.generator === "terrain" || spec.generator === "isometricTile") {
       return { unit: "generations", amount: spec.cost, candidates: spec.candidates };
@@ -20667,7 +20704,7 @@ async function unzoomFile(client2, input, opts = {}) {
 }
 var FONT_WEIGHTS = ["Bold", "Regular"];
 var FONT_GLYPH_SIZES = [8, 16, 32, 64];
-var FONT_COST_GENERATIONS = 25;
+var FONT_COST_GENERATIONS = 15;
 function fontOutputPaths(out) {
   const base = path43.resolve(out.replace(/\.(ttf|png)$/i, ""));
   return { ttf: `${base}.ttf`, atlas: `${base}.png` };
@@ -20716,6 +20753,61 @@ async function generateFont(client2, opts) {
     await sleep3(interval);
   }
 }
+var PIXELATE_COST_GENERATIONS = 6;
+var PIXELATE_MAX_SIDE = 2048;
+function defaultPixelateOut(input) {
+  const ext = path43.extname(input);
+  return `${ext ? input.slice(0, -ext.length) : input}.pixel.png`;
+}
+async function pixelateFile(client2, input, opts = {}) {
+  const out = path43.resolve(opts.out ?? defaultPixelateOut(input));
+  if (path43.resolve(input) === out) throw new Error("pixelate will not overwrite its own input; pass a different --out");
+  if (existsSync33(out) && !opts.force) throw new Error(`${out} already exists; pass --force to replace it`);
+  const bytes = await readFile29(input);
+  const metadata = imageMetadata(bytes);
+  if (!metadata) throw new Error(`${input} is not a readable PNG or JPEG`);
+  const { width, height, format } = metadata;
+  const sleep3 = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const interval = opts.intervalMs ?? 5e3;
+  const timeout = opts.timeoutMs ?? 10 * 6e4;
+  const submitted = await client2.imageToPixelartProFlash({
+    image: { base64: bytes.toString("base64"), format },
+    description: opts.description,
+    seed: opts.seed
+  });
+  const jobId = submitted.background_job_id;
+  const started = Date.now();
+  for (; ; ) {
+    const job = await client2.getBackgroundJob(jobId);
+    opts.onProgress?.(job.status);
+    if (job.status === "failed") throw new Error(`PixelLab pixelate job ${jobId} failed upstream`);
+    if (job.status === "completed") {
+      const images = job.last_response?.images;
+      const first = Array.isArray(images) ? images[0] : void 0;
+      if (!first || typeof first.base64 !== "string" || !first.base64) {
+        throw new Error(`PixelLab pixelate job ${jobId} completed without an image at last_response.images[0]`);
+      }
+      const png = Buffer.from(first.base64, "base64");
+      const size = imageMetadata(png);
+      await mkdir13(path43.dirname(out), { recursive: true });
+      await writeFile18(out, png);
+      return {
+        jobId,
+        out,
+        original: { width, height },
+        pixelated: { width: size?.width ?? Number(first.width), height: size?.height ?? Number(first.height) },
+        imageId: submitted.image_id,
+        usage: job.usage ?? null
+      };
+    }
+    if (Date.now() - started > timeout) {
+      throw new Error(
+        `PixelLab pixelate job ${jobId} is still ${job.status} after ${Math.round(timeout / 1e3)} s; it keeps running upstream, but this command has stopped waiting`
+      );
+    }
+    await sleep3(interval);
+  }
+}
 
 // src/cli/commands/pixellab-utils.ts
 function loadKeys(args) {
@@ -20783,6 +20875,39 @@ async function runFont(args) {
   log(`  wrote ${res.ttf}`);
   log(`  wrote ${res.atlas}`);
 }
+async function runPixelate(args) {
+  if (!args.from) throw new UsageError("pixelate needs --from <image>: the photo, painting, or render to convert");
+  const out = args.out ?? defaultPixelateOut(args.from);
+  log(`  pixelate ${args.from} \u2192 ${out}${args.description ? ` ("${args.description}")` : ""}; PixelLab picks the output size`);
+  log(`  cost: ${PIXELATE_COST_GENERATIONS} generations (Image to Pixel Art Pro Flash, flat)`);
+  if (args.budget !== void 0 && args.budget < PIXELATE_COST_GENERATIONS) {
+    throw new Error(`--budget ${args.budget} is below this conversion's ${PIXELATE_COST_GENERATIONS}-generation cost`);
+  }
+  if (args.dryRun) {
+    log("  dry run: nothing sent");
+    return;
+  }
+  if (!await confirm(`  Spend ${PIXELATE_COST_GENERATIONS} generations on this conversion?`, args.yes)) return;
+  loadKeys(args);
+  let last = "";
+  const res = await pixelateFile(clientFromEnv(), args.from, {
+    out,
+    description: args.description,
+    force: args.force,
+    onProgress: (status) => {
+      if (status !== last) log(`  ${status}\u2026`);
+      last = status;
+    }
+  });
+  if (args.json) {
+    log(JSON.stringify({ version: 1, ...res }, null, 2));
+    return;
+  }
+  const scaled = Math.max(res.original.width, res.original.height) > PIXELATE_MAX_SIDE ? " (scaled down upstream first)" : "";
+  log(
+    `  ${res.original.width}x${res.original.height}${scaled} \u2192 ${res.pixelated.width}x${res.pixelated.height}; wrote ${res.out}`
+  );
+}
 
 // src/cli/commands/quality.ts
 import path46 from "path";
@@ -22215,6 +22340,7 @@ var RUNNERS = {
   "estimate-skeleton": runEstimateSkeleton,
   "skeleton-preview": runSkeletonPreview,
   unzoom: runUnzoom,
+  pixelate: runPixelate,
   font: runFont
 };
 async function main(argv = process.argv.slice(2)) {