Back to Details

photo-editor

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

MPSTATS Photo Editor

MPSTATS 图片编辑器

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.
这是MPSTATS内部用于为电商商品卡片生成AI视觉内容的服务，支持背景移除/替换、图片放大、改色、「商品场景展示」、提示词编辑、拍摄图生成、信息图表制作等功能。
所有请求都通过
scripts/
目录下的现成脚本执行（Bash工具，请勿重写代码）。接口为异步模式：每个脚本负责提交请求 → 轮询状态 → 保存文件。图片在脚本内部以base64编码处理。

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:
StageFileWhen
1. Researchreferences/01-research.mdDefault for mode B unless the user chose "no research".
2. Briefreferences/02-brief.mdAlways before generating in mode B. Also covers all prompt-craft: prompt structure, slide series, length limit, content-filter.
3. Generatereferences/03-generate.mdAlways. Before running, ask: "the full batch right away, or a test frame first?".
4. Deliverreferences/04-deliver.mdMandatory, read BEFORE showing the result. Show every frame via 
Read
with an anchor caption, not a list of paths.
请谨慎选择——模式会改变后续所有操作流程。
A. 技术操作（单步骤） —— 对应
remove-background
、
upscale
、
replace-background
、
in-action
、
recolor
、
freeform
。运行脚本 → 获取结果 → 交付。无需调研/简报。适用于明确的操作需求（如「移除背景」「放大图片」「改为蓝色」）。
B. 设计任务（多阶段） —— 对应
infographics
和
photoshoot
。需要完成完整的设计工作：以电商设计师的思路思考。适用于涉及买家价值的需求（如「制作信息图表」「更新商品卡片」「我需要一套拍摄图」）。请遵循
references/
目录下的阶段指南——这些是思考框架，而非检查清单：
阶段文件适用场景
1. 调研references/01-research.md模式B的默认流程，除非用户明确选择「无需调研」。
2. 简报references/02-brief.md模式B下生成内容前必须完成。同时涵盖所有提示词创作规则：提示词结构、幻灯片系列、长度限制、内容过滤。
3. 生成references/03-generate.md所有模式下都必须执行。运行前需询问：「直接生成全部内容，还是先出测试样图？」
4. 交付references/04-deliver.md必须执行，请在展示结果前阅读。通过
Read
工具展示每张图并附上锚点说明，而非仅提供路径列表。

Mode B start — mandatory question

模式B启动——必选问题

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 answerAction
"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 messageClarify: 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.
当任务被判定为模式B时，首先需要询问用户一个问题：
是否需要进行完整调研（竞品分析、用户评价、视觉基准），还是直接根据您的提示词/描述生成内容？
不同回答对应的操作：
用户回答操作
「需要调研」/「完整分析」/ 无明确拒绝（沉默）完整执行阶段1 → 2 → 3 → 4
「无需调研」/「直接生成」/「根据我的提示词」跳过阶段1，直接进入阶段2（根据用户描述制作简报）→ 3 → 4。需明确告知：「将跳过调研环节——生成速度更快，但质量可能有所下降。」
用户在消息中提供现成的提示词确认：直接使用该提示词，还是按照简报规则优化（长度检查、模块结构、商品锁定）？
例外情况：如果用户在初始请求中已明确说明「无需分析」/「无需调研」——无需询问，直接进入阶段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.
凭证存储在
config/.env
（已加入git忽略）中：
PHOTO_EDITOR_TOKEN
（请求头
X-Mpstats-TOKEN
）和可选的
PHOTO_EDITOR_BASE_URL
（默认值为
https://mpstats.io/api/big_data/proxy
）。配置方法和变量说明：config/README.md。
如果缺少token（或token为
your_token_here
），Agent必须询问：
我需要MPSTATS Photo Editor的API令牌（X-Mpstats-TOKEN）——请从您的MPSTATS账户 → API页面获取并发送给我，我会将其写入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.
请勿将结果存入技能文件夹——技能是代码，输出属于数据。默认路径为
~/.claude/output/photo-editor/<event_id>/
，可通过
PHOTO_EDITOR_OUTPUT_DIR
变量覆盖。
对于模式B，生成完成后请将文件复制到按SKU划分的独立文件夹中，并使用有意义的文件名（如
slide_1_hero.png
等）——
event_id
包含冒号
:
，可能导致部分UI客户端无法渲染图片，而按SKU划分更便于用户浏览。

Multi-angle input: 
wb:<sku>

多角度输入：
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).
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.sh
和
photoshoot.sh
中，第一个参数可以是
wb:<sku>
或
wb:<wb-url>
，而非文件路径。技能会从WB CDN下载该商品的所有图片（通过
wb-fetch-photos.sh
脚本，缓存于
~/.claude/cache/photo-editor/wb-photos/<sku>/
）：第一张图作为
main_image
，其余作为
reference_images
（最多5张，API不接受更多）。
bash
infographics.sh generate wb:164419278 "$PROMPT" 5
对于多角度输入，在商品锁定说明中请写「保留商品辨识度」，而非「保留相同角度」——否则模型会将第一张图的角度复制到所有幻灯片中。更多提示词相关说明请参考
references/02-brief.md
。

Infographics: a series of N slides

信息图表：N张幻灯片系列

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
.
infographics.sh generate <img> "<prompt>" <count>
会一次性生成**
count
张幻灯片**（1-6张）。流程：
test
（生成测试样图）→ 确认通过 → 
generate <N>
；或使用
auto
（一次性完成测试+生成）。
最少输出4张图。接口始终返回
max(4, image_count)
张图片——即使请求1-3张，仍会返回4张。拍摄图无此限制。
提示词需设定整体方向+单图主题，而非每张幻灯片的布局——否则会在单张画布上生成2×3的拼接图。提示词创作细节请参考
references/02-brief.md
。

Models

模型

MaskTierDefaultAspect ratiosAvailable for
model_1
Standard✅ all except infographics1:1, 3:4, 4:3, 2:3, 3:2all endpoints
model_2
PRO✅ infographics1:1, 3:4, 4:3, 2:3, 3:2all endpoints
model_3
PRO—1:1, 3:4, 4:3, 2:3, 3:2all endpoints
model_4
PRO—1:1, 3:4, 4:3, 2:3, 3:2all endpoints
model_5
PRO—1:1, 3:4, 4:3freeform, 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.
标识等级默认适用场景宽高比支持的接口
model_1
标准版✅ 除信息图表外的所有场景1:1、3:4、4:3、2:3、3:2所有接口
model_2
PRO版✅ 信息图表1:1、3:4、4:3、2:3、3:2所有接口
model_3
PRO版—1:1、3:4、4:3、2:3、3:2所有接口
model_4
PRO版—1:1、3:4、4:3、2:3、3:2所有接口
model_5
PRO版—1:1、3:4、4:3freeform、photoshoot
后端不接受
model=auto
参数——技能会自动将其解析为
model_1
（标准版）。信息图表默认使用
model_2
（PRO版）——西里尔文字符质量最优。仅当有明确理由时才指定特定模型。

Scripts

脚本列表

ScriptWhen 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
脚本使用场景
remove-background.sh <img>
移除背景
upscale.sh <img>
提升分辨率
replace-background.sh <img> <template_key>
将商品放置在预设背景上
in-action.sh <img> <template_key>
生成商品使用场景图
recolor.sh <img> <#hex>
为商品改色
freeform.sh <img> "<prompt>" [model] [ar] [refs]
自由编辑（单步骤）
photoshoot.sh auto <img> "<prompt>" <count>
拍摄图生成（测试+生成一键完成）
photoshoot.sh test | generate
需要单独确认测试样图时使用
infographics.sh auto <img> "<prompt>" <count>
信息图表生成（测试+生成一键完成）
infographics.sh test | generate
与拍摄图脚本逻辑相同
templates.sh backgrounds [key]
列出
replace-background
可用的
template_key
templates.sh in-action [key]
列出
in-action
可用的
template_key
wb-fetch-photos.sh <sku-or-url> [max=8]
下载WB商品图片。使用
wb:<sku>
输入时会自动调用
health.sh
检查服务状态
run.sh <endpoint> <body_json>
通用提交+轮询脚本
poll.sh <event_id>
等待指定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
  • 「清理背景」→ 模式A，使用
    remove-background.sh
  • 「放大/锐化图片」→ 模式A，使用
    upscale.sh
  • 「将背景改为工作室/大理石纹理」→ 模式A，先执行
    templates.sh backgrounds
    再使用
    replace-background.sh
  • 「展示商品使用场景」→ 模式A，先执行
    templates.sh in-action
    再使用
    in-action.sh
  • 「改为#hex颜色」→ 模式A，使用
    recolor.sh
  • 「调整光线/去除反光/添加阴影」→ 模式A，使用
    freeform.sh
  • 「制作信息图表/拍摄图」「更新商品卡片X」→ 模式B，从
    references/01-research.md
    开始执行

Errors

错误处理

msgWhat 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 timeoutThe script stopped polling; the event_id remains — 
poll.sh <event_id>
消息处理方式
process_completed
任务完成，文件已保存
process_completed
+ 
output.image: []
内容被过滤 → 重新调整提示词（参考
references/02-brief.md
）
process_error
读取
error.message
并告知用户
process_timeout
服务器未按时完成任务；减少生成数量或更换模型
Prompt size exceeds maximum allowed length
最常见原因是提示词中的换行符(
\n
)，而非实际长度超限。将提示词作为单行传入。若问题仍存在，请缩短提示词：参考
references/02-brief.md
→ 技术限制部分。
AUTH_ERROR
凭证无效 → 参考配置部分
本地轮询超时脚本停止轮询；event_id仍有效 → 使用
poll.sh <event_id>
继续等待