pixellab-pip
Use for PixelLab/Pip setup, auth, MCP/API routing, asset generation, editing, animation, talking portraits, lip sync, skeleton/template/preset animations, multi-shot/looping cinematics, docs/troubleshooting, bark completion sounds, and explicit PixelLab cost/budget/credit questio
Install
npx skills add https://github.com/Shilo/pixellab-pip/tree/main/skills/pixellab-pip
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install shilo-pixellab-pip@llmmart
git clone https://github.com/Shilo/pixellab-pip.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole shilo/pixellab-pip collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
PixelLab Pip
Classify the request, choose the supported PixelLab surface, then act. Answer questions directly when the request is a question.
Workflow
- Classify intent; values combine, such as
animate + cost_sensitive:question | setup | update | uninstall | bark | auto | panel | create asset | edit/transform | animate | pixelart_workbench | prompt_enhancement | cost_sensitive | integrate/code | check balance/status | troubleshoot docs/API | website/editor assistance | game_builder | aseprite_integration | blueprint/recipe. A standalone command word after an explicit skill invocation, such as/pixellab-pip setupor@pixellab-pip bark off, is that intent: for setup readreferences/setup.md, for update readreferences/update.md, for uninstall readreferences/uninstall.md, for bark readreferences/bark.md, for auto readreferences/auto.md, for panel readreferences/panel.md. - Classify the target:
general_image | skill_icon | item_icon | background | character | portrait_character | font | object | effect_vfx | ui | whole_map | map_image | map_object | top_down_tileset | sidescroller_tileset | multi_shape_tileset | path_tiles | building_kit | isometric_tile | tile_variants | animation | existing_image. Fitted visual additions to an existing character image, such as hair, facial features, wearables, accessories, or held gear, areexisting_imagepaperdoll edits, not standaloneobjectrequests, unless the user explicitly wants a separate unattached prop. - Choose the surface with Surface Rules, then the route with the Intent Router. When the user explicitly asks for Aseprite handling, read
references/aseprite-cli.md; PixelLab MCP/REST generates, documented Aseprite CLI/Lua handles local workspace, import/export, packaging, and launch only. - Use MCP only if PixelLab MCP tools are visible as callable tools, bare or prefixed such as
mcp__pixellab__create_character(match by suffix). If the user explicitly asked for MCP, do not silently fall back; report that MCP is unavailable and offer setup or an approved REST v2 fallback. Otherwise, when MCP is unavailable, use the matching documented REST v2 endpoint. If both are unavailable or fail, explain why before any non-PixelLab fallback. - Before repeated paid prompt-only retries, inspect the chosen tool or endpoint schema for generation controls such as guidance, adherence/strength, reference images, palette images, or style options, and use the ones that target the failure mode. Before the first paid call to any endpoint that consumes a supplied input image, inspect its schema and embed the source image in the correct field — never send such a request without its input image. Refresh official docs only when a needed tool, endpoint, field, auth, SDK, pricing, or model/mode fact is missing or unclear (see Current Docs Refresh).
- Before already-routed generation, check only the selected project root for
pixellab-pip-style.json; when present readreferences/project-style.mdfor the effective style, temporary overrides and legacy restrictions. No profile means ordinary one-off work without forced setup. For consistency-sensitive work, summarize the user's identity, style, palette, view, and reference anchors. Ask up to three blocking questions before a credit-spending call. - Prepare natural-language parameters per Text Preparation. For non-English or mixed-language requests, read
references/localization.md. - For animation, preserve the user's requested frame count; otherwise use the endpoint or template default. Read
references/animation.mdfor generated-versus-returned counts and input-echo verification before quoting or validating a count. Exception: preset/template character animations take noframe_count; pick a matching template id such aswalking-8-frames(catalog inreferences/preset-skeleton-template-animation.md) or use custom animation per that reference. Preserve PixelLab's returned frame order; no ping-pong, reversed, duplicated, or trimmed outputs unless the user asks for that playback style. - If the user says cheap, budget, low-cost, fewer credits, or similar, read
references/cost-routing.mdbefore choosing a paid route, and ask before each extra paid attempt unless the run's approved retry allowance inreferences/auto.md→ Bounded plans and resuming covers it. - Before live generation, confirm the PixelLab bearer token is configured (see Auth And Execution).
seed: omit by default; PixelLab randomizes it. Send it only when the selected schema exposes it, in three cases — the user gave a seed (send verbatim), a candidate batch whose blueprint sets distinct seeds (send them as written), or two or more calls share near-identical wording and should attempt to hold the same composition (seed-lock, not a guarantee): generate one random positive integer (0means random, so never 0) and send that same value on every call in the set. MCPcreate_characterhas no seed; use a reference image, or Pro-onlystyle_character_id, for look consistency and do not promise reproducibility. Do not ask for a seed.- Act or answer. Once the job's live generation(s) have returned image(s) — after the last one in a chain — do three follow-ups before the final report, even if the user did not ask: the completion sound (
references/bark.md), the manifest (references/usage-reporting.md), and the*.blueprint.json(references/blueprint.md). Then send one final report. Ask a short clarification only for known collisions. Before that report, send only a blocker, a question you need answered, the approval or auto-on card, or a needed resume clarification — never progress, status, findings, or intentions; those belong in the final report. For a pending job, keep polling its getter in-turn until its status iscompletedorfailed— a still-running job is never a reason to end the turn (references/job-lifecycle.md). If the turn is being cut off before it finishes, continue with a bounded background wait instead of stopping. Hand the job back to the user only when you can do neither — no way to keep polling and no way to background a wait — then report the job or asset ID and the getter that resumes the check, and say credits were spent. Exception — chunk reveal: when an approved run produces several separately-completing image jobs (a multi-shot cinematic chain, an all-directions animation, an approved multi-asset batch), post each job's saved output — path and inline preview link — as that job completes, and fold the last job into the final report rather than revealing it twice. This covers distinct sequential jobs only, not the multiple images a single job returns at once (8-direction character, animation frames, rotations, tileset tiles, review candidates), which go straight to the final report.
Asset Integrity
- Every pixel of requested art must originate from PixelLab or the user. Local tools may read, download, assemble, package, import/export, preview, verify, mask, pad, crop, resize, and format-convert those pixels. Locally authored generation controls such as masks, palette swatches/
color_image, reference guides, and shape templates are allowed as inputs; report them as inputs. Do not draw, repaint, or synthesize requested content locally unless the user explicitly approves a labeled non-PixelLab fallback. - Reviewable static candidates: when a static image-style MCP tool or REST endpoint returns multiple alternatives, read
references/reviewable-candidates.mdbefore selecting, saving, or continuing from one. - Do not bake a colored, checkerboard, white, black, green-screen, or matte background into transparent frames, final GIFs, spritesheets, previews, or report images unless the user explicitly asks for it. A checkerboard is allowed only as a clearly labeled inspection aid kept separate from final deliverables.
- Post-process PixelLab output into a claimed final asset only with explicit approval. Local crop/split/format work that preserves original pixels is allowed when reported honestly; resizing, reassembling, compositing, or repairing failed outputs locally may be called final only after approval. Exception: when a request used
no_background: truebut the output kept a background, readreferences/background-removal.mdand attempt safe removal when verification shows the background is removable without changing the art. - Save downloaded generations, derived previews, manifests, and packages in a named per-generation subfolder under the
pixellab-pip-generations/folder at the user's project/workspace root — not loose in its root, and never resolved against a background or detached process's working directory, which may default to the home folder — unless the user names another location. A returned base64 image may be raw RGBA rather than PNG; confirm a saved image decodes to a valid PNG, and when a response exposes more than one image field, save the PNG-encoded one. Produce only the requested output formats or the route's minimal standard artifacts. When a job returns multiple separate images, always compile one standard preview alongside the individual files: a spritesheet for a collection of distinct sprites, or a looping preview GIF when the images are frames of a single animation (readreferences/local-asset-assembly.mdfor spritesheet grids and GIF settings). No APNG or extra preview/viewer formats unless asked. - After a generation returns image(s), write a
<name>.blueprint.jsonbeside the outputs perreferences/blueprint.md— canonical portable_pixellabconnection metadata, the exact route bodies, structuredTASKsteps for material work performed outside PixelLab calls, and a_comment_promptholding the user's original prompt as they intended it. Remove host-added wrappers such as connector Markdown, app URIs, hidden local paths, or tool-call serialization; keep the visible command text, such as/pixellab-pip. When the generation used one or more user-supplied input images (any role — source, reference, style, mask, init, frame, and the like), copy each into the folder by copying the file, not by reading and re-writing it. - After every live generation flow, write a manifest beside the outputs using
references/usage-reporting.md; keep its private audit/resume data out of the shareable blueprint.
Destructive Remote Actions
Deleting, clearing, or overwriting existing remote PixelLab assets — characters, objects, tiles, tilesets, fonts, UI, portraits, effects, maps and the objects placed on them, their states, animations, or tags — in a way that discards or replaces content already stored remotely is irreversible and requires explicit user permission before it happens: either an instruction that names the deletion or overwrite, or the user's approval of a destructive change you propose. Creating a new asset, state, or animation is additive, not destructive, and is not gated here. Never delete or overwrite unilaterally as an inferred fix, cleanup, reset, sync, migration, or troubleshooting step, and never because a local list, cache, or app view looks empty, stale, or out of sync — the remote is the source of truth, so investigate read-only first (list_*/get_*, REST GET) and report what you find instead of destroying it. Proposing a destructive change is fine; carrying it out before the user approves is not. Before a confirmed destructive op, list exactly what will be removed or replaced (names/IDs and count); bulk or clear-all requires the user to confirm that scope. This covers the delete_* MCP tools, MCP save_to_asset when its target already exists, remove_map_object, terrain-erasing edit_map and tile-erasing place_map_tiles ops (preview them with dry_run: true first), REST /vfx calls with effect_id (saved over in place), and REST delete/replace endpoints.
For character file synchronization, compare the returned updated_at value or URL ?t= stamp with the local copy and download only changed assets; do not use a stale cached image as evidence that the remote needs replacement.
Surface Rules
| Surface | Use for | Avoid |
|---|---|---|
| Hosted MCP | Managed PixelLab assets with IDs, polling, downloads, list/get/delete helpers, Creator gallery browse/save-back (list_images, save_to_asset), animated VFX (vfx_workbench), talking-portrait/lip-sync tools, and map/project/sandbox/agent helpers, including get_upload_url for local-image uploads, create_ui_asset, create_font, or create_portrait_character when visible; also raw-image primitives create_image_pixflux/create_image_pixen/create_image_pro/get_image, edit_image, edit_image_pixen, inpaint_image, animate_image, animate_image_pixminimax, animate_with_skeleton_v3, create_normal_map, transfer_outfit, image_to_pixelart, image_to_pixelart_pro_flash, and the cleanup tools unzoom_image/correct_pixelart/reduce_colors when visible — these need no managed asset. PixelArt Workbench uses its own command workflow; read references/pixelart-workbench.md for supported inputs. Pro Flash image-to-pixel-art conversion is available alongside image, character, object, edit, and inpaint tools; read references/pro-flash.md. |
REST-only controls such as multi-image style reference (generate-with-style-v2), freeform UI (generate-ui-v2), image-to-text, stateless lip sync, the older Pro image-to-pixel-art route, or packed spritesheet/ZIP export; resize and remove-background (no MCP tool); or any MCP call when PixelLab MCP tools are not visible. |
| REST v2 | Scripts, batch jobs, server integrations, exact endpoint control, and REST-only capabilities such as multi-image style reference, freeform UI, base-tier edit/inpaint controls, one-pose skeleton estimation, legacy three-frame skeleton animation, image-to-text, and route-specific enhancement fields that the visible MCP tool lacks (see the Intent Router for exact routes) — plus any of the MCP-covered work below when MCP tools are not visible. | Guessing SDK methods instead of checking the installed SDK or current docs. |
| Website / Map Workshop / Game Builder | Human product surfaces, the Creator queue, Game Builder (Tier 1+), full-map manual work, Godot/Unity map export, rich libraries, visible browser assistance. | Programmatic use of copied browser session tokens or undocumented internal endpoints used by first-party surfaces. |
| Aseprite plugin | In-editor workflows when the user is actively working inside Aseprite. | Treating private first-party extension endpoints as public REST/MCP contracts. |
| Aseprite CLI | Explicit Aseprite handling after PixelLab produced files: .aseprite workspaces, importing frames as layers/frames/tags, palette work, export/open via documented CLI/Lua. |
Mouse/OCR UI automation or hidden control of the PixelLab Aseprite extension. |
| Pixelorama / website editor | The PixelLab website editor is Pixelorama-powered; assist it only as visible browser automation after explicit permission, and ask again before login/session actions, spending credits, generations, downloads, edits, or deletes. | Hidden automation, undocumented endpoint calls, or any destructive action without a second confirmation. |
| REST v1 | Existing legacy code and old SDK compatibility. | New work unless the user explicitly needs v1. |
Hosted MCP tool names are not REST endpoints; do not curl MCP tool names as /v2/... paths.
Intent Router
For any atlas or spritesheet request with known or requested cell dimensions, also read references/local-asset-assembly.md for the required grid inspection preview.
| User intent | Default route | REST v2 route for code/exact control |
|---|---|---|
| Explicit Pro Flash image, character, object, edit, inpaint, or image-to-pixel-art conversion; Pro Flash comparison | Read references/pro-flash.md for the separate tools, native-size and input rules, operation-specific costs, provisional cost checks, and verification. Do not silently replace a tested default with this unbenchmarked family. |
create-image-pro-flash, create-character-pro-flash, create-object-pro-flash, edit-image-pro-flash, inpaint-image-pro-flash, image-to-pixelart-pro-flash; GET /pro-flash/capabilities and /pro-flash/cost. |
| PixelLab experimental Create VFX page | Use the visible website page https://www.pixellab.ai/create-vfx only when the user specifically requests that page. MCP vfx_workbench is a separate agent-authored workbench; REST POST /vfx is documented as the page's own effects artist. |
POST /vfx; read references/vfx-workbench.md. |
| Managed/multidirection character, player, NPC, enemy, creature (default for general character requests) | MCP create_character with mode="v3" by default, then create_character_state, animate_character, get_character, update_character_tags, list/delete helpers. Read references/animation.md for animation engine selection; read references/preset-skeleton-template-animation.md when body plan or reference images matter. A character group's name is shared; when the user names a new state, pass state_name, otherwise PixelLab derives it from the edit description. For a follow-up animation on a multi-direction character, animate south first; ask before animating all directions. outline and outline wording in description are both ignored on v3 and Pro character generation; say so instead of spending credits tuning it. Neither the schema nor an echoed get_character value is evidence otherwise — only changed art is. Pixen/v3/new may underweight user instructions for shape, pose, or view. Offer Character Pro when it fits the request after disclosing its higher cost and different style; use it only if the user chooses it. get_character returns a download link, not a full ZIP bundle — use REST GET /characters/{id}/zip for the packaged archive, or GET /characters/{id}/spritesheet (object twin GET /objects/{id}/spritesheet) for one packed sheet plus a layout JSON. PixelLab sets the cell size, so a user-specified cell size still needs local assembly. |
create-character-v3, create-character-with-4-directions, create-character-with-8-directions, create-character-pro, state/animation/tags/ZIP/list/get/delete endpoints. |
| Explicit single still character sprite | Use the general-image row and read references/characters.md for candidate/identity checks. Use Pro Flash only when selected under references/pro-flash.md, not as an automatic upgrade. |
The selected general-image route. |
| Text-only quadruped character | Default to v3: ask for a south-facing reference and use mode="v3" with the matching template; v3 without a reference is humanoid-only. If the user requires text-only, explain that v3 does not support text-only quadrupeds and offer Pro Flash (create_character_pro_flash with the matching template_id; read references/pro-flash.md) or Pro only as opt-ins after disclosing their cost. Read references/preset-skeleton-template-animation.md for templates. |
Default to create-character-v3 with a matching quadruped template_id and reference. Offer create-character-pro-flash or create-character-pro only if the user explicitly chooses text-only after the cost is clear. |
| Supplied character reference image to managed character | Use MCP create_character(mode="v3") with a finished south-facing sprite; supply direction_images for other views to preserve them. For loose concept art that should seed a Pro character's look without preserving pose or canvas, use concept_image_url or concept_image_base64 only after the user chooses Pro. Read references/image-input-roles.md and references/preset-skeleton-template-animation.md for role and direction rules. |
REST create-character-v3 also supports matching quadruped template_id values; REST create-character-pro supports method="create_from_concept"; use the live schema for exact fields. |
| Portrait-to-character or character-to-portrait | MCP create_portrait_character + get_portrait_character when visible. |
portrait-character-pro (Pro image conversion). Supplied-image roles: references/image-input-roles.md. |
| Talking portrait, mouth/viseme sprites, talking GIF, or lip-sync timing plan | Read references/vocal-animation.md. Use the MCP set_character_portrait, create_vocal_animation + get_vocal_animation, create_talking_gif, and get_lip_sync tools when visible. |
POST /characters/{character_id}/portrait, POST + dedicated GET /vocal-animation/{job_id}, POST /talking-gif, and POST /lip-sync; REST is required for stateless lip sync. |
| Pixel/bitmap font, font atlas | MCP create_font + get_font when visible. |
generate-font-pro (Pro). |
| Skill/ability/spell/action-bar/hotbar icon, inventory item/equipment/loot/pickup icon, emoji, or icon sheet | Read references/icon.md before choosing an endpoint or generating. |
The reference covers route choice, background defaults, sheet sizing, prompt wording, and verification. |
| Standalone object, prop, pickup, weapon, furniture (not an icon) | MCP create_1_direction_object, create_8_direction_object, object state/animation/tags/review tools. Pass MCP name when the user names a new object; it defaults to the description. An object's name is shared across directions and states; for a named new state pass state_name, otherwise PixelLab derives it from the edit description. Object creation is Pro Tools; candidate sheets and eight-direction objects use different prices (see references/cost-routing.md). |
create-1-direction-object, create-8-direction-object, object state/animation/tags/list/get/delete endpoints. The REST create schemas have no name field; if the stored name matters and MCP is unavailable, tell the user before creation. |
| Tileset or terrain transition with no stated type or projection; square top-down, Wang, or autotile tileset | Read references/tileset.md, then MCP create_topdown_tileset; this is the default when no tileset type, projection, or route is specified. |
create-tileset, tilesets. |
Explicit hex, isometric, or oblique connectable terrain transition; or explicit create_tiles_pro/create-tiles-pro tileset mode |
Read references/tileset.md, then MCP create_tiles_pro with tile_feature="tileset". |
create-tiles-pro with tile_feature: "tileset", then tiles-pro/{tile_id}. |
| Sidescroller/platformer tileset | Read references/tileset.md, then MCP create_sidescroller_tileset. |
create-tileset-sidescroller. |
| Isometric tile/block/floor | MCP create_isometric_tile; map thickness wording to tile_shape (thin tile, thick tile, block — same values as REST, default block). |
create-isometric-tile with isometric_tile_shape (thin tile, thick tile, block). |
| Multiple independent tile variants (hex, octagon, square, or isometric) | MCP create_tiles_pro with no tile_feature. |
create-tiles-pro, tiles-pro/{tile_id}. |
| Connectable path/road tile set | MCP create_path_tiles; shares get_tiles_pro/list_tiles_pro/delete_tiles_pro with create_tiles_pro — no dedicated getter. |
create-tiles-pro with tile_feature: "roads". |
| Building kit (floor, connectable walls, doorways, pillar, stairs) | Read references/tileset.md, then MCP create_building_kit; shares get_tiles_pro/list_tiles_pro/delete_tiles_pro with create_tiles_pro — no dedicated getter. |
create-tiles-pro with tile_feature: "building" and building_* fields. |
| Hard-projection top-down/south-facing building sprite | Read references/style-reference.md; use MCP create_image_pro or REST generate-with-style-v2; apply the reference's verification. |
Do not route a single sprite to create_building_kit. |
| General image, sprite, standalone asset that is not an icon or emoji | MCP create_image_pixflux/create_image_pixen/create_image_pro + get_image when MCP-first — same model choice as REST, minus multi-image style reference (REST-only). For explicit Create Image Pro, create_image_pro/generate-image-v2, exact grids/sheets, or below-32px cells, read references/create-image-pro.md first. For full-body Pixen characters, read references/pixen-character-prompt.md. Model character: PixFlux = lower detail, loose/painterly (frames whole subjects); Pixen = high detail, tight framing; Pixen and Pro crop larger subjects; Pro for style/variety or closer adherence to the user's description. Pixen/v3/new has isometric bias and may underweight user instructions such as view/direction; prefer Pro for static south-facing when higher cost and different character style is acceptable. Pixen no_background: true allows up to 65,536 px of canvas area (e.g. 256×256 or 512×128); a larger canvas is refused with it on. |
create-image-pixen, generate-image-v2, create-image-pixflux, generate-with-style-v2. |
| Exact hex palette or color cap on a generated asset or animation | Read references/create-image-pro.md (Exact Palette Control) before choosing the route: many MCP (palette) and REST (target_palette) routes accept it, with surface and mode limits. |
The selected route's target_palette; see the reference. |
| Generate a normal map for a sprite or animation | Read references/image-input-roles.md; use MCP create_normal_map + get_image when visible, otherwise REST POST /normal-map. The 0.4.130 announcement also lists Creator availability, but does not document its UI flow. |
/normal-map accepts a PNG sprite or an equal-frame horizontal strip; choose convention="directx" for Unreal, otherwise the default is OpenGL. |
| Browse/search the Creator gallery, inspect or edit a gallery reference, or save generated/edited pixel art back into a character, object, animation direction, or gallery | MCP list_images for gallery metadata; pass its gallery:<id> reference to get_image to download or to pixelart_workbench for inspection/editing; use save_to_asset for save-back when visible; read references/mcp-platform-tools.md for target and destructive-save rules. |
No public REST v2 equivalent is documented. |
| Pixel-level repair or recipe drawing; inspect, measure, lint, compare, or animate source parts | For explicit pixel operations, read references/pixelart-workbench.md and use MCP pixelart_workbench. Keep open-ended image creation on the normal image-generation routes. |
MCP-only pixelart_workbench; no public REST equivalent. |
| PixelLab image description or visual Q&A | Use REST POST /image-to-text when the user wants PixelLab's read of an image: the default is a generic 1–3 sentence generation description; an optional prompt requests a custom visual answer. For improving existing text for a known generation route, use its matching enhancer instead; do not chain image-to-text before enhancement by default. Answer ordinary image questions directly when possible. |
REST-only; returns text, not an image. |
| Background, scene, backdrop | MCP create_image_pixflux/create_image_pixen (no_background: false) when MCP-first, else REST v2. Route by whether a subject is present: subject-less backdrop (empty landscape/sky/room, no figure) → PixFlux; full scene with a subject in an environment → Pixen. Do not use Pro generate-image-v2/create_image_pro here — its 10–25-generation size tiers are unnecessary for backdrops or scenes. |
create-image-pixflux-background (same schema as create-image-pixflux, so create_image_pixflux covers it too); verify current size/field support before exact code. |
| UI, HUD, button, panel, health bar, menu | MCP create_ui_asset + get_ui_asset when MCP-first — it has both pieces (rounded_rect/circle/polygon) and elements (button, icon_button, toolbar, tab, panel, window, health_bar, avatar, triangle/pentagon/hexagon/octagon); mind its aspect-gated size caps (square ≤512×512, 16:9 ≤688×384, 9:16 ≤384×688, 4:3 ≤600×448, 3:4 ≤448×600). Use REST v2 create-ui-asset (Pro) when MCP is unavailable. generate-ui-v2 (REST-only, no MCP tool) for loose/raw UI images, especially with a concept_image. |
Do not route shape-piece/layout requests to generate-ui-v2. |
| Image edit, inpaint, mask, convert, resize, remove background | For supplied images read references/image-input-roles.md. MCP edit_image and inpaint_image are Pro routes with size-tiered costs (see references/cost-routing.md); prefer their URL inputs and use inline base64 only when needed. MCP edit_image_pixen is the cheap text-instruction edit (1 generation, source ≤256px per side, target area ≤256×256). For conversion, use MCP image_to_pixelart at a requested supported size; without an output-size request, the older REST-only Pro route detects native scale. Pro Flash is a separate six-generation MCP/REST option when requested (see references/pro-flash.md). The older Pro converter, base edit/inpaint weak-guidance controls, resize, and remove-background remain REST-only. |
inpaint, inpaint-v3 (Pro), edit-image, edit-image-pixen, edit-images-v2, image-to-pixelart, the older image-to-pixelart-pro, image-to-pixelart-pro-flash, resize, and remove-background. |
| Fitted paperdoll addition on an existing character image | Treat as an existing_image edit anchored on the base frame; read references/paperdolling.md before choosing layer/composite outputs. |
Do not use object generation for fitted layers unless the user explicitly wants an unattached prop. |
| Set up, pick, change or save a project's art style, or match art the user shows | Read references/project-style.md; use assets/project_style.py when Python is available; optional assets/analyze_style.py supplies advisory measurements, not automatic art direction. |
Applying any look the user did not choose. |
| Style-reference or consistent-style generation | Read references/style-reference.md. Single style image or labelled references → MCP create_image_pro (preferred image URLs, plus style_copy) when MCP-first, else REST generate-image-v2. Multi-image style reference (style_images array, with optional style_description) is REST-only — no MCP tool has that shape. |
generate-with-style-v2 or generate-image-v2 style/reference fields after checking current docs. |
| Clean up pixel art, quantize/reduce colors, unzoom upscaled art | MCP correct_pixelart, reduce_colors, unzoom_image (0.1 generations each) + get_image, else REST v2. correct_pixelart and reduce_colors take a frame list — batch an animation's frames or a character's directions into one call so they stay consistent; unzoom_image is one image per call. |
correct-pixelart, reduce-colors, unzoom. For file-level palette clamps on local copies, read references/aseprite-cli.md. |
| Clean up or finish generated frames locally (stray pixels, flashes, floating poses, colour drift, trails, thrown props, baked effects) | Read references/finishing.md. |
Local assets/finish/ helpers; no PixelLab call. |
| Editor-only utilities (Canny/Pose/Depth, reshape) | Read references/editor-only-utilities.md. |
No public REST/MCP route exists for these; do not invent /v2/... routes. |
| Try on garment/accessory | Website Try on (single composited image); for animation-frame outfit transfer use MCP transfer_outfit when visible, otherwise REST transfer-outfit-v2. |
Try on and outfit transfer return composited imagery, not isolated paperdoll layers. |
| Multi-image combine/edit | MCP edit_image (Pro; preferred image_urls, or inline base64, with optional reference URL/base64) when MCP-first, else REST v2 edit-images-v2; website/editor for visual experimental flows. |
Aseprite's generate-multi-edit is an internal endpoint, not public REST. |
| Prompt enhancement | Matching enhance endpoint or inline enhance_prompt per Text Preparation. |
enhance-pixen-prompt, enhance-character-v3-prompt, enhance-animation-v3-prompt (engine="v3", "pixminimax", or "skeleton-v3"), or the inline enhance_prompt on animate-pixminimax. |
| Explicit preset/template/built-in animation | Read references/preset-skeleton-template-animation.md; it covers managed templates and points to the Skeleton v3 and legacy raw routes. |
Do not call website root /generate-animation/background or Aseprite extension internals. |
| Explicit custom key poses/choreography, pinned pose stages, or an approved advanced attack recipe | Read references/key-pose-animation.md for this optional production method; ordinary attacks follow the raw/managed animation row. Use a padded canvas when needed, a selected supported edit route for reviewed key poses, then raw interpolation; Pro Flash pose editing is an explicit recipe choice. |
Selected edit route, then animate-with-text-v3 with first_frame + last_frame, or the otherwise selected raw-animation route. |
| Check or fix animation frames (jumps, flicker, specks, wrong size, a weapon that vanished), or plan re-rolls of bad frames | Read references/animation-doctor.md, then inspect with python <skill-dir>/assets/fix.py <frames> --check-only --out <dir>; omit --check-only only for requested/accepted repairs (free, local; optional dependencies skip clearly). |
Re-rolling the whole animation when only some frames failed. |
| Skeleton v3, pose-keypoint animation, or auto-rig pipeline | Read references/animation.md → Route Choice for custom-vs-preset selection, then references/preset-skeleton-template-animation.md for managed MCP/REST custom motion, preset clips, raw keypoints, and auto-rig instructions. |
animate-character / characters/animations for managed motion; animate-with-skeleton-v3 for raw sequences. estimate-skeleton supplies only one pose; legacy animate-with-skeleton has a separate three-frame contract. |
| Raw or managed text-driven animation, interpolation, outfit transfer, rotate | Read references/animation.md → Route Choice for the PixMiniMax default, explicit engine/template requests, count/cost exceptions, and managed-object limits. If MiniMax H3 is a strict provider requirement, use raw REST POST /animate-pixminimax; the managed provider is undisclosed. The same reference covers provider evidence, managed/raw differences, frame anchors, prompt adaptation, idle-loop risk, outfit-transfer inputs, and verification. For outfit transfer on animation frames, use MCP transfer_outfit when visible, otherwise REST transfer-outfit-v2. For 8-rotations-from-an-image, MCP only partially covers it by regenerating rather than rotating the exact input: create_character(mode="v3", reference_image_base64=…) for character/humanoid sprites, create_8_direction_object(reference_image_base64=…) for props. |
Managed PixMiniMax: REST /animate-character or /characters/animations; raw animation: animate-with-text-v3, animate-pixminimax, edit-animation-v2, interpolation-v2, transfer-outfit-v2, rotate, generate-8-rotations-v2/v3 (use the rotation route when exact input pixels must be preserved, not regenerated). No public 4-rotation route. For a start→end tween prefer the selected raw animation route; use interpolation-v2 only on an explicit Pro/v2 request. |
| Multi-shot, multi-second, or seamless-loop cinematic (a scene longer than one clip) | Read references/cinematic.md; requires a user-specified budget, a documented plan, and per-shot validation. Select the raw animation engine via references/animation.md → Route Choice, with preferred frame URLs or inline base64. |
Selected raw route (animate-pixminimax or animate-with-text-v3) — one looped clip for cyclic motion, chained shots (each from the previous handoff frame) for evolving scenes, or first_frame+last_frame for a strict start→end tween. |
| Furnished room with a floor plan and doorways, or room furniture cutouts | MCP create_room, get_room, and optional cut_out_room_furniture; read references/scenes-and-backgrounds.md for plan/tier/cost and view restrictions. Ordinary room background pictures use the Background row. |
MCP-only; no public REST v2 room route. |
| Map image / visual level concept | MCP create_image_pixflux/create_image_pixen + get_image when MCP-first (same subject-vs-subject-less split as the Background row), else REST v2 image/background route; website or Aseprite for map extension workflows. |
No public map extension/texture surface is documented. |
| Map object | MCP create_map_object + get_map_object, then place_map_object to put it on a map. |
POST /map-objects, then GET /map-objects/{object_id} for status + metadata. |
| Whole map, map CRUD, terrain tiles, or placing/moving/removing objects and characters on a map | MCP only: read references/mcp-platform-tools.md before remove_map_object; placement_id targets one placement, while asset_id removes every placement of that asset from the map. Use create_map (seeded from a top-down tileset, or from a tiles-pro/path/building tile group via tile_group_id), edit_map (path/rect terrain-tile ops), place_map_tiles (place, stack, or erase tile-group tiles on tile layers), get_map, view_map, list_maps, delete_map, and place_map_object/move_map_object/remove_map_object/list_map_objects. Otherwise use the visible website Map Workshop manually; use its Godot/Unity export when requested. |
No public REST v2 map or map-export surface is documented; do not invent /v2/maps... routes. |
| Game Builder or game-building project | For Tier 1+ users, use the visible Game Builder workflow. If compatible MCP project/chat/sandbox tools are visible, read references/mcp-platform-tools.md before using them and pass project_id only for the requested project context. |
No public REST v2 Game Builder endpoint is documented; do not invent one. |
| Static effect/VFX sprite | If a target image is supplied and the user asks to add an effect to it, MCP edit_image (pro) when MCP-first, else REST image edit, on that target; otherwise default isolated reusable VFX to Create Image Pro (create_image_pro/generate-image-v2) and read references/create-image-pro.md. |
Pro is the reliable effects/variety route found in focused testing; Pixen is retry-heavy and unreliable for effect-only assets. Edit routes return a whole edited image, not an isolated effect layer; no static VFX endpoint is documented. vfx_workbench is for animated effects. |
| Animated effect/VFX | Use MCP vfx_workbench when visible; use REST POST /vfx when it is not, for code or batch integrations, or when the user wants PixelLab's own effects artist. Read references/vfx-workbench.md for both. For free-form motion on a supplied raw image without effect-part or anchor controls, or a managed object animation, select the route via references/animation.md → Route Choice. |
Effects artist: POST /vfx. Raw animation uses animate-pixminimax, animate-with-text-v3, animate-with-skeleton-v3, or legacy animate-with-skeleton; managed object animation uses the object animation endpoints. |
| Balance, credits, account check | MCP get_balance if available. |
GET /balance. |
| REST async job status or cancellation | Poll GET /background-jobs/{job_id}; while processing, last_response.queue_position and last_response.estimated_wait_seconds expose queue information. Use HTTP DELETE on /background-jobs/{job_id} only when the user explicitly approves cancellation; read references/job-lifecycle.md. Vocal animation is the exception and uses GET /vocal-animation/{job_id}. |
MCP managed assets use resource-specific get_* tools instead. |
| PixelLab projects, sandbox, chat, deployed agents, job control, MCP help/knowledge/feedback | Read references/mcp-platform-tools.md before using list_projects, add_to_project, remove_from_project, sandbox_*, chat_*, agent_*, search_knowledge, list_jobs, wait_for_jobs, or cancel_job. |
No public REST v2 equivalent is documented for the platform helpers, active-job list, or all-job wait; REST cancellation uses HTTP DELETE on /background-jobs/{job_id}. |
Discover, inspect, select, or replay blueprints/recipes, including a supplied *.blueprint.json |
Read references/blueprint.md. For actual replay follow its discovery/selection/replay contract. When a blueprint is only a look or identity source for a different requested asset, route that new asset normally and classify its identifiable existing output images with references/image-input-roles.md; do not replay merely to obtain missing references. Recorded route/size/seed/mode do not become defaults for the new asset. A blueprint name that contains an asset word (e.g. "knight") is still blueprint intent when the conversation identifies it as one. |
Actual replay uses the exact recorded route (MCP <tool> or POST /v2/...); reference-only use follows the new asset route. |
Clarify Only For Collisions
- "Presets": infer bundled blueprints from established blueprint context and preset/template animations from animation or motion context; ask which collection only when neither is clear.
- "Tiles": top-down/autotile tileset, platformer tileset, explicit-projection connectable set, independent variants, one isometric tile, path set, building kit, or packed texture sheet?
- "Map": tile-based map (MCP map tools), map object, flat map image, tileset, isometric tile, or tile variants?
- "Isometric tileset": one tile, independent variants, or a connectable terrain set? Ask when unclear; only the connectable set uses
tile_feature="tileset". - "Object/character": infer character for people, NPCs, creatures, or identity/state animation; object for standalone props, pickups, furniture, weapons. Ask only if unclear.
- Animation direction on a multi-direction character: default to
southfor one preview candidate; ask only whensouthis unavailable, directions are unknown, or the user needs another gameplay-facing direction. Animate all directions only on explicit request or approval. - "Effect": static or animated? If a target image is supplied, infer a one-off edit; ask reusable-asset vs one-off only without a clear edit target.
- "Paperdoll": gather base image, desired layers, target regions, directions, and whether the user wants separate transparent layer files, editor layers, composited previews, or both; see
references/paperdolling.md. - Supplied images: infer each file's low-risk endpoint-specific role from wording. Before credit-spending calls, ask when role uncertainty (identity vs style vs concept vs edit target vs mask vs palette vs first/last frame) would change the endpoint or output; see
references/image-input-roles.md. - If prompt enhancement adds material inferred details, surface the proposed description in the cost-approval gate (
references/auto.md) before a credit-spending call.
References
Resolve every references/ path against this skill's own directory (the parent of this SKILL.md) and use an absolute path in the tool call. If that directory is unknown to you, find the pixellab-pip/references/ folder by listing or searching the workspace and agent-skill directories before acting; do not skip the read. When a rule names a reference, open and read it before acting, then follow its current text — not memory or a summary. Your training does not contain these PixelLab-specific contracts, so answering from general knowledge — for example treating Pip as a pip-installed Python package — will be wrong. If a required reference cannot be read, say so and stop rather than improvise its contract.
Read each reference only when its trigger applies:
- Bearer-token setup, PixelLab UI naming, MCP auth reuse:
references/credentials.md. - Setup wizard for MCP, REST v2 fallback, auth after install:
references/setup.md. - Update an installed Pip to the latest version:
references/update.md. - Remove an installed Pip:
references/uninstall.md. - Persistent completion sound toggle:
references/bark.md. - Cost-approval gate before paid calls, the
autoon/off toggle and explicitly bounded run budgets/retries:references/auto.md. - Interactive project/output review and
/pixellab-pip panel:references/panel.md. - Safe post-processing when
no_background: truefails:references/background-removal.md. - Skill/ability and inventory item icon sheets:
references/icon.md. - Create Image Pro, exact hex palettes or color caps on any route, native-size multi-output batches, exact grids, below-32px cells:
references/create-image-pro.md. - Explicit Pro Flash image/character/object/edit/inpaint/pixel-conversion or comparison:
references/pro-flash.md. - Cheap/budget/credit-minimizing route selection:
references/cost-routing.md. - Paperdolling and layered characters:
references/paperdolling.md. - Review/choice handling for static candidate alternatives:
references/reviewable-candidates.md. - Animated effects through MCP
vfx_workbenchor REST/vfx:references/vfx-workbench.md. - Tilesets and tile variants:
references/tileset.md. - Project art styles kept across assets (
pixellab-pip-style.json; the user always chooses the style, named examples offered):references/project-style.md,references/style-examples.md. - Still character sprites (hero, NPC, monster, boss): route, description, candidates, the look checklist at 3x, colour variants, adding a prop:
references/characters.md. - Battle/level backgrounds, hub backdrops, story pictures, region maps, building sprites and upgrade tiers:
references/scenes-and-backgrounds.md. - Normal maps for sprites or animations (input packing, clip splitting, lit preview, engine wiring):
references/normal-maps.md. - A character move in 8 facings for top-down or 3/4 games:
references/eight-direction.md. - Style-reference generation, Aseprite-equivalent square padding, and output sizing:
references/style-reference.md. - Supplied image roles, endpoint image fields, fixed-size image-to-pixelart:
references/image-input-roles.md. - Pixel-level drawing, repair, inspection, comparison, and recipe animation:
references/pixelart-workbench.md. - Non-English or mixed-language requests:
references/localization.md. - Official PixelLab doc URLs and boundaries:
references/official-pixellab-documentation.md. - Generation reports and manifests after PixelLab calls:
references/usage-reporting.md. - Per-generation blueprint (PixelLab calls + agent tasks), recreation, and sharing:
references/blueprint.md. - Async jobs, MCP review state, rate limits, download expiry, tools refused by the user's plan:
references/job-lifecycle.md. - Preset/template/skeleton character animations:
references/preset-skeleton-template-animation.md. - Raw animation, interpolation, outfit transfer, idle-loop risk:
references/animation.md. - Weapon, fighting, armour/cloth and weapon-effect motion (visible pose wording, key poses, frame rhythm, pitfalls):
references/weapon-<name>.md, where<name>issword,katana,dagger,staff,bow,mace,spear,axe,sword-and-shield,war-hammer,whip,firearms(pistols, rifles, shotguns),futuristic(arm cannons, energy blades),anime(giant swords, scythes, kunai, chibi) oreffects; plusreferences/martial-arts.mdandreferences/armor-clothing.md. Read only the page for the weapon or effect at hand. - Talking portraits, viseme generation, talking GIFs, and lip-sync plans:
references/vocal-animation.md. - Multi-shot, multi-second, or seamless-loop cinematics from chained animations:
references/cinematic.md. - Editor-only utilities without public routes:
references/editor-only-utilities.md. - PixelLab project/sandbox/chat/agent MCP tools:
references/mcp-platform-tools.md. - REST v2 prompt/field character limits:
references/prompt-limits.md. - Explicit Aseprite handling,
.asepriteworkspaces, palette quantization, CLI/Lua export:references/aseprite-cli.md. - Third-party Aseprite MCP servers:
references/aseprite-mcp.md. - Before any bundled image helper: dependency/skip requirements, decoded-image checks, atlas/spritesheet grid previews, local assembly, GIFs and ImageMagick:
references/local-asset-assembly.md.
Optional broader docs: in full plugin/repo installs these resolve relative to this SKILL.md; raw skill installs may omit them. Read at most one matching file if runtime references are not enough; if absent, continue with references/official-pixellab-documentation.md and current official docs.
- Surface boundaries and service selection:
../../docs/pixellab/pixellab-surfaces-and-services.md. - Plain-language asset routing:
../../docs/pixellab/pixellab-asset-routing.md. - Product/model/mode terminology:
../../docs/pixellab/pixellab-terminology.md. - SDK-vs-REST compatibility:
../../docs/pixellab/pixellab-sdk-compatibility.md. - Bearer-token, session, and security boundaries:
../../docs/pixellab/pixellab-auth-and-security.md. - UI generation and MCP-vs-REST UI routing research:
../../docs/pixellab/pixellab-ui-generation-surfaces-research.md. - Multi-shot cinematic technique research (chained-animation findings):
../../docs/pixellab/pixellab-cinematic-spike.md. - Cinematic scene composition and motion technique (inspiration):
../../docs/pixellab/pixellab-cinematic-inspiration.md.
Model And Mode Terms
Treat PixelLab model/provider language as product labels unless official docs disclose more. Do not invent provider internals where docs are silent.
Pixen,PixFlux: product/workflow labels, not guaranteed provider names.PixMiniMax: PixelLab's label for raw-frame animation and managed-character mode; provider attribution varies by surface. Seereferences/animation.mdfor the public evidence and route details.PixPatch: website-surface label; no public v2PixPatchendpoint exists.Pro: a quality/tier label across many unrelated tools, not one endpoint or model. Treat Pro and Pro Tools routes as expensive unless current docs prove otherwise.Pro Flash: a separate beta image/character/object/edit/inpaint/pixel-conversion family, not a faster alias for existing Pro routes. Readreferences/pro-flash.mdfor size-based prices, rotation charges, and the REST/MCP pricing discrepancy.v3andnew: workflow/version labels scoped to a selected operation. Cheap-family hints, but check the endpoint — RESTinpaint-v3is documented as Pro.standard: characterstandardis deprecated for Pip routing; do not recommend it. The separatestandardmode on top-down tilesets is a different workflow — readreferences/tileset.mdfor its routing.S-XL,M-XL,S-M,M-L: size/product labels, not asset intents.Gemini: retired label, absent from current REST v2 and MCP docs. Do not present it as a current tier or provider.
Text Preparation
Exact field values win over prompt prep. If the user explicitly supplies a PixelLab-facing field value, such as prompt: ..., description: ..., action: ..., or use exactly ..., send that value unchanged and do not enhance it. If it is invalid, over limit, or unsafe, stop and ask for an approved replacement or trim before spending credits.
Prompt enhancement is opt-out. Otherwise, for natural-language parameters such as description, style_description, negative_description, *_description, action, item_descriptions, text, and color_palette, produce the best concise PixelLab-ready English value from the request and visible inputs before calling a tool. For non-English or mixed-language requests, load references/localization.md and obtain the user's approval for the exact English transformation before the first external call. Exception: /talking-gif.text, /lip-sync.text, and their MCP text_to_speak fields are dialogue content; preserve the user's wording exactly and do not enhance or translate it.
Prompts describe visual content or, for action fields, depicted motion — never tool operation, output metadata, or report status. Include only details that change output; omit boilerplate already expressed by a supported control. Prefer supported controls and positive structural wording. Use inline exclusions only for a specific visual constraint, not generic boilerplate; no separate field is required. On Pixen, describe the intended empty or replacement state instead of naming an otherwise absent object only to exclude it. Send negative_description only when the live schema exposes it. For a named visual style, state it briefly and avoid conflicting render adjectives; use route-specific references for additional style guidance.
Respect documented character limits: many REST v2 description fields allow 2000 characters, but several action/edit/style fields cap at 500. On a length rejection, trim without changing intent, note the adjustment, and retry. Exact limits: references/prompt-limits.md or OpenAPI.
Use one enhancement path per call. Inline enhance_prompt flags exist on create-image-pixen, animate-with-text-v3, animate-pixminimax, create-character-v3, animate-character/characters/animations, and object animations, cost about 0.05 generations, and are preferred over a separate enhancer call when the route has one. Constraints: for character/object animation, enhance_prompt is valid only with mode="v3"; for create-character-v3 it is valid only for from-scratch generation; on animate-pixminimax, enhance_prompt rewrites the motion-only action caption, while direction is a separate facing caption field and may be used with or without enhancement. The current PixMiniMax schema also exposes optional subject_description, initial_pose, and view caption fields; omit them only when image inference is acceptable. These fields are surface-specific: MCP animate_image_pixminimax exposes enhance_prompt, direction, subject_description, initial_pose, and view but not REST's drift_threshold; create_image_pixen, animate_image, and create_character expose no enhance_prompt, so on those MCP-first routes enhance directly as the agent instead. Standalone enhancers: enhance-pixen-prompt for Pixen image prompts, enhance-animation-v3-prompt for animation actions (engine="v3", "pixminimax", or "skeleton-v3"), and enhance-character-v3-prompt for character-v3 prompts. Otherwise enhance directly as the agent; do not force a mismatched enhancer.
Do Not Use
- No local code or editor automation to create or alter requested visual content: no PIL/Pillow drawing, canvas/SVG drawing, ImageMagick draw, Aseprite Lua drawing, ASCII-to-image, or procedural pixel placement. Local code may copy, mask, composite, and verify pixels that came from PixelLab or the user.
- No undocumented internal endpoints used by first-party surfaces: root website routes, unversioned
api.pixellab.aipaths like/tilesets/create, or Aseprite extension operation URLs. Treat them as unsupported unless they appear in public REST v2 docs/OpenAPI or MCP docs. - Never ask for the PixelLab bearer token in chat; direct users to the setup wizard, local
PIXELLAB_SECRET, or app secret settings. If a token appears in chat or tool output, do not repeat or use it; tell the user to treat it as exposed and replace it before continuing. - Never scrape browser session tokens or cookies. Website session tokens are not API bearer tokens; never use one for the other.
- Do not default to v1 or old SDK README examples for new work, and do not assume an installed SDK covers every current v2 endpoint — confirm the installed package or call REST v2 directly.
Current Docs Refresh
Route from this skill first. Refresh official docs only when a needed tool, endpoint, field, schema, SDK detail, auth step, price/limit, or model/mode claim is missing or unclear. Start lightweight (REST v2 llms.txt, MCP docs); fetch openapi.json only for exact schemas, reading a field's existence, type, or default from the raw JSON, not a prose summary. Links and their limits: references/official-pixellab-documentation.md.
If web access is unavailable, answer from this skill and say which current claim could not be freshly verified.
Auth And Execution
If no bearer token is configured, stop before generation and offer the setup wizard: the user opens https://www.pixellab.ai/account after signing in, copies the value labeled Secret, and stores it locally as PIXELLAB_SECRET or in app secret settings — never pasted into chat. For Manual setup, link https://www.pixellab.ai/mcp and stop. PixelLab UI/docs may call this value an API key, API token, or secret; for REST/MCP bearer auth, call it a bearer token.
A Python launcher that fails before Python starts does not mean Python is missing: on Windows, try each where.exe python3 and where.exe python result and use the first that passes --version. Never install Python. When a helper skips with exit 3 for a missing or outdated package, report the step as not done and name that package from the skip reason; install packages only when the user asks.
For questions, answer with: recommended surface/endpoint, why it fits, warnings for unsupported alternatives, and a verification note only when the answer depends on an unverified current fact.
For tasks, generate only when the user clearly requested it and token plus tooling are configured. For nontrivial work, produce one candidate first, report it, and continue only if asked. Before the first credit-spending call, apply the cost-approval gate in references/auto.md: unless Auto is on, plan the whole paid chain, then in one message show every predicted paid call, its material inputs (including the exact prompt text), and a rough total for approval; also apply current-run constraints. For destructive remote actions, follow Destructive Remote Actions. Refuse unsupported automation and reroute to the closest documented MCP/REST option or a visible manual website flow. Locally authored non-PixelLab visual content requires explicit request or approval and a non-PixelLab-fallback label.
Capture a balance snapshot before a nontrivial paid call when available. After live PixelLab work, read `references/usag
Files (pixellab-pip)
-
assets
-
finish
-
apply_palette.py 2.6 KB
Loading… -
bake_fx.py 3.7 KB
Loading… -
blade_trail.py 5.3 KB
Loading… -
colormatch.py 1.6 KB
Loading… -
despeckle.py 3.1 KB
Loading… -
dir8_finish.py 5.3 KB
Loading… -
find_muzzle.py 3.7 KB
Loading… -
ground_snap.py 2.9 KB
Loading… -
recolor_groups.py 5.9 KB
Loading… -
recolor_like.py 5.7 KB
Loading… -
recolor_trail.py 7.4 KB
Loading… -
scrub.py 4.6 KB
Loading… -
slash_layer.py 3.8 KB
Loading… -
throw_prop.py 2.9 KB
Loading… -
_derive.py 3.3 KB
Loading…
-
-
fixlib
-
colour.py 1.7 KB
Loading… -
frames.py 9.6 KB
Loading… -
measure.py 26.4 KB
Loading… -
model.py 2.1 KB
Loading… -
plan.py 9 KB
Loading… -
repair.py 15.2 KB
Loading… -
report.py 8.8 KB
Loading… -
thresholds.py 3.6 KB
Loading… -
timing.py 2.5 KB
Loading… -
__init__.py 0 B
Loading…
-
-
analyze_style.py 12 KB
Loading… -
background_removal.py 14.7 KB
Loading… -
bark.py 9.8 KB
Loading… -
bark.wav 31.9 KB · in bundle
-
contact_sheet.py 2.6 KB
Loading… -
fetch.py 9.9 KB
Loading… -
fix.py 12.4 KB
Loading… -
history.py 6 KB
Loading… -
inspect_images.py 3.6 KB
Loading… -
make_sheet.py 4.4 KB
Loading… -
manifest.py 12.1 KB
Loading… -
normal_map.py 4.9 KB
Loading… -
pad_sprite.py 1.2 KB
Loading… -
panel.html 10.3 KB · in bundle
-
panel.py 21.2 KB
Loading… -
paperdoll.py 4.8 KB
Loading… -
preview_gif.py 1.8 KB
Loading… -
project_style.py 16.1 KB
Loading… -
showcase_gif.py 4.7 KB
Loading… -
tileset_preview.py 4.6 KB
Loading… -
_assembly.py 3.2 KB
Loading… -
_gif.py 3.7 KB
Loading…
-
-
blueprints
-
aura.blueprint.json 6.8 KB
Loading… -
background-aura.blueprint.json 1.6 KB
Loading… -
character-candidates.blueprint.json 4.5 KB
Loading… -
ground-aura.blueprint.json 1.6 KB
Loading… -
knight.blueprint.json 3 KB
Loading… -
overhead-axe-chop.blueprint.json 7.5 KB
Loading… -
overlay-aura.blueprint.json 1.6 KB
Loading… -
paired-sprites.blueprint.json 2.4 KB
Loading… -
portable-sprite.blueprint.json 1.7 KB
Loading… -
portrait-head-shoulders-mvp.blueprint.json 2.8 KB
Loading… -
projectile-skill.blueprint.json 10.2 KB
Loading… -
rpg-maker-character.blueprint.json 21.8 KB
Loading… -
status-effect.blueprint.json 1.6 KB
Loading… -
turntable-rotate-16.blueprint.json 4.2 KB
Loading… -
vfx-eruption-per-target.blueprint.json 6.5 KB
Loading… -
vfx-strike-single-target.blueprint.json 5.5 KB
Loading… -
vfx-wave-across-party.blueprint.json 7.8 KB
Loading… -
wall-aura.blueprint.json 1.6 KB
Loading…
-
-
references
-
animation-doctor.md 7.6 KB
Loading… -
animation.md 21.6 KB
Loading… -
armor-clothing.md 14.6 KB
Loading… -
aseprite-cli.md 27.2 KB
Loading… -
aseprite-mcp.md 1.8 KB
Loading… -
auto.md 14.7 KB
Loading… -
background-removal.md 4.3 KB
Loading… -
bark.md 4.3 KB
Loading… -
blueprint.md 20.1 KB
Loading… -
characters.md 6.7 KB
Loading… -
cinematic.md 20.9 KB
Loading… -
cost-routing.md 16.9 KB
Loading… -
create-image-pro.md 12.4 KB
Loading… -
credentials.md 6.5 KB
Loading… -
editor-only-utilities.md 1.4 KB
Loading… -
eight-direction.md 5.2 KB
Loading… -
finishing.md 9.3 KB
Loading… -
icon.md 12 KB
Loading… -
image-input-roles.md 16 KB
Loading… -
job-lifecycle.md 11.1 KB
Loading… -
key-pose-animation.md 12.8 KB
Loading… -
local-asset-assembly.md 10.3 KB
Loading… -
localization.md 3.5 KB
Loading… -
martial-arts.md 12.5 KB
Loading… -
mcp-platform-tools.md 5.7 KB
Loading… -
normal-maps.md 3.3 KB
Loading… -
official-pixellab-documentation.md 10.4 KB
Loading… -
panel.md 7 KB
Loading… -
paperdolling.md 14.2 KB
Loading… -
pixelart-workbench.md 3.1 KB
Loading… -
pixen-character-prompt.md 833 B
Loading… -
preset-skeleton-template-animation.md 33.1 KB
Loading… -
pro-flash.md 6.6 KB
Loading… -
project-style.md 5.7 KB
Loading… -
prompt-limits.md 3.7 KB
Loading… -
reviewable-candidates.md 3.3 KB
Loading… -
scenes-and-backgrounds.md 6.5 KB
Loading… -
setup.md 19.5 KB
Loading… -
style-examples.md 4.5 KB
Loading… -
style-reference.md 7.2 KB
Loading… -
tileset.md 21 KB
Loading… -
uninstall.md 6 KB
Loading… -
update.md 4.2 KB
Loading… -
usage-reporting.md 10 KB
Loading… -
vfx-workbench.md 7.5 KB
Loading… -
vocal-animation.md 3.6 KB
Loading… -
weapon-anime.md 11.4 KB
Loading… -
weapon-axe.md 11.2 KB
Loading… -
weapon-bow.md 10.5 KB
Loading… -
weapon-dagger.md 8.1 KB
Loading… -
weapon-effects.md 17 KB
Loading… -
weapon-firearms.md 13.8 KB
Loading… -
weapon-futuristic.md 10.9 KB
Loading… -
weapon-katana.md 14.6 KB
Loading… -
weapon-mace.md 6.9 KB
Loading… -
weapon-spear.md 11.7 KB
Loading… -
weapon-staff.md 10.2 KB
Loading… -
weapon-sword-and-shield.md 9.6 KB
Loading… -
weapon-sword.md 12.4 KB
Loading… -
weapon-war-hammer.md 8.5 KB
Loading… -
weapon-whip.md 3.4 KB
Loading…
-
-
LICENSE.md 1.2 KB
Loading… -
SKILL.md 61.5 KB
--- name: pixellab-pip description: Use when PixelLab (Pixel Lab) or Pip skill context is present for setup/auth (PIXELLAB_SECRET, bearer token), MCP/API routing, asset generation, endpoint choice, SDK integration, sprites, sprite sheets, characters, portrait characters, objects, tiles, tilesets, tilemaps, maps, Godot/Unity map export, icons/UI/fonts, backgrounds, palettes, image edits, animation/VFX, talking portraits, vocal animations, talking GIFs, lip sync, skeleton/template/preset animation, looping/seamless or multi-shot cinematics, project art styles, animation inspection/repair, blueprints/recipes and `*.blueprint.json` replay, Workbench, Aseprite/Pixelorama, Game Builder, docs/troubleshooting or generations/cost/credit budgets. Covers MCP, public REST v2, website/editor assistance and explicit legacy v1 integration. Also use for explicit skill setup, update, uninstall, auto, panel and bark (completion sound) commands. Do not trigger for Python pip/package management or generic image/pixel-art requests without PixelLab intent. license: MIT metadata: requires_api_key: "false" api_key_env: PIXELLAB_SECRET api_key_note: "Optional. Guidance, setup, routing, and docs need no key. Live PixelLab generation needs a bearer token, configured in the MCP client or as PIXELLAB_SECRET for REST v2 fallback; the skill uses it only as an auth header and never reads, prints, or stores its value." permissions: # local helpers read/write outputs and config; fetch.py uses only documented PixelLab download/file hosts - env - shell - file_read - file_write - network --- # PixelLab Pip Classify the request, choose the supported PixelLab surface, then act. Answer questions directly when the request is a question. ## Workflow 1. Classify intent; values combine, such as `animate + cost_sensitive`: `question | setup | update | uninstall | bark | auto | panel | create asset | edit/transform | animate | pixelart_workbench | prompt_enhancement | cost_sensitive | integrate/code | check balance/status | troubleshoot docs/API | website/editor assistance | game_builder | aseprite_integration | blueprint/recipe`. A standalone command word after an explicit skill invocation, such as `/pixellab-pip setup` or `@pixellab-pip bark off`, is that intent: for setup read `references/setup.md`, for update read `references/update.md`, for uninstall read `references/uninstall.md`, for bark read `references/bark.md`, for auto read `references/auto.md`, for panel read `references/panel.md`. 2. Classify the target: `general_image | skill_icon | item_icon | background | character | portrait_character | font | object | effect_vfx | ui | whole_map | map_image | map_object | top_down_tileset | sidescroller_tileset | multi_shape_tileset | path_tiles | building_kit | isometric_tile | tile_variants | animation | existing_image`. Fitted visual additions to an existing character image, such as hair, facial features, wearables, accessories, or held gear, are `existing_image` paperdoll edits, not standalone `object` requests, unless the user explicitly wants a separate unattached prop. 3. Choose the surface with Surface Rules, then the route with the Intent Router. When the user explicitly asks for Aseprite handling, read `references/aseprite-cli.md`; PixelLab MCP/REST generates, documented Aseprite CLI/Lua handles local workspace, import/export, packaging, and launch only. 4. Use MCP only if PixelLab MCP tools are visible as callable tools, bare or prefixed such as `mcp__pixellab__create_character` (match by suffix). If the user explicitly asked for MCP, do not silently fall back; report that MCP is unavailable and offer setup or an approved REST v2 fallback. Otherwise, when MCP is unavailable, use the matching documented REST v2 endpoint. If both are unavailable or fail, explain why before any non-PixelLab fallback. 5. Before repeated paid prompt-only retries, inspect the chosen tool or endpoint schema for generation controls such as guidance, adherence/strength, reference images, palette images, or style options, and use the ones that target the failure mode. Before the first paid call to any endpoint that consumes a supplied input image, inspect its schema and embed the source image in the correct field — never send such a request without its input image. Refresh official docs only when a needed tool, endpoint, field, auth, SDK, pricing, or model/mode fact is missing or unclear (see Current Docs Refresh). 6. Before already-routed generation, check only the selected project root for `pixellab-pip-style.json`; when present read `references/project-style.md` for the effective style, temporary overrides and legacy restrictions. No profile means ordinary one-off work without forced setup. For consistency-sensitive work, summarize the user's identity, style, palette, view, and reference anchors. Ask up to three blocking questions before a credit-spending call. 7. Prepare natural-language parameters per Text Preparation. For non-English or mixed-language requests, read `references/localization.md`. 8. For animation, preserve the user's requested frame count; otherwise use the endpoint or template default. Read `references/animation.md` for generated-versus-returned counts and input-echo verification before quoting or validating a count. Exception: preset/template character animations take no `frame_count`; pick a matching template id such as `walking-8-frames` (catalog in `references/preset-skeleton-template-animation.md`) or use custom animation per that reference. Preserve PixelLab's returned frame order; no ping-pong, reversed, duplicated, or trimmed outputs unless the user asks for that playback style. 9. If the user says cheap, budget, low-cost, fewer credits, or similar, read `references/cost-routing.md` before choosing a paid route, and ask before each extra paid attempt unless the run's approved retry allowance in `references/auto.md` → Bounded plans and resuming covers it. 10. Before live generation, confirm the PixelLab bearer token is configured (see Auth And Execution). 11. `seed`: omit by default; PixelLab randomizes it. Send it only when the selected schema exposes it, in three cases — the user gave a seed (send verbatim), a candidate batch whose blueprint sets distinct seeds (send them as written), or two or more calls share near-identical wording and should attempt to hold the same composition (seed-lock, not a guarantee): generate one random positive integer (`0` means random, so never 0) and send that same value on every call in the set. MCP `create_character` has no seed; use a reference image, or Pro-only `style_character_id`, for look consistency and do not promise reproducibility. Do not ask for a seed. 12. Act or answer. Once the job's live generation(s) have returned image(s) — after the last one in a chain — do three follow-ups before the final report, even if the user did not ask: the completion sound (`references/bark.md`), the manifest (`references/usage-reporting.md`), and the `*.blueprint.json` (`references/blueprint.md`). Then send one final report. Ask a short clarification only for known collisions. Before that report, send only a blocker, a question you need answered, the approval or auto-on card, or a needed resume clarification — never progress, status, findings, or intentions; those belong in the final report. For a pending job, keep polling its getter in-turn until its status is `completed` or `failed` — a still-running job is never a reason to end the turn (`references/job-lifecycle.md`). If the turn is being cut off before it finishes, continue with a bounded background wait instead of stopping. Hand the job back to the user only when you can do neither — no way to keep polling and no way to background a wait — then report the job or asset ID and the getter that resumes the check, and say credits were spent. Exception — chunk reveal: when an approved run produces several separately-completing image jobs (a multi-shot cinematic chain, an all-directions animation, an approved multi-asset batch), post each job's saved output — path and inline preview link — as that job completes, and fold the last job into the final report rather than revealing it twice. This covers distinct sequential jobs only, not the multiple images a single job returns at once (8-direction character, animation frames, rotations, tileset tiles, review candidates), which go straight to the final report. ## Asset Integrity - Every pixel of requested art must originate from PixelLab or the user. Local tools may read, download, assemble, package, import/export, preview, verify, mask, pad, crop, resize, and format-convert those pixels. Locally authored generation controls such as masks, palette swatches/`color_image`, reference guides, and shape templates are allowed as inputs; report them as inputs. Do not draw, repaint, or synthesize requested content locally unless the user explicitly approves a labeled non-PixelLab fallback. - Reviewable static candidates: when a static image-style MCP tool or REST endpoint returns multiple alternatives, read `references/reviewable-candidates.md` before selecting, saving, or continuing from one. - Do not bake a colored, checkerboard, white, black, green-screen, or matte background into transparent frames, final GIFs, spritesheets, previews, or report images unless the user explicitly asks for it. A checkerboard is allowed only as a clearly labeled inspection aid kept separate from final deliverables. - Post-process PixelLab output into a claimed final asset only with explicit approval. Local crop/split/format work that preserves original pixels is allowed when reported honestly; resizing, reassembling, compositing, or repairing failed outputs locally may be called final only after approval. Exception: when a request used `no_background: true` but the output kept a background, read `references/background-removal.md` and attempt safe removal when verification shows the background is removable without changing the art. - Save downloaded generations, derived previews, manifests, and packages in a named per-generation subfolder under the `pixellab-pip-generations/` folder at the user's project/workspace root — not loose in its root, and never resolved against a background or detached process's working directory, which may default to the home folder — unless the user names another location. A returned base64 image may be raw RGBA rather than PNG; confirm a saved image decodes to a valid PNG, and when a response exposes more than one image field, save the PNG-encoded one. Produce only the requested output formats or the route's minimal standard artifacts. When a job returns multiple separate images, always compile one standard preview alongside the individual files: a spritesheet for a collection of distinct sprites, or a looping preview GIF when the images are frames of a single animation (read `references/local-asset-assembly.md` for spritesheet grids and GIF settings). No APNG or extra preview/viewer formats unless asked. - After a generation returns image(s), write a `<name>.blueprint.json` beside the outputs per `references/blueprint.md` — canonical portable `_pixellab` connection metadata, the exact route bodies, structured `TASK` steps for material work performed outside PixelLab calls, and a `_comment_prompt` holding the user's original prompt as they intended it. Remove host-added wrappers such as connector Markdown, app URIs, hidden local paths, or tool-call serialization; keep the visible command text, such as `/pixellab-pip`. When the generation used one or more user-supplied input images (any role — source, reference, style, mask, init, frame, and the like), copy each into the folder by copying the file, not by reading and re-writing it. - After every live generation flow, write a manifest beside the outputs using `references/usage-reporting.md`; keep its private audit/resume data out of the shareable blueprint. ## Destructive Remote Actions Deleting, clearing, or overwriting existing remote PixelLab assets — characters, objects, tiles, tilesets, fonts, UI, portraits, effects, maps and the objects placed on them, their states, animations, or tags — in a way that discards or replaces content already stored remotely is irreversible and requires explicit user permission before it happens: either an instruction that names the deletion or overwrite, or the user's approval of a destructive change you propose. Creating a new asset, state, or animation is additive, not destructive, and is not gated here. Never delete or overwrite unilaterally as an inferred fix, cleanup, reset, sync, migration, or troubleshooting step, and never because a local list, cache, or app view looks empty, stale, or out of sync — the remote is the source of truth, so investigate read-only first (`list_*`/`get_*`, REST `GET`) and report what you find instead of destroying it. Proposing a destructive change is fine; carrying it out before the user approves is not. Before a confirmed destructive op, list exactly what will be removed or replaced (names/IDs and count); bulk or clear-all requires the user to confirm that scope. This covers the `delete_*` MCP tools, MCP `save_to_asset` when its target already exists, `remove_map_object`, terrain-erasing `edit_map` and tile-erasing `place_map_tiles` ops (preview them with `dry_run: true` first), REST `/vfx` calls with `effect_id` (saved over in place), and REST delete/replace endpoints. For character file synchronization, compare the returned `updated_at` value or URL `?t=` stamp with the local copy and download only changed assets; do not use a stale cached image as evidence that the remote needs replacement. ## Surface Rules | Surface | Use for | Avoid | |---|---|---| | Hosted MCP | Managed PixelLab assets with IDs, polling, downloads, list/get/delete helpers, Creator gallery browse/save-back (`list_images`, `save_to_asset`), animated VFX (`vfx_workbench`), talking-portrait/lip-sync tools, and map/project/sandbox/agent helpers, including `get_upload_url` for local-image uploads, `create_ui_asset`, `create_font`, or `create_portrait_character` when visible; also raw-image primitives `create_image_pixflux`/`create_image_pixen`/`create_image_pro`/`get_image`, `edit_image`, `edit_image_pixen`, `inpaint_image`, `animate_image`, `animate_image_pixminimax`, `animate_with_skeleton_v3`, `create_normal_map`, `transfer_outfit`, `image_to_pixelart`, `image_to_pixelart_pro_flash`, and the cleanup tools `unzoom_image`/`correct_pixelart`/`reduce_colors` when visible — these need no managed asset. PixelArt Workbench uses its own command workflow; read `references/pixelart-workbench.md` for supported inputs. Pro Flash image-to-pixel-art conversion is available alongside image, character, object, edit, and inpaint tools; read `references/pro-flash.md`. | REST-only controls such as multi-image style reference (`generate-with-style-v2`), freeform UI (`generate-ui-v2`), image-to-text, stateless lip sync, the older Pro image-to-pixel-art route, or packed spritesheet/ZIP export; resize and remove-background (no MCP tool); or any MCP call when PixelLab MCP tools are not visible. | | REST v2 | Scripts, batch jobs, server integrations, exact endpoint control, and REST-only capabilities such as multi-image style reference, freeform UI, base-tier edit/inpaint controls, one-pose skeleton estimation, legacy three-frame skeleton animation, image-to-text, and route-specific enhancement fields that the visible MCP tool lacks (see the Intent Router for exact routes) — plus any of the MCP-covered work below when MCP tools are not visible. | Guessing SDK methods instead of checking the installed SDK or current docs. | | Website / Map Workshop / Game Builder | Human product surfaces, the Creator queue, Game Builder (Tier 1+), full-map manual work, Godot/Unity map export, rich libraries, visible browser assistance. | Programmatic use of copied browser session tokens or undocumented internal endpoints used by first-party surfaces. | | Aseprite plugin | In-editor workflows when the user is actively working inside Aseprite. | Treating private first-party extension endpoints as public REST/MCP contracts. | | Aseprite CLI | Explicit Aseprite handling after PixelLab produced files: `.aseprite` workspaces, importing frames as layers/frames/tags, palette work, export/open via documented CLI/Lua. | Mouse/OCR UI automation or hidden control of the PixelLab Aseprite extension. | | Pixelorama / website editor | The PixelLab website editor is Pixelorama-powered; assist it only as visible browser automation after explicit permission, and ask again before login/session actions, spending credits, generations, downloads, edits, or deletes. | Hidden automation, undocumented endpoint calls, or any destructive action without a second confirmation. | | REST v1 | Existing legacy code and old SDK compatibility. | New work unless the user explicitly needs v1. | Hosted MCP tool names are not REST endpoints; do not curl MCP tool names as `/v2/...` paths. ## Intent Router For any atlas or spritesheet request with known or requested cell dimensions, also read `references/local-asset-assembly.md` for the required grid inspection preview. | User intent | Default route | REST v2 route for code/exact control | |---|---|---| | Explicit Pro Flash image, character, object, edit, inpaint, or image-to-pixel-art conversion; Pro Flash comparison | Read `references/pro-flash.md` for the separate tools, native-size and input rules, operation-specific costs, provisional cost checks, and verification. Do not silently replace a tested default with this unbenchmarked family. | `create-image-pro-flash`, `create-character-pro-flash`, `create-object-pro-flash`, `edit-image-pro-flash`, `inpaint-image-pro-flash`, `image-to-pixelart-pro-flash`; `GET /pro-flash/capabilities` and `/pro-flash/cost`. | | PixelLab experimental Create VFX page | Use the visible website page `https://www.pixellab.ai/create-vfx` only when the user specifically requests that page. MCP `vfx_workbench` is a separate agent-authored workbench; REST `POST /vfx` is documented as the page's own effects artist. | `POST /vfx`; read `references/vfx-workbench.md`. | | Managed/multidirection character, player, NPC, enemy, creature (default for general character requests) | MCP `create_character` with `mode="v3"` by default, then `create_character_state`, `animate_character`, `get_character`, `update_character_tags`, list/delete helpers. Read `references/animation.md` for animation engine selection; read `references/preset-skeleton-template-animation.md` when body plan or reference images matter. A character group's `name` is shared; when the user names a new state, pass `state_name`, otherwise PixelLab derives it from the edit description. For a follow-up animation on a multi-direction character, animate `south` first; ask before animating all directions. `outline` and outline wording in `description` are both ignored on v3 and Pro character generation; say so instead of spending credits tuning it. Neither the schema nor an echoed `get_character` value is evidence otherwise — only changed art is. Pixen/v3/new may underweight user instructions for shape, pose, or view. Offer Character Pro when it fits the request after disclosing its higher cost and different style; use it only if the user chooses it. `get_character` returns a download link, not a full ZIP bundle — use REST `GET /characters/{id}/zip` for the packaged archive, or `GET /characters/{id}/spritesheet` (object twin `GET /objects/{id}/spritesheet`) for one packed sheet plus a layout JSON. PixelLab sets the cell size, so a user-specified cell size still needs local assembly. | `create-character-v3`, `create-character-with-4-directions`, `create-character-with-8-directions`, `create-character-pro`, state/animation/tags/ZIP/list/get/delete endpoints. | | Explicit single still character sprite | Use the general-image row and read `references/characters.md` for candidate/identity checks. Use Pro Flash only when selected under `references/pro-flash.md`, not as an automatic upgrade. | The selected general-image route. | | Text-only quadruped character | Default to v3: ask for a south-facing reference and use `mode="v3"` with the matching template; v3 without a reference is humanoid-only. If the user requires text-only, explain that v3 does not support text-only quadrupeds and offer Pro Flash (`create_character_pro_flash` with the matching `template_id`; read `references/pro-flash.md`) or Pro only as opt-ins after disclosing their cost. Read `references/preset-skeleton-template-animation.md` for templates. | Default to `create-character-v3` with a matching quadruped `template_id` and reference. Offer `create-character-pro-flash` or `create-character-pro` only if the user explicitly chooses text-only after the cost is clear. | | Supplied character reference image to managed character | Use MCP `create_character(mode="v3")` with a finished south-facing sprite; supply `direction_images` for other views to preserve them. For loose concept art that should seed a Pro character's look without preserving pose or canvas, use `concept_image_url` or `concept_image_base64` only after the user chooses Pro. Read `references/image-input-roles.md` and `references/preset-skeleton-template-animation.md` for role and direction rules. | REST `create-character-v3` also supports matching quadruped `template_id` values; REST `create-character-pro` supports `method="create_from_concept"`; use the live schema for exact fields. | | Portrait-to-character or character-to-portrait | MCP `create_portrait_character` + `get_portrait_character` when visible. | `portrait-character-pro` (Pro image conversion). Supplied-image roles: `references/image-input-roles.md`. | | Talking portrait, mouth/viseme sprites, talking GIF, or lip-sync timing plan | Read `references/vocal-animation.md`. Use the MCP `set_character_portrait`, `create_vocal_animation` + `get_vocal_animation`, `create_talking_gif`, and `get_lip_sync` tools when visible. | `POST /characters/{character_id}/portrait`, `POST` + dedicated `GET /vocal-animation/{job_id}`, `POST /talking-gif`, and `POST /lip-sync`; REST is required for stateless lip sync. | | Pixel/bitmap font, font atlas | MCP `create_font` + `get_font` when visible. | `generate-font-pro` (Pro). | | Skill/ability/spell/action-bar/hotbar icon, inventory item/equipment/loot/pickup icon, emoji, or icon sheet | Read `references/icon.md` before choosing an endpoint or generating. | The reference covers route choice, background defaults, sheet sizing, prompt wording, and verification. | | Standalone object, prop, pickup, weapon, furniture (not an icon) | MCP `create_1_direction_object`, `create_8_direction_object`, object state/animation/tags/review tools. Pass MCP `name` when the user names a new object; it defaults to the description. An object's name is shared across directions and states; for a named new state pass `state_name`, otherwise PixelLab derives it from the edit description. Object creation is Pro Tools; candidate sheets and eight-direction objects use different prices (see `references/cost-routing.md`). | `create-1-direction-object`, `create-8-direction-object`, object state/animation/tags/list/get/delete endpoints. The REST create schemas have no `name` field; if the stored name matters and MCP is unavailable, tell the user before creation. | | Tileset or terrain transition with no stated type or projection; square top-down, Wang, or autotile tileset | Read `references/tileset.md`, then MCP `create_topdown_tileset`; this is the default when no tileset type, projection, or route is specified. | `create-tileset`, `tilesets`. | | Explicit hex, isometric, or oblique connectable terrain transition; or explicit `create_tiles_pro`/`create-tiles-pro` tileset mode | Read `references/tileset.md`, then MCP `create_tiles_pro` with `tile_feature="tileset"`. | `create-tiles-pro` with `tile_feature: "tileset"`, then `tiles-pro/{tile_id}`. | | Sidescroller/platformer tileset | Read `references/tileset.md`, then MCP `create_sidescroller_tileset`. | `create-tileset-sidescroller`. | | Isometric tile/block/floor | MCP `create_isometric_tile`; map thickness wording to `tile_shape` (`thin tile`, `thick tile`, `block` — same values as REST, default `block`). | `create-isometric-tile` with `isometric_tile_shape` (`thin tile`, `thick tile`, `block`). | | Multiple independent tile variants (hex, octagon, square, or isometric) | MCP `create_tiles_pro` with no `tile_feature`. | `create-tiles-pro`, `tiles-pro/{tile_id}`. | | Connectable path/road tile set | MCP `create_path_tiles`; shares `get_tiles_pro`/`list_tiles_pro`/`delete_tiles_pro` with `create_tiles_pro` — no dedicated getter. | `create-tiles-pro` with `tile_feature: "roads"`. | | Building kit (floor, connectable walls, doorways, pillar, stairs) | Read `references/tileset.md`, then MCP `create_building_kit`; shares `get_tiles_pro`/`list_tiles_pro`/`delete_tiles_pro` with `create_tiles_pro` — no dedicated getter. | `create-tiles-pro` with `tile_feature: "building"` and `building_*` fields. | | Hard-projection top-down/south-facing building sprite | Read `references/style-reference.md`; use MCP `create_image_pro` or REST `generate-with-style-v2`; apply the reference's verification. | Do not route a single sprite to `create_building_kit`. | | General image, sprite, standalone asset that is not an icon or emoji | MCP `create_image_pixflux`/`create_image_pixen`/`create_image_pro` + `get_image` when MCP-first — same model choice as REST, minus multi-image style reference (REST-only). For explicit Create Image Pro, `create_image_pro`/`generate-image-v2`, exact grids/sheets, or below-32px cells, read `references/create-image-pro.md` first. For full-body Pixen characters, read `references/pixen-character-prompt.md`. Model character: PixFlux = lower detail, loose/painterly (frames whole subjects); Pixen = high detail, tight framing; Pixen and Pro crop larger subjects; Pro for style/variety or closer adherence to the user's description. Pixen/v3/new has isometric bias and may underweight user instructions such as `view`/`direction`; prefer Pro for static south-facing when higher cost and different character style is acceptable. Pixen `no_background: true` allows up to 65,536 px of canvas area (e.g. 256×256 or 512×128); a larger canvas is refused with it on. | `create-image-pixen`, `generate-image-v2`, `create-image-pixflux`, `generate-with-style-v2`. | | Exact hex palette or color cap on a generated asset or animation | Read `references/create-image-pro.md` (Exact Palette Control) before choosing the route: many MCP (`palette`) and REST (`target_palette`) routes accept it, with surface and mode limits. | The selected route's `target_palette`; see the reference. | | Generate a normal map for a sprite or animation | Read `references/image-input-roles.md`; use MCP `create_normal_map` + `get_image` when visible, otherwise REST `POST /normal-map`. The 0.4.130 announcement also lists Creator availability, but does not document its UI flow. | `/normal-map` accepts a PNG sprite or an equal-frame horizontal strip; choose `convention="directx"` for Unreal, otherwise the default is OpenGL. | | Browse/search the Creator gallery, inspect or edit a gallery reference, or save generated/edited pixel art back into a character, object, animation direction, or gallery | MCP `list_images` for gallery metadata; pass its `gallery:<id>` reference to `get_image` to download or to `pixelart_workbench` for inspection/editing; use `save_to_asset` for save-back when visible; read `references/mcp-platform-tools.md` for target and destructive-save rules. | No public REST v2 equivalent is documented. | | Pixel-level repair or recipe drawing; inspect, measure, lint, compare, or animate source parts | For explicit pixel operations, read `references/pixelart-workbench.md` and use MCP `pixelart_workbench`. Keep open-ended image creation on the normal image-generation routes. | MCP-only `pixelart_workbench`; no public REST equivalent. | | PixelLab image description or visual Q&A | Use REST `POST /image-to-text` when the user wants PixelLab's read of an image: the default is a generic 1–3 sentence generation description; an optional prompt requests a custom visual answer. For improving existing text for a known generation route, use its matching enhancer instead; do not chain image-to-text before enhancement by default. Answer ordinary image questions directly when possible. | REST-only; returns text, not an image. | | Background, scene, backdrop | MCP `create_image_pixflux`/`create_image_pixen` (`no_background: false`) when MCP-first, else REST v2. Route by whether a subject is present: subject-less backdrop (empty landscape/sky/room, no figure) → PixFlux; full scene with a subject in an environment → Pixen. Do not use Pro `generate-image-v2`/`create_image_pro` here — its 10–25-generation size tiers are unnecessary for backdrops or scenes. | `create-image-pixflux-background` (same schema as `create-image-pixflux`, so `create_image_pixflux` covers it too); verify current size/field support before exact code. | | UI, HUD, button, panel, health bar, menu | MCP `create_ui_asset` + `get_ui_asset` when MCP-first — it has both `pieces` (rounded_rect/circle/polygon) and `elements` (button, icon_button, toolbar, tab, panel, window, health_bar, avatar, triangle/pentagon/hexagon/octagon); mind its aspect-gated size caps (square ≤512×512, 16:9 ≤688×384, 9:16 ≤384×688, 4:3 ≤600×448, 3:4 ≤448×600). Use REST v2 `create-ui-asset` (Pro) when MCP is unavailable. `generate-ui-v2` (REST-only, no MCP tool) for loose/raw UI images, especially with a `concept_image`. | Do not route shape-piece/layout requests to `generate-ui-v2`. | | Image edit, inpaint, mask, convert, resize, remove background | For supplied images read `references/image-input-roles.md`. MCP `edit_image` and `inpaint_image` are Pro routes with size-tiered costs (see `references/cost-routing.md`); prefer their URL inputs and use inline base64 only when needed. MCP `edit_image_pixen` is the cheap text-instruction edit (1 generation, source ≤256px per side, target area ≤256×256). For conversion, use MCP `image_to_pixelart` at a requested supported size; without an output-size request, the older REST-only Pro route detects native scale. Pro Flash is a separate six-generation MCP/REST option when requested (see `references/pro-flash.md`). The older Pro converter, base edit/inpaint weak-guidance controls, resize, and remove-background remain REST-only. | `inpaint`, `inpaint-v3` (Pro), `edit-image`, `edit-image-pixen`, `edit-images-v2`, `image-to-pixelart`, the older `image-to-pixelart-pro`, `image-to-pixelart-pro-flash`, `resize`, and **remove-background**. | | Fitted paperdoll addition on an existing character image | Treat as an `existing_image` edit anchored on the base frame; read `references/paperdolling.md` before choosing layer/composite outputs. | Do not use object generation for fitted layers unless the user explicitly wants an unattached prop. | | Set up, pick, change or save a project's art style, or match art the user shows | Read `references/project-style.md`; use `assets/project_style.py` when Python is available; optional `assets/analyze_style.py` supplies advisory measurements, not automatic art direction. | Applying any look the user did not choose. | | Style-reference or consistent-style generation | Read `references/style-reference.md`. Single style image or labelled references → MCP `create_image_pro` (preferred image URLs, plus `style_copy`) when MCP-first, else REST `generate-image-v2`. Multi-image style reference (`style_images` array, with optional `style_description`) is REST-only — no MCP tool has that shape. | `generate-with-style-v2` or `generate-image-v2` style/reference fields after checking current docs. | | Clean up pixel art, quantize/reduce colors, unzoom upscaled art | MCP `correct_pixelart`, `reduce_colors`, `unzoom_image` (0.1 generations each) + `get_image`, else REST v2. `correct_pixelart` and `reduce_colors` take a frame list — batch an animation's frames or a character's directions into one call so they stay consistent; `unzoom_image` is one image per call. | `correct-pixelart`, `reduce-colors`, `unzoom`. For file-level palette clamps on local copies, read `references/aseprite-cli.md`. | | Clean up or finish generated frames locally (stray pixels, flashes, floating poses, colour drift, trails, thrown props, baked effects) | Read `references/finishing.md`. | Local `assets/finish/` helpers; no PixelLab call. | | Editor-only utilities (Canny/Pose/Depth, reshape) | Read `references/editor-only-utilities.md`. | No public REST/MCP route exists for these; do not invent `/v2/...` routes. | | Try on garment/accessory | Website Try on (single composited image); for animation-frame outfit transfer use MCP `transfer_outfit` when visible, otherwise REST `transfer-outfit-v2`. | Try on and outfit transfer return composited imagery, not isolated paperdoll layers. | | Multi-image combine/edit | MCP `edit_image` (Pro; preferred `image_urls`, or inline base64, with optional reference URL/base64) when MCP-first, else REST v2 `edit-images-v2`; website/editor for visual experimental flows. | Aseprite's `generate-multi-edit` is an internal endpoint, not public REST. | | Prompt enhancement | Matching enhance endpoint or inline `enhance_prompt` per Text Preparation. | `enhance-pixen-prompt`, `enhance-character-v3-prompt`, `enhance-animation-v3-prompt` (`engine="v3"`, `"pixminimax"`, or `"skeleton-v3"`), or the inline `enhance_prompt` on `animate-pixminimax`. | | Explicit preset/template/built-in animation | Read `references/preset-skeleton-template-animation.md`; it covers managed templates and points to the Skeleton v3 and legacy raw routes. | Do not call website root `/generate-animation/background` or Aseprite extension internals. | | Explicit custom key poses/choreography, pinned pose stages, or an approved advanced attack recipe | Read `references/key-pose-animation.md` for this optional production method; ordinary attacks follow the raw/managed animation row. Use a padded canvas when needed, a selected supported edit route for reviewed key poses, then raw interpolation; Pro Flash pose editing is an explicit recipe choice. | Selected edit route, then `animate-with-text-v3` with `first_frame` + `last_frame`, or the otherwise selected raw-animation route. | | Check or fix animation frames (jumps, flicker, specks, wrong size, a weapon that vanished), or plan re-rolls of bad frames | Read `references/animation-doctor.md`, then inspect with `python <skill-dir>/assets/fix.py <frames> --check-only --out <dir>`; omit `--check-only` only for requested/accepted repairs (free, local; optional dependencies skip clearly). | Re-rolling the whole animation when only some frames failed. | | Skeleton v3, pose-keypoint animation, or auto-rig pipeline | Read `references/animation.md` → Route Choice for custom-vs-preset selection, then `references/preset-skeleton-template-animation.md` for managed MCP/REST custom motion, preset clips, raw keypoints, and auto-rig instructions. | `animate-character` / `characters/animations` for managed motion; `animate-with-skeleton-v3` for raw sequences. `estimate-skeleton` supplies only one pose; legacy `animate-with-skeleton` has a separate three-frame contract. | | Raw or managed text-driven animation, interpolation, outfit transfer, rotate | Read `references/animation.md` → Route Choice for the PixMiniMax default, explicit engine/template requests, count/cost exceptions, and managed-object limits. If MiniMax H3 is a strict provider requirement, use raw REST `POST /animate-pixminimax`; the managed provider is undisclosed. The same reference covers provider evidence, managed/raw differences, frame anchors, prompt adaptation, idle-loop risk, outfit-transfer inputs, and verification. For outfit transfer on animation frames, use MCP `transfer_outfit` when visible, otherwise REST `transfer-outfit-v2`. For 8-rotations-from-an-image, MCP only partially covers it by regenerating rather than rotating the exact input: `create_character(mode="v3", reference_image_base64=…)` for character/humanoid sprites, `create_8_direction_object(reference_image_base64=…)` for props. | Managed PixMiniMax: REST `/animate-character` or `/characters/animations`; raw animation: `animate-with-text-v3`, `animate-pixminimax`, `edit-animation-v2`, `interpolation-v2`, `transfer-outfit-v2`, `rotate`, `generate-8-rotations-v2/v3` (use the rotation route when exact input pixels must be preserved, not regenerated). No public 4-rotation route. For a start→end tween prefer the selected raw animation route; use `interpolation-v2` only on an explicit Pro/v2 request. | | Multi-shot, multi-second, or seamless-loop cinematic (a scene longer than one clip) | Read `references/cinematic.md`; requires a user-specified budget, a documented plan, and per-shot validation. Select the raw animation engine via `references/animation.md` → Route Choice, with preferred frame URLs or inline base64. | Selected raw route (`animate-pixminimax` or `animate-with-text-v3`) — one looped clip for cyclic motion, chained shots (each from the previous handoff frame) for evolving scenes, or `first_frame`+`last_frame` for a strict start→end tween. | | Furnished room with a floor plan and doorways, or room furniture cutouts | MCP `create_room`, `get_room`, and optional `cut_out_room_furniture`; read `references/scenes-and-backgrounds.md` for plan/tier/cost and view restrictions. Ordinary room background pictures use the Background row. | MCP-only; no public REST v2 room route. | | Map image / visual level concept | MCP `create_image_pixflux`/`create_image_pixen` + `get_image` when MCP-first (same subject-vs-subject-less split as the Background row), else REST v2 image/background route; website or Aseprite for map extension workflows. | No public map extension/texture surface is documented. | | Map object | MCP `create_map_object` + `get_map_object`, then `place_map_object` to put it on a map. | `POST /map-objects`, then `GET /map-objects/{object_id}` for status + metadata. | | Whole map, map CRUD, terrain tiles, or placing/moving/removing objects and characters on a map | MCP only: read `references/mcp-platform-tools.md` before `remove_map_object`; `placement_id` targets one placement, while `asset_id` removes every placement of that asset from the map. Use `create_map` (seeded from a top-down tileset, or from a tiles-pro/path/building tile group via `tile_group_id`), `edit_map` (`path`/`rect` terrain-tile ops), `place_map_tiles` (place, stack, or erase tile-group tiles on tile layers), `get_map`, `view_map`, `list_maps`, `delete_map`, and `place_map_object`/`move_map_object`/`remove_map_object`/`list_map_objects`. Otherwise use the visible website Map Workshop manually; use its Godot/Unity export when requested. | No public REST v2 map or map-export surface is documented; do not invent `/v2/maps...` routes. | | Game Builder or game-building project | For Tier 1+ users, use the visible Game Builder workflow. If compatible MCP project/chat/sandbox tools are visible, read `references/mcp-platform-tools.md` before using them and pass `project_id` only for the requested project context. | No public REST v2 Game Builder endpoint is documented; do not invent one. | | Static effect/VFX sprite | If a target image is supplied and the user asks to add an effect to it, MCP `edit_image` (pro) when MCP-first, else REST image edit, on that target; otherwise default isolated reusable VFX to Create Image Pro (`create_image_pro`/`generate-image-v2`) and read `references/create-image-pro.md`. | Pro is the reliable effects/variety route found in focused testing; Pixen is retry-heavy and unreliable for effect-only assets. Edit routes return a whole edited image, not an isolated effect layer; no static VFX endpoint is documented. `vfx_workbench` is for animated effects. | | Animated effect/VFX | Use MCP `vfx_workbench` when visible; use REST `POST /vfx` when it is not, for code or batch integrations, or when the user wants PixelLab's own effects artist. Read `references/vfx-workbench.md` for both. For free-form motion on a supplied raw image without effect-part or anchor controls, or a managed object animation, select the route via `references/animation.md` → Route Choice. | Effects artist: `POST /vfx`. Raw animation uses `animate-pixminimax`, `animate-with-text-v3`, `animate-with-skeleton-v3`, or legacy `animate-with-skeleton`; managed object animation uses the object animation endpoints. | | Balance, credits, account check | MCP `get_balance` if available. | `GET /balance`. | | REST async job status or cancellation | Poll `GET /background-jobs/{job_id}`; while processing, `last_response.queue_position` and `last_response.estimated_wait_seconds` expose queue information. Use HTTP **DELETE** on `/background-jobs/{job_id}` only when the user explicitly approves cancellation; read `references/job-lifecycle.md`. Vocal animation is the exception and uses `GET /vocal-animation/{job_id}`. | MCP managed assets use resource-specific `get_*` tools instead. | | PixelLab projects, sandbox, chat, deployed agents, job control, MCP help/knowledge/feedback | Read `references/mcp-platform-tools.md` before using `list_projects`, `add_to_project`, `remove_from_project`, `sandbox_*`, `chat_*`, `agent_*`, `search_knowledge`, `list_jobs`, `wait_for_jobs`, or `cancel_job`. | No public REST v2 equivalent is documented for the platform helpers, active-job list, or all-job wait; REST cancellation uses HTTP **DELETE** on `/background-jobs/{job_id}`. | | Discover, inspect, select, or replay blueprints/recipes, including a supplied `*.blueprint.json` | Read `references/blueprint.md`. For actual replay follow its discovery/selection/replay contract. When a blueprint is only a look or identity source for a different requested asset, route that new asset normally and classify its identifiable existing output images with `references/image-input-roles.md`; do not replay merely to obtain missing references. Recorded route/size/seed/mode do not become defaults for the new asset. A blueprint name that contains an asset word (e.g. "knight") is still blueprint intent when the conversation identifies it as one. | Actual replay uses the exact recorded route (`MCP <tool>` or `POST /v2/...`); reference-only use follows the new asset route. | ## Clarify Only For Collisions - "Presets": infer bundled blueprints from established blueprint context and preset/template animations from animation or motion context; ask which collection only when neither is clear. - "Tiles": top-down/autotile tileset, platformer tileset, explicit-projection connectable set, independent variants, one isometric tile, path set, building kit, or packed texture sheet? - "Map": tile-based map (MCP map tools), map object, flat map image, tileset, isometric tile, or tile variants? - "Isometric tileset": one tile, independent variants, or a connectable terrain set? Ask when unclear; only the connectable set uses `tile_feature="tileset"`. - "Object/character": infer character for people, NPCs, creatures, or identity/state animation; object for standalone props, pickups, furniture, weapons. Ask only if unclear. - Animation direction on a multi-direction character: default to `south` for one preview candidate; ask only when `south` is unavailable, directions are unknown, or the user needs another gameplay-facing direction. Animate all directions only on explicit request or approval. - "Effect": static or animated? If a target image is supplied, infer a one-off edit; ask reusable-asset vs one-off only without a clear edit target. - "Paperdoll": gather base image, desired layers, target regions, directions, and whether the user wants separate transparent layer files, editor layers, composited previews, or both; see `references/paperdolling.md`. - Supplied images: infer each file's low-risk endpoint-specific role from wording. Before credit-spending calls, ask when role uncertainty (identity vs style vs concept vs edit target vs mask vs palette vs first/last frame) would change the endpoint or output; see `references/image-input-roles.md`. - If prompt enhancement adds material inferred details, surface the proposed description in the cost-approval gate (`references/auto.md`) before a credit-spending call. ## References Resolve every `references/` path against this skill's own directory (the parent of this `SKILL.md`) and use an absolute path in the tool call. If that directory is unknown to you, find the `pixellab-pip/references/` folder by listing or searching the workspace and agent-skill directories before acting; do not skip the read. When a rule names a reference, open and read it before acting, then follow its current text — not memory or a summary. Your training does not contain these PixelLab-specific contracts, so answering from general knowledge — for example treating Pip as a `pip`-installed Python package — will be wrong. If a required reference cannot be read, say so and stop rather than improvise its contract. Read each reference only when its trigger applies: - Bearer-token setup, PixelLab UI naming, MCP auth reuse: `references/credentials.md`. - Setup wizard for MCP, REST v2 fallback, auth after install: `references/setup.md`. - Update an installed Pip to the latest version: `references/update.md`. - Remove an installed Pip: `references/uninstall.md`. - Persistent completion sound toggle: `references/bark.md`. - Cost-approval gate before paid calls, the `auto` on/off toggle and explicitly bounded run budgets/retries: `references/auto.md`. - Interactive project/output review and `/pixellab-pip panel`: `references/panel.md`. - Safe post-processing when `no_background: true` fails: `references/background-removal.md`. - Skill/ability and inventory item icon sheets: `references/icon.md`. - Create Image Pro, exact hex palettes or color caps on any route, native-size multi-output batches, exact grids, below-32px cells: `references/create-image-pro.md`. - Explicit Pro Flash image/character/object/edit/inpaint/pixel-conversion or comparison: `references/pro-flash.md`. - Cheap/budget/credit-minimizing route selection: `references/cost-routing.md`. - Paperdolling and layered characters: `references/paperdolling.md`. - Review/choice handling for static candidate alternatives: `references/reviewable-candidates.md`. - Animated effects through MCP `vfx_workbench` or REST `/vfx`: `references/vfx-workbench.md`. - Tilesets and tile variants: `references/tileset.md`. - Project art styles kept across assets (`pixellab-pip-style.json`; the user always chooses the style, named examples offered): `references/project-style.md`, `references/style-examples.md`. - Still character sprites (hero, NPC, monster, boss): route, description, candidates, the look checklist at 3x, colour variants, adding a prop: `references/characters.md`. - Battle/level backgrounds, hub backdrops, story pictures, region maps, building sprites and upgrade tiers: `references/scenes-and-backgrounds.md`. - Normal maps for sprites or animations (input packing, clip splitting, lit preview, engine wiring): `references/normal-maps.md`. - A character move in 8 facings for top-down or 3/4 games: `references/eight-direction.md`. - Style-reference generation, Aseprite-equivalent square padding, and output sizing: `references/style-reference.md`. - Supplied image roles, endpoint image fields, fixed-size image-to-pixelart: `references/image-input-roles.md`. - Pixel-level drawing, repair, inspection, comparison, and recipe animation: `references/pixelart-workbench.md`. - Non-English or mixed-language requests: `references/localization.md`. - Official PixelLab doc URLs and boundaries: `references/official-pixellab-documentation.md`. - Generation reports and manifests after PixelLab calls: `references/usage-reporting.md`. - Per-generation blueprint (PixelLab calls + agent tasks), recreation, and sharing: `references/blueprint.md`. - Async jobs, MCP review state, rate limits, download expiry, tools refused by the user's plan: `references/job-lifecycle.md`. - Preset/template/skeleton character animations: `references/preset-skeleton-template-animation.md`. - Raw animation, interpolation, outfit transfer, idle-loop risk: `references/animation.md`. - Weapon, fighting, armour/cloth and weapon-effect motion (visible pose wording, key poses, frame rhythm, pitfalls): `references/weapon-<name>.md`, where `<name>` is `sword`, `katana`, `dagger`, `staff`, `bow`, `mace`, `spear`, `axe`, `sword-and-shield`, `war-hammer`, `whip`, `firearms` (pistols, rifles, shotguns), `futuristic` (arm cannons, energy blades), `anime` (giant swords, scythes, kunai, chibi) or `effects`; plus `references/martial-arts.md` and `references/armor-clothing.md`. Read only the page for the weapon or effect at hand. - Talking portraits, viseme generation, talking GIFs, and lip-sync plans: `references/vocal-animation.md`. - Multi-shot, multi-second, or seamless-loop cinematics from chained animations: `references/cinematic.md`. - Editor-only utilities without public routes: `references/editor-only-utilities.md`. - PixelLab project/sandbox/chat/agent MCP tools: `references/mcp-platform-tools.md`. - REST v2 prompt/field character limits: `references/prompt-limits.md`. - Explicit Aseprite handling, `.aseprite` workspaces, palette quantization, CLI/Lua export: `references/aseprite-cli.md`. - Third-party Aseprite MCP servers: `references/aseprite-mcp.md`. - Before any bundled image helper: dependency/skip requirements, decoded-image checks, atlas/spritesheet grid previews, local assembly, GIFs and ImageMagick: `references/local-asset-assembly.md`. Optional broader docs: in full plugin/repo installs these resolve relative to this `SKILL.md`; raw skill installs may omit them. Read at most one matching file if runtime references are not enough; if absent, continue with `references/official-pixellab-documentation.md` and current official docs. - Surface boundaries and service selection: `../../docs/pixellab/pixellab-surfaces-and-services.md`. - Plain-language asset routing: `../../docs/pixellab/pixellab-asset-routing.md`. - Product/model/mode terminology: `../../docs/pixellab/pixellab-terminology.md`. - SDK-vs-REST compatibility: `../../docs/pixellab/pixellab-sdk-compatibility.md`. - Bearer-token, session, and security boundaries: `../../docs/pixellab/pixellab-auth-and-security.md`. - UI generation and MCP-vs-REST UI routing research: `../../docs/pixellab/pixellab-ui-generation-surfaces-research.md`. - Multi-shot cinematic technique research (chained-animation findings): `../../docs/pixellab/pixellab-cinematic-spike.md`. - Cinematic scene composition and motion technique (inspiration): `../../docs/pixellab/pixellab-cinematic-inspiration.md`. ## Model And Mode Terms Treat PixelLab model/provider language as product labels unless official docs disclose more. Do not invent provider internals where docs are silent. - `Pixen`, `PixFlux`: product/workflow labels, not guaranteed provider names. - `PixMiniMax`: PixelLab's label for raw-frame animation and managed-character mode; provider attribution varies by surface. See `references/animation.md` for the public evidence and route details. - `PixPatch`: website-surface label; no public v2 `PixPatch` endpoint exists. - `Pro`: a quality/tier label across many unrelated tools, not one endpoint or model. Treat Pro and Pro Tools routes as expensive unless current docs prove otherwise. - `Pro Flash`: a separate beta image/character/object/edit/inpaint/pixel-conversion family, not a faster alias for existing Pro routes. Read `references/pro-flash.md` for size-based prices, rotation charges, and the REST/MCP pricing discrepancy. - `v3` and `new`: workflow/version labels scoped to a selected operation. Cheap-family hints, but check the endpoint — REST `inpaint-v3` is documented as Pro. - `standard`: character `standard` is deprecated for Pip routing; do not recommend it. The separate `standard` mode on top-down tilesets is a different workflow — read `references/tileset.md` for its routing. - `S-XL`, `M-XL`, `S-M`, `M-L`: size/product labels, not asset intents. - `Gemini`: retired label, absent from current REST v2 and MCP docs. Do not present it as a current tier or provider. ## Text Preparation Exact field values win over prompt prep. If the user explicitly supplies a PixelLab-facing field value, such as `prompt: ...`, `description: ...`, `action: ...`, or `use exactly ...`, send that value unchanged and do not enhance it. If it is invalid, over limit, or unsafe, stop and ask for an approved replacement or trim before spending credits. Prompt enhancement is opt-out. Otherwise, for natural-language parameters such as `description`, `style_description`, `negative_description`, `*_description`, `action`, `item_descriptions`, `text`, and `color_palette`, produce the best concise PixelLab-ready English value from the request and visible inputs before calling a tool. For non-English or mixed-language requests, load `references/localization.md` and obtain the user's approval for the exact English transformation before the first external call. Exception: `/talking-gif.text`, `/lip-sync.text`, and their MCP `text_to_speak` fields are dialogue content; preserve the user's wording exactly and do not enhance or translate it. Prompts describe visual content or, for action fields, depicted motion — never tool operation, output metadata, or report status. Include only details that change output; omit boilerplate already expressed by a supported control. Prefer supported controls and positive structural wording. Use inline exclusions only for a specific visual constraint, not generic boilerplate; no separate field is required. On Pixen, describe the intended empty or replacement state instead of naming an otherwise absent object only to exclude it. Send `negative_description` only when the live schema exposes it. For a named visual style, state it briefly and avoid conflicting render adjectives; use route-specific references for additional style guidance. Respect documented character limits: many REST v2 description fields allow 2000 characters, but several action/edit/style fields cap at 500. On a length rejection, trim without changing intent, note the adjustment, and retry. Exact limits: `references/prompt-limits.md` or OpenAPI. Use one enhancement path per call. Inline `enhance_prompt` flags exist on `create-image-pixen`, `animate-with-text-v3`, `animate-pixminimax`, `create-character-v3`, `animate-character`/`characters/animations`, and object animations, cost about 0.05 generations, and are preferred over a separate enhancer call when the route has one. Constraints: for character/object animation, `enhance_prompt` is valid only with `mode="v3"`; for `create-character-v3` it is valid only for from-scratch generation; on `animate-pixminimax`, `enhance_prompt` rewrites the motion-only action caption, while `direction` is a separate facing caption field and may be used with or without enhancement. The current PixMiniMax schema also exposes optional `subject_description`, `initial_pose`, and `view` caption fields; omit them only when image inference is acceptable. These fields are surface-specific: MCP `animate_image_pixminimax` exposes `enhance_prompt`, `direction`, `subject_description`, `initial_pose`, and `view` but not REST's `drift_threshold`; `create_image_pixen`, `animate_image`, and `create_character` expose no `enhance_prompt`, so on those MCP-first routes enhance directly as the agent instead. Standalone enhancers: `enhance-pixen-prompt` for Pixen image prompts, `enhance-animation-v3-prompt` for animation actions (`engine="v3"`, `"pixminimax"`, or `"skeleton-v3"`), and `enhance-character-v3-prompt` for character-v3 prompts. Otherwise enhance directly as the agent; do not force a mismatched enhancer. ## Do Not Use - No local code or editor automation to create or alter requested visual content: no PIL/Pillow drawing, canvas/SVG drawing, ImageMagick draw, Aseprite Lua drawing, ASCII-to-image, or procedural pixel placement. Local code may copy, mask, composite, and verify pixels that came from PixelLab or the user. - No undocumented internal endpoints used by first-party surfaces: root website routes, unversioned `api.pixellab.ai` paths like `/tilesets/create`, or Aseprite extension operation URLs. Treat them as unsupported unless they appear in public REST v2 docs/OpenAPI or MCP docs. - Never ask for the PixelLab bearer token in chat; direct users to the setup wizard, local `PIXELLAB_SECRET`, or app secret settings. If a token appears in chat or tool output, do not repeat or use it; tell the user to treat it as exposed and replace it before continuing. - Never scrape browser session tokens or cookies. Website session tokens are not API bearer tokens; never use one for the other. - Do not default to v1 or old SDK README examples for new work, and do not assume an installed SDK covers every current v2 endpoint — confirm the installed package or call REST v2 directly. ## Current Docs Refresh Route from this skill first. Refresh official docs only when a needed tool, endpoint, field, schema, SDK detail, auth step, price/limit, or model/mode claim is missing or unclear. Start lightweight (REST v2 `llms.txt`, MCP docs); fetch `openapi.json` only for exact schemas, reading a field's existence, type, or default from the raw JSON, not a prose summary. Links and their limits: `references/official-pixellab-documentation.md`. If web access is unavailable, answer from this skill and say which current claim could not be freshly verified. ## Auth And Execution If no bearer token is configured, stop before generation and offer the setup wizard: the user opens `https://www.pixellab.ai/account` after signing in, copies the value labeled `Secret`, and stores it locally as `PIXELLAB_SECRET` or in app secret settings — never pasted into chat. For Manual setup, link `https://www.pixellab.ai/mcp` and stop. PixelLab UI/docs may call this value an API key, API token, or secret; for REST/MCP bearer auth, call it a bearer token. A Python launcher that fails before Python starts does not mean Python is missing: on Windows, try each `where.exe python3` and `where.exe python` result and use the first that passes `--version`. Never install Python. When a helper skips with exit 3 for a missing or outdated package, report the step as not done and name that package from the skip reason; install packages only when the user asks. For questions, answer with: recommended surface/endpoint, why it fits, warnings for unsupported alternatives, and a verification note only when the answer depends on an unverified current fact. For tasks, generate only when the user clearly requested it and token plus tooling are configured. For nontrivial work, produce one candidate first, report it, and continue only if asked. Before the first credit-spending call, apply the cost-approval gate in `references/auto.md`: unless Auto is on, plan the whole paid chain, then in one message show every predicted paid call, its material inputs (including the exact prompt text), and a rough total for approval; also apply current-run constraints. For destructive remote actions, follow Destructive Remote Actions. Refuse unsupported automation and reroute to the closest documented MCP/REST option or a visible manual website flow. Locally authored non-PixelLab visual content requires explicit request or approval and a non-PixelLab-fallback label. Capture a balance snapshot before a nontrivial paid call when available. After live PixelLab work, read `references/usag
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.