Pixel Prompt CATPIT — asset on-brand e animati (API v2)

Fonte di verità del design: KB_Sprite/DESIGN_personaggi_e_ambiente.md. Forma finale: **spazio
vivo dove i gatti si muovono**, NON collage statico.

1. API v2 — usa il sistema CHARACTER (è la chiave)

Base: https://api.pixellab.ai/v2 · Auth: header Authorization: Bearer <PIXELLAB_SECRET> · JSON.
Immagine in input (init/reference/style): oggetto {"type":"base64","base64":"<...>","format":"png"}.

Per i personaggi vivi NON cucire sprite a mano: usa la pipeline Character, fatta apposta per
"un personaggio coerente che si muove":

1. `POST /create-character-v3` — da reference_image (lo sprite del gatto già approvato, sud/frontale) + description → un personaggio salvato in 8 direzioni, coerente in automatico. Restituisce un riferimento al character (id). (image_size from-scratch default 64; con reference max 256.)
2. `POST /animate-character` — anima il character esistente (character_id) → animazioni per direzione (walk, idle, ecc.). Modalità v3: action_description + frame_count (4–16). È asincrona: ritorna un job per direzione → fai polling su GET /background-jobs/{job_id} finché status=="completed" → i fotogrammi sono in `last_response.images` (base64).
3. `POST /create-character-state` — nuovi stati/pose dello stesso gatto (es. "seduto che digita", "acciambellato che dorme").

Per animazioni singole senza il sistema character: `POST /animate-with-text-v3` (first_frame +
action + frame_count 4/8/16, fino a 256×256) → async, frame in last_response.images.
Per immagini singole / sfondi: POST /create-image-pixflux (sincrono, response {image:{base64},usage}).

⚠️ La libreria pip pixellab è vecchia/rotta: chiama gli endpoint REST v2 diretti.

Flusso character CONFERMATO (2026-06-30): create-character-v3 torna subito
{character_id, background_job_id, status:"processing"} e genera in background (qualche minuto).
Le immagini NON sono nel job: si recuperano con `GET /characters/{character_id}` → campo
`rotation_urls` = 8 URL PNG (south/west/east/north + diagonali), size 256×256,
view:"low top-down", template mannequin, più `skeletons.3d` (per animate-with-skeleton).
Le animazioni si aggiungono con POST /animate-character (character_id + action_description +
frame_count; async per direzione); poi animation_count cresce e i frame si scaricano dalle url del character.

2. Coerenza & STILE (risolve "gatti che stonano con la stanza")

• Coerenza personaggio: il sistema Character la garantisce (stesso character_id, 8 direzioni). In più: seed fisso, init_image, color_image (palette forzata).
• Stile coerente con l'ambiente: usa `POST /generate-with-style-v2` passando come style_images un riferimento dello stile della stanza (lo sfondo underground) → i personaggi escono nello stesso stile, non lisci e incollati. (style_images = lista di {"image":<base64image>,"width","height"}.)

3. Utility che ci servono

• `POST /resize` — ridimensiona uno sprite preservando il pixel → sistema la SCALA (gatti proporzionati ai mobili). (max 200×200)
• `POST /remove-background` — PNG trasparente pulito (remove_simple_background / remove_complex_background).
• `POST /inpaint` (o edit-image) — ritocchi mirati su una zona (es. cravatta, macchie).
• *`POST /enhance--prompt`** — migliora un prompt corto (pochi centesimi).

4. Design CATPIT (grounding — vedi DESIGN_personaggi_e_ambiente.md)

Gatti vestiti solo sopra, zampe pelose nude (gag). Description corta, niente "pixel art".

Parametri base personaggi: outline:"single color black outline", shading:"basic shading",
detail:"medium detail", direction:"south" per il riferimento. Palette arancio #ff7a1a + blu
#2ec4ff + giallo #ffd23f su scuro.

Ambiente (decise): vecchio ufficio della metro abbandonato → gattile underground punk, dismesso, 5
postazioni PC + cucce. Sfondo già scelto: office_underground_3 (schiarito).

5. I 7 CRITERI DI QUALITÀ della scena (vincolanti — la scena è ok solo se li passa tutti)

1. Si muove: un gatto cammina cuccia↔scrivania al cambio di stato (non statica).
2. Stile unico: personaggi coerenti con lo sfondo (usa style-reference; non sprite lisci incollati).
3. Scala/prospettiva giuste: gatti proporzionati ai mobili (usa resize).
4. Pose per stato: seduto-di-profilo-che-digita (active), acciambellato-che-dorme (idle), walk laterale (transizioni). Mai il ritratto frontale in scena.
5. Stato leggibile dalla scena (non solo dall'etichetta).
6. Luce/ombra: ombra di contatto a terra + tinta dell'ambiente sui personaggi.
7. Composizione curata: posizioni reali, cucce che non coprono le sedie, z-order corretto.

6. Pipeline consigliata per UN gatto (vertical slice)

Riferimento approvato → create-character-v3 (8 direzioni) → create-character-state (seduto-typing, dorme)
→ animate-character (walk per le transizioni) → resize alla scala di scena → montaggio nel motore
2D dell'app (CSS steps()/canvas) con movimento guidato dai dati reali. Budget: fai **prima un solo