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>

infographics.sh

and

photoshoot.sh

the first argument can be

wb:<sku>

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).

bash

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>`

photo-editor

NPX Install

Tags

SKILL.md Content