photo-editor

name	photo-editor
description	MPSTATS Photo Editor API. Use when generating product photos, photoshoots, infographics, recolors, in-action scenes, background removal/replacement, upscaling, prompt-based image edits for marketplace sellers (Wildberries, Ozon, YM).
license	MIT
metadata	{"author":"mpstats","version":"1.1.0"}

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:

Stage	File	When
1. Research	references/01-research.md	Default for mode B unless the user chose "no research".
2. Brief	references/02-brief.md	Always before generating in mode B. Also covers all prompt-craft: prompt structure, slide series, length limit, content-filter.
3. Generate	references/03-generate.md	Always. Before running, ask: "the full batch right away, or a test frame first?".
4. Deliver	references/04-deliver.md	Mandatory, read BEFORE showing the result. Show every frame via Read with an anchor caption, not a list of paths.

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:

User answer	Action
"with research" / "full analysis" / silence (no explicit refusal)	Run Stage 1 → 2 → 3 → 4 in full
"no research" / "generate right away" / "from my prompt"	Skip Stage 1, go straight to Stage 2 (brief from the user's description) → 3 → 4. State explicitly: "Skipping research — quality may be lower, but it's faster."
User provides a ready prompt in the message	Clarify: use it as-is or run it through the brief (length check, block structure, product lock)?

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

Mask	Tier	Default	Aspect ratios	Available for
model_1	Standard	✅ all except infographics	1:1, 3:4, 4:3, 2:3, 3:2	all endpoints
model_2	PRO	✅ infographics	1:1, 3:4, 4:3, 2:3, 3:2	all endpoints
model_3	PRO	—	1:1, 3:4, 4:3, 2:3, 3:2	all endpoints
model_4	PRO	—	1:1, 3:4, 4:3, 2:3, 3:2	all endpoints
model_5	PRO	—	1:1, 3:4, 4:3	freeform, photoshoot

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

Script	When to use
remove-background.sh <img>	Remove the background
upscale.sh <img>	Increase resolution
replace-background.sh <img> <template_key>	Place the product on a stock background
in-action.sh <img> <template_key>	Product in a ready usage scene
recolor.sh <img> <#hex>	Recolor the product
freeform.sh <img> "<prompt>" [model] [ar] [refs]	Freeform edit (single-step)
photoshoot.sh auto <img> "<prompt>" <count>	Photoshoot (test → generate in one command)
photoshoot.sh test | generate	When you need to approve the test frame separately
infographics.sh auto <img> "<prompt>" <count>	Infographics (test → generate)
infographics.sh test | generate	Same as photoshoot
templates.sh backgrounds [key]	List template_key for replace-background
templates.sh in-action [key]	List template_key for in-action
wb-fetch-photos.sh <sku-or-url> [max=8]	Download WB product photos. Called automatically on wb:<sku> input
health.sh	Check the service
run.sh <endpoint> <body_json>	Universal submit + poll
poll.sh <event_id>	Wait for a ready event_id

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

msg	What to do
process_completed	Done, files saved
process_completed + output.image: []	Content-filter → rephrase the prompt (references/02-brief.md)
process_error	Read error.message, show it to the user
process_timeout	The server didn't finish in time; reduce count or change the model
Prompt size exceeds maximum allowed length	Most often the cause is line breaks (\n) in the prompt, not an actual limit overflow. Pass the prompt as a single line. If the error persists after that — shorten the prompt: references/02-brief.md → Technical limits.
AUTH_ERROR	Invalid credentials — see the Config section
Local poll timeout	The script stopped polling; the event_id remains — poll.sh <event_id>