MPSTATS Photo Editor

Internal MPSTATS service for AI-generated visuals for marketplace product cards: background removal/replacement, upscaling, recolor, "product in action", prompt-edit, photoshoots, infographics.

All requests go through the ready-made scripts in scripts/ (Bash tool, do not rewrite the code). Endpoints are asynchronous: each script handles submit → polling → saving files. Images are base64-encoded inside the scripts.

Two modes of operation

Choose deliberately — it changes all downstream behavior.

A. Technical operations (single-step) — remove-background, upscale, replace-background, in-action, recolor, freeform. Run the script → get the result → deliver. No research/brief. Use when a concrete action is requested ("remove the background", "upscale", "recolor to blue").

B. Design tasks (multi-stage) — infographics and photoshoot. Full design work: think like a marketplace designer. Use when the request is about buyer value ("make an infographic", "refresh the card", "I need a photoshoot"). Use the stage guides in references/ — these are thinking guides, not checklists:

Mode B start — mandatory question

When a task is identified as mode B, the first thing to do is ask a single question:

Run full research (competitor analysis, reviews, visual benchmark) or generate right away from your prompt / description?

Possible answers and what to do:

Exception: if the user already explicitly stated "no analysis" / "no research" in the first message — don't ask, go straight to Stage 2.

Config

Credentials in config/.env (gitignored): PHOTO_EDITOR_TOKEN (header X-Mpstats-TOKEN) and optional PHOTO_EDITOR_BASE_URL (default https://mpstats.io/api/big_data/proxy). Setup and variables: config/README.md.

If the token is missing (or it is your_token_here), the agent must ask:

I need an MPSTATS API token (X-Mpstats-TOKEN) for Photo Editor — get it from your MPSTATS account → API and send it over, I'll write it into config/.env.

Output location

Do NOT put results in the skill folder — the skill is code, output is data. Default ~/.claude/output/photo-editor/<event_id>/, override via PHOTO_EDITOR_OUTPUT_DIR.

For mode B, after generation copy the files into a clean per-SKU folder with meaningful names (slide_1_hero.png, etc.) — event_id contains :, which breaks image rendering in some UI clients, and per-SKU is easier for the user to navigate.

Multi-angle input: wb:<sku>

In infographics.sh and photoshoot.sh the first argument can be wb:<sku> or wb:<wb-url> instead of a file path. The skill downloads all product photos from the WB CDN (wb-fetch-photos.sh, cached in ~/.claude/cache/photo-editor/wb-photos/<sku>/): the first → main_image, the rest → reference_images (max 5, the API won't accept more).

infographics.sh generate wb:164419278 "$PROMPT" 5

For multi-angle input, in the product-lock instruction write "preserve product identity", NOT "preserve same orientation" — otherwise the model copies the first photo's angle onto every slide. More on the prompt — references/02-brief.md.

Infographics: a series of N slides

infographics.sh generate <img> "<prompt>" <count> creates a series of count slides (1..6) in a single call. Flow: test (a trial frame) → approve → generate <N>; or auto (test + generate at once).

Minimum output is 4 frames. The endpoint always returns max(4, image_count) images — requesting count=1..3 still yields 4. Photoshoot has no such limit.

The prompt sets the high-level direction + frame themes, not the layout of each slide — otherwise you get a 2×3 collage on a single canvas. Prompt-craft details — references/02-brief.md.

Models

The backend does not accept model=auto — the skill resolves it to model_1 (Standard). For infographics the default is hard-wired to model_2 (PRO) — best Cyrillic quality. Specify an explicit model only if you have a hypothesis why.

Scripts

Decision Guide

• "clean up the background" → A, remove-background.sh
• "make it bigger/sharper" → A, upscale.sh
• "change the background to a studio/marble" → A, templates.sh backgrounds → replace-background.sh
• "show the product in use" → A, templates.sh in-action → in-action.sh
• "recolor to #hex" → A, recolor.sh
• "fix the lighting / remove the glare / add a shadow" → A, freeform.sh
• "make an infographic / photoshoot", "refresh product card X" → B, start with references/01-research.md

Errors