pixelkiln 0.89.5 → 0.89.6

package/docs/ENDPOINTS.md

@@ -894,6 +894,34 @@ Listed so the gaps are known rather than assumed away:
   `animate-character`, portraits, and outfit transfer are covered in full; see
   the September 2026 measurements below.
 
+## Skeleton-driven motion, measured
+
+October 2026, on a v3 character (64×64, `pixen_v3`), each billed exactly 3
+generations and finished in about two minutes:
+
+- **`POST /animate-with-skeleton-v3`** (pixelkiln's `animate-skeleton`):
+  8 hand-edited poses on a 64×64 sprite returned 8 frames at 64×64, matching
+  PixelLab's anchor (8 frames = 3). `description` and `action` are both
+  required. Sent with neither, the endpoint answers `422` with a field
+  error for each, and a failed request bills nothing. The completed job's
+  `last_response` carries `images` (base64, `width`, `height`), `flow_kind`,
+  and `billing_usage` beside the top-level `usage`.
+- **`POST /characters/animations`, `mode: "skeleton-v3"` with no
+  `template_animation_id`** (PixelLab's new custom motion): a one-sentence
+  `action_description` and `frame_count` 8 returned 8 frames at **96×96**
+  (the character's own canvas grows from 64) in one job for `south`, saved
+  onto the character as an animation (`animation_id`, `animation_group_id`),
+  and billed 3. The submit answers `{ background_job_ids, directions,
+  animation_group_id, status, enhanced_prompt, enhance_usage }`. The finished
+  job's `last_response` has `images`, `storage_urls.frames`,
+  `generation_model: "skeleton-v3_custom"`, `animation_description`, and
+  `billing_usage: {usd: 0, type: "generations", generations: 3}`, the same
+  nested field as the other character jobs, which is where `poll` looks when
+  the top-level amount is a dollar zero. PixelLab says the action is written
+  into one 3D motion that every direction is drawn from, so later directions
+  added with `animation_group_id` move the same way (humanoids). pixelkiln
+  does not send this mode yet.
+
 ## Characters, measured
 
 - Standard bases draw on a canvas 28px larger than `image_size` (64 → 92,

package/docs/REVISIONS.md

@@ -553,11 +553,15 @@ Cost uses PixelLab's own documented anchors (3 frames = 2 generations, 8 = 3,
 15 = 4 — barely moving with length, unlike `animate`/`animate-pixminimax`'s
 canvas-area formula) and interpolates between the nearest two for any
 in-between frame count, ceiling'd — the safe direction for `--budget` — since
-no in-between value is confirmed live. **Neither `animate-with-skeleton-v3`
-nor `estimate-skeleton` has been exercised against a live account**; request
-field names come from the live `animate_with_skeleton_v3` MCP tool schema
-(the same authoritative source already trusted for the character/object
-family), not an observed call.
+no in-between value is confirmed live. **Both have now run live once**
+(October 2026): `estimate-skeleton` on a 64×64 sprite, then an 8-frame
+`animate-skeleton` revision of it billed exactly 3 generations, matching the
+anchor, and returned 8 frames at the sprite's own 64×64 size. The endpoint
+**requires both `description` and `action`**: the asset's `prompt` is sent as
+`action` (a short motion label such as "wave"), and `revision.description`
+(what the character looks like) is sent as `description`. Without a
+`description` PixelLab answers `422` with `description: Field required`,
+and `plan` does not catch that yet.
 
 ComfyUI does not support this mode either, for the same structural reason as
 `animate`/`animate-pixminimax`.

package/package.json

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

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

@@ -297,8 +297,9 @@ and which tutorial(s) demonstrated real (not hypothetical) demand for it.
   is wrapped too, but deliberately kept outside the manifest pipeline — a
   standalone `pixelkiln estimate-skeleton` CLI command, not a
   `resolveSpecs`/`estimate()`-time call — so `animate-skeleton`'s submission
-  composes exactly one never-tested-live PixelLab endpoint, not two chained
-  together. **Correcting this catalog's own prior research**: this entry
+  composes exactly one PixelLab endpoint, not two chained together. Both
+  endpoints have since run live once (8 frames billed exactly 3), and the
+  run found that `description` is required: `plan` does not check for it yet. **Correcting this catalog's own prior research**: this entry
   used to also claim a distinct "animation to animation" endpoint existed,
   for transferring an existing walk cycle's motion onto a different
   character. Checked against the live `animate_with_skeleton_v3` MCP tool
@@ -516,6 +517,20 @@ missing:
   Aseprite. pixelkiln has no frame-set concatenation; `lastFrame` can pin a
   clip's ending to another clip's frame file, but the two sets stay separate.
 
+## Sentence-driven skeleton-v3 loops
+
+PixelLab's October 2026 character-creator update adds custom animation on the
+skeleton v3 model: a sentence becomes one 3D motion that every direction of
+the animation is drawn from, so a direction added later moves the same way.
+It is `POST /characters/animations` with `mode: "skeleton-v3"`, an
+`action_description`, and no `template_animation_id` (3 to 15 frames, humanoid
+v3 characters). **Measured once**: an 8-frame south loop billed exactly 3 and
+came back at 96×96 (docs/ENDPOINTS.md, "Skeleton-driven motion, measured").
+Still a gap: a character loop's `mode: "skeleton-v3"` needs a `template`,
+and the request never sends `action_description` for it. Closing it means a
+loop that names `skeleton-v3` and a `prompt` without a template, a
+`frames` count from 3 to 15, and adding a direction to an existing group.
+
 ## Map Workshop (scene composition)
 
 PixelLab's actual scene-building surface: lay out a tile floor, place