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 questions across MCP, REST v2/API, website/editor Pixelorama, Aseprite, and legacy v1. Trigger only when PixelLab (Pixel Lab) context is present, including PixelLab setup, MCP/API setup, PIXELLAB_SECRET, bearer-token auth, PixelLab sprites, sprite sheets, characters, portrait characters, vocal animations, talking GIFs, lip-sync plans, fonts, objects, tiles, tilesets, tilemaps, maps, UI, icons, backgrounds, palettes, image edits, animations, skeletons, template animations, preset animations, cinematics, looping or seamless-loop scenes, multi-shot scenes, endpoint choice, SDK integration, blueprints/recipes, recreating/replaying *.blueprint.json generations, troubleshooting, or PixelLab credits/cost/budget. Do not trigger for unrelated Python pip/package-manager requests or generic image/pixel-art requests with no PixelLab intent.

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 | create asset | edit/transform | animate | prompt_enhancement | cost_sensitive | integrate/code | check balance/status | troubleshoot docs/API | website/editor assistance | aseprite_integration | blueprint/recipe. A standalone setup, update, uninstall, bark, or auto 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.
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. 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. 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 fall back to v3 custom mode. 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 a concrete budget or attempt count was approved.
10. Before live generation, confirm the PixelLab bearer token is configured without asking the user to paste it into chat (see Auth And Execution).
11. seed: omit by default; PixelLab randomizes it. Send it in two cases only — the user gave a seed (send verbatim), or two or more calls share near-identical wording and must land on the same composition (seed-lock): generate one random positive integer (0 means random, so never 0) and send that same value on every call in the set. Never ask the user 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 or a question you need answered — 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.
• Do not post-process PixelLab output into a claimed final asset without explicit approval. Local crop/split/format work that preserves original pixels is allowed when reported honestly; resizing, reassembling, compositing, or repairing failed outputs locally must not be called final without 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, 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 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, talking-portrait/lip-sync tools, and project/sandbox/agent helpers, including 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, inpaint_image, animate_image when visible — these need no managed asset.	REST-only controls such as UI-asset style_image/project_id, multi-image style reference (generate-with-style-v2), or stateless lip sync; convert-to-pixel-art, resize, 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, skeleton animation, and prompt enhancement (see the Intent Router for exact routes) — plus any of the MCP-covered work below when MCP tools are not visible.	Guessing SDK methods without checking the installed SDK or current docs.
Website / Map Workshop	Human product surface, full-map manual work, 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
Character, player, NPC, enemy, creature	MCP create_character with mode="v3" by default, then create_character_state, animate_character, get_character, update_character_tags, list/delete helpers. 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; Character Pro follows the user's description more closely when higher cost and a different style are acceptable. get_character returns a download link, not a full ZIP bundle — use REST GET /characters/{id}/zip when the user needs the packaged archive.	create-character-v3, create-character-with-4-directions, create-character-with-8-directions, create-character-pro, state/animation/tags/ZIP/list/get/delete endpoints.
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. An object group's name is shared; when the user names a new state, pass state_name, otherwise PixelLab derives it from the edit description. Object creation is Pro Tools (20-40 generations).	create-1-direction-object, create-8-direction-object, object state/animation/tags/list/get/delete endpoints.
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.	create-image-pixen, generate-image-v2, create-image-pixflux, generate-with-style-v2.
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 — not worth its ~12× cost 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). REST v2 create-ui-asset (Pro) only when style_image or project_id is needed, or 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; prefer their URL inputs and use inline base64 only when needed. Use REST for cheaper base edit/inpaint or extra weak-guidance controls. Convert/resize/remove-background have no MCP tool; use REST v2.	inpaint, inpaint-v3 (Pro), edit-image, edit-images-v2, image-to-pixelart, image-to-pixelart-pro, resize, 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.
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.
Editor-only utilities (Canny/Pose/Depth, reduce colors, unzoom, pixel correction, reshape)	Read references/editor-only-utilities.md. For file-level palette quantization/reduction/replacement, read references/aseprite-cli.md even without explicit Aseprite wording.	No public REST/MCP route exists for these; do not invent /v2/... routes.
Try on garment/accessory	Website Try on (single composited image); REST transfer-outfit-v2 only for animation-frame outfit transfer.	Try on does not return 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.
Preset/template/built-in animation, named motion, or custom skeleton/keypoints	Read references/preset-skeleton-template-animation.md; it splits MCP managed-template vs REST raw-skeleton routes.	Do not call website root /generate-animation/background or Aseprite extension internals.
Auto-rig, estimate skeleton, animate from keypoints	Read references/preset-skeleton-template-animation.md.	estimate-skeleton, then animate-with-skeleton.
Raw non-skeleton animation, interpolation, outfit transfer, rotate	MCP animate_image animates any supplied image directly — preferred frame URLs or inline base64 plus action, with an optional last frame for a tween — no managed character/object needed. 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. Otherwise REST v2. Read references/animation.md for frame anchors, idle-loop risk, and verification.	animate-with-text-v3, edit-animation-v2, interpolation-v2, transfer-outfit-v2, rotate, generate-8-rotations-v2/v3 (use this when the exact input pixels must be preserved, not regenerated). No public 4-rotation route. For a start→end tween prefer animate-with-text-v3; 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. MCP animate_image with preferred frame URLs or inline base64 when MCP-first, else REST.	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.
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 CRUD/extension/texture surface is documented.
Map object	MCP create_map_object + get_map_object; download promptly — MCP map objects auto-delete after 8 hours.	POST /map-objects, then GET /map-objects/{object_id} for status + metadata.
Whole map, Map Workshop, map CRUD/export	Website manually, or generate components via MCP/REST.	No public map CRUD surface is documented.
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 standalone VFX endpoint exists.
Animated effect/VFX	MCP animate_image for a raw (non-managed) image, REST v2 raw animation, or MCP object animation for a managed object.	animate-with-text-v3, animate-with-skeleton, or object animation endpoints; VFX is a description, not an endpoint.
Balance, credits, account check	MCP get_balance if available.	GET /balance.
REST async job status	Usually GET /background-jobs/{job_id}; 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, MCP help/feedback	Read references/mcp-platform-tools.md before using list_projects, sandbox_*, chat_*, or agent_* tools.	No public REST v2 equivalent is documented.
Discover, inspect, select, or replay blueprints/recipes, including a supplied *.blueprint.json	Read references/blueprint.md and follow its discovery, selection, and replay contract. A blueprint name that contains an asset word (e.g. "knight") is still blueprint intent when the conversation identifies it as one.	The exact route recorded in the blueprint (MCP <tool> or POST /v2/...).

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": whole map, map object, 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, and the auto on/off toggle: references/auto.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, native-size multi-output batches, exact grids, below-32px cells: references/create-image-pro.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.
• Tilesets and tile variants: references/tileset.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.
• 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: 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.
• 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.
• Atlas/spritesheet grid inspection previews, local assembly, preview 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.
• 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.
• 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: a legacy generation mode, not a quality tier (the standard/pro split on characters, tilesets). Use it only when the user explicitly asks or a route reference directs it.
• S-XL, M-XL, S-M, M-L: size/product labels, not asset intents.
• Gemini: a cost-tier label in current edit/inpaint schemas; its older website Create Tileset Pro usage is stale and must not be presented as current.

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, 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. These are REST-only fields — the matching MCP tools (create_image_pixen, animate_image, create_character) expose no enhance_prompt; on an MCP-first route, enhance directly as the agent instead. Standalone enhancers: enhance-pixen-prompt for Pixen image prompts, enhance-animation-v3-prompt for animation v3 actions, 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 https://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 users to paste the PixelLab bearer token into chat; direct them to the setup wizard, local PIXELLAB_SECRET, or app secret settings.
• 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; fetch openapi.json only for exact schemas.

• https://api.pixellab.ai/v2/llms.txt — REST v2 endpoint index and auth summary
• https://api.pixellab.ai/v2/docs — interactive REST v2 parameters
• https://api.pixellab.ai/v2/openapi.json — exact schema checks only; read a field's existence, type, or default from the raw JSON, not a prose summary
• https://api.pixellab.ai/mcp/docs — MCP tool behavior
• https://www.pixellab.ai/mcp — MCP setup
• https://github.com/pixellab-code — official SDK/MCP repo state only
• https://api.pixellab.ai/v1/openapi.json — legacy checks only

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.

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 the persistent auto setting 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. 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/usage-reporting.md and use its report layout; verify the output against the user's explicit constraints before calling it final, and say plainly when verification failed instead of silently salvaging. Do not paste secrets, raw base64, full response JSON, or internal IDs unless needed for pending status, follow-up, or debugging.

When a live generation, edit, transform, conversion, background-removal, or animation job returns image(s), read references/bark.md and apply the completion-sound contract.

Examples

Request	Route
"Make a wizard with idle and walk animations."	MCP create_character, then animate_character; south first, ask before all directions.
"Use the humanoid Walk (8 frames) template animation."	references/preset-skeleton-template-animation.md; MCP animate_character with template_animation_id="walking-8-frames", REST /characters/animations fallback.
"Auto-rig this sprite and animate from the skeleton."	references/preset-skeleton-template-animation.md; REST estimate-skeleton, then animate-with-skeleton.
"Generate a mossy platformer tileset from code."	MCP create_sidescroller_tileset; REST v2 create-tileset-sidescroller for code/exact control or when MCP is unavailable.
"Make a 512x256 UI panel with a portrait circle and three buttons."	MCP create_ui_asset with pieces/elements; REST v2 create-ui-asset when style_image/project_id is needed or MCP is unavailable.
"Convert this image to pixel art and remove the background."	REST v2 image-to-pixelart-pro, then remove-background.
"Add a wind dash effect to this runner sprite."	MCP edit_image (pro) when MCP-first, else REST v2 edit-image; the runner is the edit target, effect on the same canvas.
"Give my character a leather helmet as a separate layer."	Paperdoll edit per references/paperdolling.md, not object generation.
"Use /tilesets/create with my browser token."	Refuse; route to public MCP/REST tileset tools or manual website use.
"What does Pro use?"	Product-level facts only; refresh official docs if current model details matter.
"Cheapest way to get a few item icons?"	references/cost-routing.md + references/icon.md; prefer a non-Pro route and name the tradeoff.
"Make a 30-second looping scene from this frame."	references/cinematic.md; ask for a budget if none given, decide cyclic vs evolving (one looped clip or chained shots), plan, validate each shot.