pixelkiln 0.89.5 → 0.90.0

package/docs/CHARACTERS.md

@@ -222,6 +222,45 @@ single direction before a batch.
 "mira.walk": { "animation": { "of": "mira", "template": "walk", "mode": "skeleton-v3", "directions": ["south", "west", "north"] } }
 ```
 
+### Loops from a sentence
+
+`mode: "skeleton-v3"` with **no `template`** animates the asset's `prompt`
+instead: PixelLab writes the sentence into one 3D motion and draws the
+character from it, with no template to pick. `frames` takes PixelLab's own
+3 to 15 for this combination (odd counts included, default 8); a template
+`skeleton-v3` loop still takes none.
+
+```jsonc
+"mira.swing": {
+  "prompt": "swinging a sword in a wide arc",
+  "animation": { "of": "mira", "mode": "skeleton-v3", "frames": 8, "directions": ["south", "west"] }
+}
+```
+
+- **A v3 base is required.** The sentence is written onto the character's
+  stored 3D skeleton, which a `standard` base lacks, so `plan` and `validate`
+  refuse the pairing and name the engine. `pro` and `pro-flash` bases are
+  not refused but are unverified. An `objectPro` has no skeleton at all.
+- **The prompt is the sentence**, sent as written as `action_description`
+  (a loop's prompt never takes the style's prefix or suffix, same as a v3
+  loop). It is required; `startFrame`, `endFrame`, `enhancePrompt`,
+  `subject`, and the template style hints are refused.
+- **The canvas can grow.** The measured 64px loop came back at 96×96. The
+  frames are saved as PixelLab returns them; a mirror flips them locally like
+  any other loop.
+- **Cost**: the plan budgets 4 per direction, the same ceiling as a template
+  `skeleton-v3` loop. Measured live on a v3 character: 8 frames at 64px billed
+  exactly 3 generations for one direction, about 15 seconds before the jobs
+  start. `billed` in the lock records the real amount.
+- **Directions do not share one motion yet.** PixelLab draws every direction
+  of a request from one 3D motion, and `animation_group_id` appends a
+  direction to an existing animation so it moves the same way. pixelkiln
+  makes one request per direction asset (including each direction of
+  `directions`), so each direction's motion is written from the sentence
+  separately and may differ a little. Appending to a recorded group is not
+  wired up; the lock keeps each direction's `animationGroupId` for when it is.
+  Verified live is a single south direction only.
+
 ### Pose frames and other loop controls
 
 A v3 loop can start and end where you say. `startFrame` is a
@@ -489,11 +528,12 @@ reference image change alone also makes it stale.
   style (engine, size, directions, body, view, folder) or an existing one,
   the base with an optional sprite of your own (uploaded into `refs/`, so
   only the rotations are billed), any number of loops (each a template
-  posed by `skeleton-v3` by default, or a plain template, v3, or pro loop,
+  posed by `skeleton-v3` by default, a `skeleton-v3` loop described in words
+  with a 3 to 15 frame count, or a plain template, v3, or pro loop,
   in the directions you tick, mirrors added free), and a portrait. A
   `standard` base has no 3D skeleton for `skeleton-v3` to pose, so its loops
-  start on `template` and the skeleton-v3 choice is greyed out; the new-loop
-  form on an existing base does the same. The
+  start on `template` and both skeleton-v3 choices are greyed out; the
+  new-loop form on an existing base does the same. The
   sheet prices the draft live, the way `plan` would. Pro Flash bases are
   priced by PixelLab's own quote (`/pro-flash/cost`, a free call) when the
   project has a key; those rows are marked live, and the offline estimate

package/docs/ENDPOINTS.md

@@ -894,6 +894,38 @@ 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
+  sends this mode for a character loop with `mode: "skeleton-v3"`, a prompt,
+  and no template (docs/CHARACTERS.md, "Loops from a sentence"), one request
+  per direction asset and without `animation_group_id`. Verified live with
+  one south direction on a v3 character; a standard-engine character is
+  refused (`has no stored 3D skeleton`).
+
 ## Characters, measured
 
 - Standard bases draw on a canvas 28px larger than `image_size` (64 → 92,

package/docs/MANIFEST.md

@@ -56,7 +56,7 @@ not merely a label edit.
 
 | Field | Type/default | Meaning |
 |---|---|---|
-| `prompt` | string, required unless `mirror`, `portrait`, `outfit`, or a template loop (`animation.template`) | The subject wording wrapped by the selected style's prompt prefix and suffix. A template loop is described by its template; a v3 or pro loop still needs the motion in words. |
+| `prompt` | string, required unless `mirror`, `portrait`, `outfit`, or a template loop (`animation.template`) | The subject wording wrapped by the selected style's prompt prefix and suffix. A template loop is described by its template; a v3, pro, or sentence (`skeleton-v3` with no template) loop still needs the motion in words. |
 | `width` / `height` | integer 16–8192 | Per-asset dimensions for generators that accept rectangular output. Provider limits may be lower. |
 | `size` | integer 16–8192 | Per-asset square size where the generator uses one dimension. |
 | `file` | string | Output path below the style's `outDir`; defaults to `<category>/<assetId>.png`. |
@@ -66,7 +66,7 @@ not merely a label edit.
 | `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`, `remove-background`, `normal-map`, 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). |
+| `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). `mode: "skeleton-v3"` with no `template` animates the asset's `prompt` as a sentence (3–15 `frames`, default 8; a v3 base); see [Loops from a sentence](./CHARACTERS.md#loops-from-a-sentence). |
 | `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). |
 | `outfit` | object | `character` styles: an existing loop's frames re-clothed from an outfit image, `{ "of": "<loop asset>", "reference": "<image>" }`, with optional `additionalInstructions`. See [Outfit transfer](./CHARACTERS.md#outfit-transfer). |
 | `mirror` | string | Another asset of the same style flipped left to right, made locally at no cost. See [Mirrors](./CHARACTERS.md#mirrors). |

package/docs/REVISIONS.md

@@ -492,7 +492,8 @@ a supplied 18-joint skeleton per frame instead of a text motion description:
         "mode": "animate-skeleton",
         "from": "hero-idle",
         "keypointsFile": "poses/hero-swing.json",
-        "direction": "south"
+        "direction": "south",
+        "description": "a knight in steel armour holding a sword"
       }
     }
   }
@@ -522,8 +523,8 @@ over the source image, locally and for free.
 `direction` is **required** for this mode (unlike `animate-pixminimax`,
 where it is optional). `frames`/`fps`/`lastFrame`/`enhancePrompt` are all
 rejected — the frame count comes from the keypoints file itself
-(`frames.length`), never a manifest number. `description` (optional: what the
-character *looks like* — colours, clothing, held items) is a new field
+(`frames.length`), never a manifest number. `description` (**required**: what
+the character *looks like* — colours, clothing, held items) is a new field
 distinct from the asset's own `prompt`, which this mode sends as the motion's
 short label (PixelLab's `action`) — the same `prompt`-as-motion convention
 `animate`/`animate-pixminimax` already use, just under this endpoint's own
@@ -553,11 +554,17 @@ 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`, so
+`plan` refuses an `animate-skeleton` revision without a non-empty
+`revision.description` (or an empty `prompt`) and the gallery's form asks for
+one.
 
 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.90.0",
   "description": "Manifest-driven pixel-art generation, review, recovery, and packaging with deterministic provenance.",
   "type": "module",
   "sideEffects": false,

package/schema/manifest.schema.json

@@ -1307,7 +1307,7 @@
                   },
                   "frames": {
                     "type": "integer",
-                    "minimum": 4,
+                    "minimum": 3,
                     "maximum": 16
                   },
                   "fps": {

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

@@ -31,6 +31,13 @@ and which tutorial(s) demonstrated real (not hypothetical) demand for it.
 
 ## Already closed since this catalog's research began
 
+- **Sentence-driven skeleton-v3 loops** — a character loop with
+  `mode: "skeleton-v3"`, no `template`, and a `prompt` animates the sentence
+  on `/characters/animations` (`action_description`, 3 to 15 `frames`). Billed
+  exactly 3 generations for 8 frames at 64px, frames back at 96×96; the plan
+  budgets 4. See `docs/CHARACTERS.md`, "Loops from a sentence". Shared motion
+  across directions is not wired up (one request per direction asset).
+
 - **Skeleton-v3 template loops** — `/characters/animations`'
   `mode: "skeleton-v3"` poses a template with the skeleton video model
   (2 to 4 generations and 3 to 5 minutes per direction, beta, Tier 1 and
@@ -297,8 +304,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, which `plan` now enforces. **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 +524,17 @@ 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, shared motion across directions
+
+PixelLab's sentence loops (`mode: "skeleton-v3"`, no template) are supported;
+see "Already closed". What is still open: every direction of one request is
+drawn from one 3D motion, and `animation_group_id` appends a direction to an
+existing animation so it moves the same way. pixelkiln makes one request per
+direction asset and never sends the group id, so each direction's motion is
+written separately. Closing it means linking the direction assets of a
+`directions` loop to one group (a batch like `1dir`'s, or the recorded
+`animationGroupId` of a sibling) and passing it on the later requests.
+
 ## Map Workshop (scene composition)
 
 PixelLab's actual scene-building surface: lay out a tile floor, place

package/skills/pixelkiln/references/pixellab.md

@@ -394,6 +394,14 @@ stored 3D skeleton: a `v3` base has one (measured, 3 generations); a
 refuses the loop at `plan`/`validate`, pointing at `mode: "template"`. `pro`
 and `pro-flash` bases are not refused but are unverified.
 
+`"mode": "skeleton-v3"` with **no** `template` animates the asset's `prompt`
+as a sentence (`frames` 3 to 15, default 8; a v3 base): PixelLab writes it
+into one 3D motion. Measured: 8 frames at 64px billed exactly 3 generations
+and came back at 96×96, so the canvas can grow. The plan still budgets 4. One
+request goes out per direction asset, so directions are not drawn from one
+shared motion yet (docs/CHARACTERS.md, "Loops from a sentence"). The
+`prompt` is required and gets no style prefix or suffix.
+
 A named `template` loop (`walk`, `breathing-idle`, and similar) is trained
 mostly on characters with empty hands, and reliably struggles once a
 character holds an item — a weapon, a tool, anything gripped. For a