diff --git a/deploy/container/api-server.env.example b/deploy/container/api-server.env.example
index e0f28bdbf..002bc4990 100644
--- a/deploy/container/api-server.env.example
+++ b/deploy/container/api-server.env.example
@@ -32,9 +32,17 @@ GENARRATIVE_WALLET_REFUND_OUTBOX_DIR=/var/lib/genarrative/wallet-refund-outbox
 GENARRATIVE_WALLET_REFUND_OUTBOX_BATCH_SIZE=100
 GENARRATIVE_WALLET_REFUND_OUTBOX_FLUSH_INTERVAL_MS=1000
 GENARRATIVE_WALLET_REFUND_OUTBOX_MAX_BYTES=67108864
-GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS=45000
+GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS=180000
 GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD=3
 GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS=300
+# BgFilter 失败后的中间兜底：阿里云通用抠图（SegmentCommonImage）。AccessKey 留空则跳过该层，
+# BgFilter 失败直接本地 editor_green_screen 去背；填入后恢复 BgFilter→阿里云→本地三级兜底。
+# AccessKey 也可复用标准 SDK 命名 ALIBABA_CLOUD_ACCESS_KEY_ID / ALIBABA_CLOUD_ACCESS_KEY_SECRET。
+GENARRATIVE_ALIYUN_MATTING_ENABLED=true
+GENARRATIVE_ALIYUN_MATTING_ENDPOINT=imageseg.cn-shanghai.aliyuncs.com
+GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_ID=
+GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_SECRET=
+GENARRATIVE_ALIYUN_MATTING_REQUEST_TIMEOUT_MS=30000
 
 GENARRATIVE_OTEL_ENABLED=true
 OTEL_SERVICE_NAME=genarrative-api
diff --git a/deploy/env/api-server.env.example b/deploy/env/api-server.env.example
index cbf014f0c..636b111fc 100644
--- a/deploy/env/api-server.env.example
+++ b/deploy/env/api-server.env.example
@@ -32,9 +32,17 @@ GENARRATIVE_WALLET_REFUND_OUTBOX_DIR=/var/lib/genarrative/wallet-refund-outbox
 GENARRATIVE_WALLET_REFUND_OUTBOX_BATCH_SIZE=100
 GENARRATIVE_WALLET_REFUND_OUTBOX_FLUSH_INTERVAL_MS=1000
 GENARRATIVE_WALLET_REFUND_OUTBOX_MAX_BYTES=67108864
-GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS=45000
+GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS=180000
 GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD=3
 GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS=300
+# BgFilter 失败后的中间兜底：阿里云通用抠图（SegmentCommonImage）。AccessKey 留空则跳过该层，
+# BgFilter 失败直接本地 editor_green_screen 去背；填入后恢复 BgFilter→阿里云→本地三级兜底。
+# AccessKey 也可复用标准 SDK 命名 ALIBABA_CLOUD_ACCESS_KEY_ID / ALIBABA_CLOUD_ACCESS_KEY_SECRET。
+GENARRATIVE_ALIYUN_MATTING_ENABLED=true
+GENARRATIVE_ALIYUN_MATTING_ENDPOINT=imageseg.cn-shanghai.aliyuncs.com
+GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_ID=
+GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_SECRET=
+GENARRATIVE_ALIYUN_MATTING_REQUEST_TIMEOUT_MS=30000
 GENARRATIVE_OTEL_ENABLED=true
 OTEL_SERVICE_NAME=genarrative-api
 OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318
diff --git a/docs/openapi/genarrative-external-v1.openapi.json b/docs/openapi/genarrative-external-v1.openapi.json
index fd8dee488..67596e4dd 100644
--- a/docs/openapi/genarrative-external-v1.openapi.json
+++ b/docs/openapi/genarrative-external-v1.openapi.json
@@ -2508,6 +2508,13 @@
             "type": "string",
             "minLength": 1
           },
+          "screenColor": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "纯色抠像背景色。可传画布支持的纯色背景 hex（如 #CFEFFF）指定；传 \"auto\"、null 或省略则由服务端自动决策。"
+          },
           "size": {
             "type": "string",
             "description": "兼容旧 size 入参；未传 aspectRatio/imageSize 时生效。",
@@ -2872,6 +2879,13 @@
               "type": "string"
             }
           },
+          "screenColor": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "纯色抠像背景色。可传画布支持的纯色背景 hex（如 #CFEFFF）指定；传 \"auto\"、null 或省略则由服务端自动决策。"
+          },
           "model": {
             "type": "string",
             "default": "gemini-3.1-flash-image-preview"
@@ -2937,6 +2951,13 @@
             "type": "string",
             "description": "UI 设计图 Data URL 或 objectKey。"
           },
+          "screenColor": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "纯色抠像背景色。可传画布支持的纯色背景 hex（如 #CFEFFF）指定；传 \"auto\"、null 或省略则由服务端自动决策。"
+          },
           "model": {
             "type": "string",
             "default": "gemini-3.1-flash-image-preview",
@@ -3163,6 +3184,13 @@
             "minLength": 1,
             "maxLength": 4000
           },
+          "screenColor": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "纯色抠像背景色。可传画布支持的纯色背景 hex（如 #CFEFFF）指定；传 \"auto\"、null 或省略则由服务端自动决策。"
+          },
           "resolution": {
             "type": "string",
             "enum": [
diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md
index 9881ef82a..7539f761d 100644
--- a/docs/project-memory/shared-memory/decision-log.md
+++ b/docs/project-memory/shared-memory/decision-log.md
@@ -16,6 +16,30 @@
 
 ---
 
+## 2026-07-10 BgFilter segModel 保留内部字段，不进入外部 OpenAPI
+
+- 背景：`api-server` 的图片生成、图标 spritesheet 与 UI 素材提取请求仍可反序列化 `segModel`，并识别 `birefnet` / `anime-seg`，以兼容内部调用和既有任务；但 BgFilter 当前受服务进程内存与并发容量约束，不同分割模型的内存占用并非可由外部调用方自由选择的稳定契约。
+- 决策：`segModel` 是有效的**内部**字段，不是用户可配置字段。产品 UI 不提供抠图模型选择，应用内调用固定使用 `birefnet`；外部编辑器 OpenAPI 刻意不声明 `segModel`，并通过请求 schema 的 `additionalProperties: false` 拒绝该字段。外部调用方应省略它并使用服务端默认值；只有维护 BgFilter 容量与模型策略的后端代码可在经过内存 / 并发验证后调整内部固定值或兼容策略。
+- 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、`src/services/image-editor/editorProjectClient.ts`、图片画布提交模型、`docs/openapi/genarrative-external-v1.openapi.json`。
+- 验证方式：确认外部 OpenAPI 三个生成请求 schema 均未公开 `segModel` 且保持 `additionalProperties: false`；运行 `npm run check:encoding` 和 `git diff --check`。
+- 关联文档：`docs/project-memory/shared-memory/pitfalls.md`（BgFilter 模型字段的对外暴露边界）。
+
+## 2026-07-10 背景色决策统一走 gpt-5-mini 并挪到预扣泥点之后
+
+- 背景：背景色决策此前无源图路径继承 `state.llm_client()`（Ark/豆包，选色能力弱、线上从未真正调用 VectorEngine）；且四条生成链路（角色生图 / 角色动作生视频 / 图标 spritesheet / UI 设计图提取）都在 `execute_billable_asset_operation_with_cost` 预扣泥点之前发起决策，导致用户余额不足或生成注定失败时仍白发一次 gpt-5-mini 决策、平台白付 token，也与定价文档「预扣失败不得继续调用上游」的原则相悖。
+- 决策：（1）无源图决策改走独立常量 `EDITOR_SCREEN_BACKGROUND_TEXT_LLM_MODEL = gpt-5-mini`（VectorEngine，Responses 协议 + `reasoning_effort=low`），与有源图视觉档 `EDITOR_SCREEN_BACKGROUND_VISION_LLM_MODEL` 分离、便于各自调参；gpt5 客户端未配置时才降级回默认文本客户端。（2）**所有用到背景色决策的生成链路，决策必须在余额校验 + 预扣泥点之后发起**：预扣前只做颜色无关的算价 / 校验 / settings（动画用默认色占位算价，与队列路径一致），决策及颜色相关的 prompt / 合成 / `generationInputs` 搬进 billable 闭包，闭包把决策结果带出供后续抠图与落库使用。语义：余额不足则决策不跑（平台零成本）；决策失败则闭包返 `Err` 走失败退款（用户不损失泥点）。后续新增任何用背景色的生成链路都必须遵循此顺序。
+- 影响范围：`server-rs/crates/api-server/src/llm_model_routing.rs`、`editor_screen_background_decision.rs`、`editor_project.rs`（生图 / 图标 / UI 提取三条 `_for_owner`）、`character_animation_assets.rs`（动画 `_for_owner`）；四条链路的 worker / inline / agent / external-API 入口同时覆盖。
+- 验证方式：`cargo test -p api-server editor_project --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server character_animation --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`；`editor_screen_background_decision::tests::live_*`（`-- --ignored`，需真实 `VECTOR_ENGINE_*`）验证有图 / 无图两条路径真实调用 VectorEngine。
+- 关联文档：`docs/【编辑器】模型定价配置管理方案-2026-06-22.md`（预扣泥点原则）、`docs/project-memory/shared-memory/pitfalls.md`（gpt-5-mini 图片输入上限实测）。
+
+## 2026-07-09 角色动作视频生成背景色统一为多色自动决策 + 阿里云抠帧
+
+- 背景：角色动作视频抽帧过去固定 legacy `#00FF00` 绿幕 + 本地 `editor_green_screen`，与生图链路的多色自动决策不一致；实测出现背景色与前景 / 皮肤撞色（蓝撞蓝、桃 / 黄撞肤色）以及图生视频背景变白的问题。
+- 决策：角色动作视频背景色与生图统一。`screenColor=auto` 时由视觉 LLM（`gpt-5-mini`，Responses 协议、`reasoning_effort=low`，`max_tokens=1024`）读源角色图自动决策，并经硬过滤器（Lab 危险质量 + 皮肤专属三判据：ΔE 距离 / 色调投影 / RGB 分离）剔除与前景及皮肤撞色的候选，手动 hex 仍尊重用户选择；透明源角色图在提交 Ark 图生视频前先合成到选定背景色实色，使视频背景确定性等于抠图键色。抽帧后逐帧优先走阿里云通用抠图，失败降级本地 `editor_green_screen` 键色兜底（按生成时选定的背景色，而非固定 `#00FF00`）。BgFilter 与阿里云抠图失败均写入 `external_api_call_failure` 失败审计。调色板新增中明度低饱和「灰竹绿 `#A0BBA0`」补齐冷区绿色段。
+- 影响范围：`server-rs/crates/api-server/src/character_animation_assets.rs`、`editor_screen_background_decision.rs`、`editor_screen_background_filter.rs`（新增硬过滤模块）、`editor_green_screen.rs`（调色板）、`external_api_audit.rs`、`llm_model_routing.rs`、图片画布 MVP 与后端数据契约文档。
+- 验证方式：`cargo test -p api-server editor_screen_background character_animation --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、真机对源角色图跑视觉决策与候选危险度表、抽帧后采样序列帧背景色确认落在冷区安全集。
+- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
 ## 2026-07-09 充值订单过期改为 SpacetimeDB scheduled 表触发
 
 - 背景：旧充值过期处理使用 api-server 后台轮询 worker claim 普通 schedule 表，非 HTTP 的 external-generation-worker / controller 进程也可能启动同一过期任务；扩外部生成 worker 会意外放大微信查单 / 关单流量，并且本地过期后若微信仍可支付，容易出现“微信扣款但本地拒绝入账”的风险。
@@ -35,7 +59,7 @@
 ## 2026-07-02 图片画布生成抠图背景色使用 screenColor 传递
 
 - 背景：画布角色、图标和 UI 素材生成过去固定要求 `#00FF00` 绿幕，后续 BGfilter 服务需要按生成时背景色做去背景，不能继续把背景色写死在 prompt 或后处理里。
-- 决策：角色形象、图标 spritesheet 和 UI 设计图素材提取不再向用户提供手动抠图背景色选择；前端用户路径统一提交 `screenColor=auto`，但用户可见生成输入快照不再写入 `抠图背景色` 或 `抠图模型`。api-server 在 11 个候选色中自动决策具体 hex，失败后兜底 `#CFEFFF`；最终 prompt 和 BgFilter 去背景只接收解析后的具体 hex 作为 `screen_color`。后端仍保留手动 hex 解析能力供内部兼容，角色动作抽帧暂不接入该选择，继续使用 legacy `#00FF00` 绿幕。
+- 决策：角色形象、图标 spritesheet 和 UI 设计图素材提取不再向用户提供手动抠图背景色选择；前端用户路径统一提交 `screenColor=auto`，但用户可见生成输入快照不再写入 `抠图背景色` 或 `抠图模型`。api-server 在 12 个候选色中自动决策具体 hex，失败后兜底 `#CFEFFF`；最终 prompt 和 BgFilter 去背景只接收解析后的具体 hex 作为 `screen_color`。后端仍保留手动 hex 解析能力供内部兼容。角色动作背景色和抠帧口径已由 2026-07-09 决策取代。
 - 影响范围：`/editor/canvas` 角色形象生成、图标素材生成、UI 设计图素材提取、BgFilter 服务入参、图片画布 MVP 和角色形象生成设计文档。
 - 验证方式：运行画布生成模型 / workflow / API client 定向前端测试、`cargo test -p api-server editor_green_screen --manifest-path server-rs/Cargo.toml`、`cargo test -p platform-image generated_asset_sheet_light_blue_key_color_removes_selected_background --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding` 和 `git diff --check`。
 - 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`。
@@ -43,7 +67,7 @@
 ## 2026-07-05 图片画布抠图背景色自动决策
 
 - 背景：手动背景色选择对用户负担较高，且不同角色、图标和 UI 素材主题需要避开不同主体色；但 BgFilter 和生成 prompt 仍必须拿到明确的纯色 hex。
-- 决策：前端用户路径直接固定通过 `screenColor=auto` 提交，不再展示背景色选项；api-server 新增 `editor_screen_background_decision` 模块，在角色形象、图标 spritesheet 和 UI 设计图素材提取组装 prompt 前解析 `screenColor`。手动 hex 直接校验并使用；`auto` 通过服务端 LLM 在 11 个候选色中选择具体 hex，最多重试 3 次，LLM 未配置、请求失败或返回非法颜色时 fallback 到 `浅雾蓝 #CFEFFF`。自动解析结果不写入用户可见生成输入快照；最终生图 prompt 和 BgFilter `screen_color` 永远只接收具体 hex，不透传 `auto`。
+- 决策：前端用户路径直接固定通过 `screenColor=auto` 提交，不再展示背景色选项；api-server 新增 `editor_screen_background_decision` 模块，在角色形象、图标 spritesheet 和 UI 设计图素材提取组装 prompt 前解析 `screenColor`。手动 hex 直接校验并使用；`auto` 通过服务端 LLM 在 12 个候选色中选择具体 hex，最多重试 3 次，LLM 未配置、请求失败或返回非法颜色时 fallback 到 `浅雾蓝 #CFEFFF`。自动解析结果不写入用户可见生成输入快照；最终生图 prompt 和 BgFilter `screen_color` 永远只接收具体 hex，不透传 `auto`。
 - 影响范围：`/editor/canvas` 角色形象生成、图标素材生成、UI 设计图素材提取、api-server LLM 调用、BgFilter 参数、图片画布文档。
 - 验证方式：运行背景决策模块单测、画布生成模型 / workflow / API client 定向前端测试、`cargo test -p api-server editor_screen_background_decision editor_green_screen --manifest-path server-rs/Cargo.toml`、`npm run check:encoding` 和 `git diff --check`。
 - 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`、`docs/【编辑器】画板UI设计图生成入口设计-2026-06-17.md`、`docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md`。
@@ -52,6 +76,7 @@
 
 - 背景：曾用一次性 BgFilter live probe 稳定复现 BgFilter 对 2K 输入返回 `HTTP 500 {"detail":"inference failed"}`，浏览器生成链路会因此收到“BgFilter 服务返回非成功状态”。
 - 决策：角色形象生成、图标 spritesheet 生成和 UI 设计图素材提取仍优先调用独立 BgFilter；若 BgFilter 请求失败、返回非成功状态、返回空图片或非法图片，api-server 记录 warning 后使用本地 `editor_green_screen` 按解析后的纯色背景执行确定性去背兜底，不中断生成。手动任意图片去背景仍只走独立 BiRefNet BFF，不使用该兜底。
+- 更正（截至 2026-07-10 实现）：BgFilter 失败/熔断后不再直接本地兜底，而是先走阿里云通用抠图，仅阿里云也失败才本地 `editor_green_screen` 键色兜底；口径统一见 2026-07-09「角色动作视频…阿里云抠帧」决策，并已扩展到本条的角色形象/图标/UI 三条静态生图链路。
 - 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、BgFilter 运维排障、图片画布生成后处理。
 - 验证方式：运行 `cargo test -p api-server editor_canvas_screen_background_generation_uses_bgfilter_postprocess editor_green_screen --manifest-path server-rs/Cargo.toml`、`npm run check:encoding` 和 `git diff --check`。
 - 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`、`docs/【编辑器】画板UI设计图生成入口设计-2026-06-17.md`、`docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md`。
@@ -59,7 +84,7 @@
 ## 2026-07-03 图片画布生成纯色背景资产接入 BgFilter
 
 - 背景：独立 BgFilter 服务已部署在 image host，并提供 `POST /bgfilter/remove-background`，支持显式 `screen_color` 和 `seg_model`。手动去背景已有独立 BiRefNet BFF，不能把两个服务的配置或语义混在一起。
-- 决策：角色形象生成、图标 spritesheet 生成和 UI 设计图素材提取在保存带纯色背景源图后，统一调用 BgFilter 生成透明 PNG；请求 multipart 字段为 `file`、`screen_color=<screenColor>` 和 `seg_model=<segModel>`，前端用户路径固定提交 `segModel=birefnet` 且不展示抠图模型选择；`anime-seg` 路径保留为后端可识别的内部能力但不对用户可见。BgFilter 使用独立配置 `GENARRATIVE_EDITOR_BGFILTER_BASE_URL`、`GENARRATIVE_EDITOR_BGFILTER_TOKEN`、`GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS`，默认 base URL 为 `http://58.87.105.82/bgfilter`，默认请求超时 `45000ms`，token 未配置时复用 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN`。手动 `POST /api/editor/images/background-removals` 继续使用独立 BiRefNet 配置 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_BASE_URL`，不受 BgFilter 影响。BgFilter 参数里的 `seg_model=birefnet` 只表示 BgFilter 内部分割后端，不等于手动去背景的独立 BiRefNet 服务。若 BgFilter 失败，api-server 对这些标准纯色背景生成图使用本地 `editor_green_screen` 兜底；连续失败达到 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD`（默认 `3`）后，`GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS`（默认 `300`）内直接本地兜底。角色动作抽帧仍保留 legacy `#00FF00` 与本地 `editor_green_screen` 透明化。
+- 决策：角色形象生成、图标 spritesheet 生成和 UI 设计图素材提取在保存带纯色背景源图后，统一调用 BgFilter 生成透明 PNG；请求 multipart 字段为 `file`、`screen_color=<screenColor>` 和内部固定的 `seg_model=birefnet`。`segModel` 虽是后端可识别的内部兼容字段（另保留 `anime-seg`），但不向用户或外部 OpenAPI 暴露：当前 BgFilter 的内存与并发容量不适合由调用方自由切换模型。BgFilter 使用独立配置 `GENARRATIVE_EDITOR_BGFILTER_BASE_URL`、`GENARRATIVE_EDITOR_BGFILTER_TOKEN`、`GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS`，默认 base URL 为 `http://58.87.105.82/bgfilter`，默认请求超时 `180000ms`，token 未配置时复用 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN`。手动 `POST /api/editor/images/background-removals` 继续使用独立 BiRefNet 配置 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_BASE_URL`，不受 BgFilter 影响。BgFilter 参数里的 `seg_model=birefnet` 只表示 BgFilter 内部分割后端，不等于手动去背景的独立 BiRefNet 服务。若 BgFilter 失败，api-server 对这些标准纯色背景生成图使用本地 `editor_green_screen` 兜底；连续失败达到 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD`（默认 `3`）后，`GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS`（默认 `300`）内直接本地兜底。角色动作背景色和抠帧口径已由 2026-07-09 决策取代：角色动作同样使用多色自动决策，抽帧后优先阿里云通用抠图，失败再按选定背景色本地兜底。更正（截至 2026-07-10 实现）：BgFilter 失败与熔断期本条描述的「直接本地兜底」已过时——角色形象/图标/UI 三条静态生图链路同样先走阿里云通用抠图，仅阿里云也失败才本地 `editor_green_screen` 兜底。
 - 影响范围：`server-rs/crates/api-server/src/config.rs`、`server-rs/crates/api-server/src/editor_project.rs`、图片画布 MVP 文档和角色形象生成设计文档。
 - 验证方式：运行 `cargo test -p api-server config::tests::from_env_reads_editor_bgfilter_settings_and_reuses_background_token editor_project::tests::editor_canvas_screen_background_generation_uses_bgfilter_postprocess --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding` 和 `git diff --check`。
 - 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`。
@@ -2210,7 +2235,7 @@
 ## 2026-05-07 server-rs Cargo 依赖集中到 workspace
 
 - 背景：`server-rs` 多 crate 已稳定成 DDD workspace，成员 `Cargo.toml` 中重复散写第三方版本和本地 path 依赖，升级 SpacetimeDB SDK、`serde`、`reqwest`、`tokio` 等依赖时容易漂移。
-- 决策：`server-rs/Cargo.toml` 的 `[workspace.dependencies]` 统一维护第三方依赖版本和 workspace 内部 crate path；成员 crate 默认使用 `{ workspace = true }`，只保留自身 feature、optional 或 target-specific 差异；不再新增 `sha1`，OSS 与阿里云 OpenAPI 签名统一走 `sha2::Sha256` 对应的 V4/V3 口径。
+- 决策：`server-rs/Cargo.toml` 的 `[workspace.dependencies]` 统一维护第三方依赖版本和 workspace 内部 crate path；成员 crate 默认使用 `{ workspace = true }`，只保留自身 feature、optional 或 target-specific 差异；OSS 与阿里云 OpenAPI 签名统一走 `sha2::Sha256` 对应的 V4/V3 口径。例外：`platform-matting` 向 VIAPI 官方临时 OSS 桶上传抠图输入时，因该临时桶接口要求 OSS V1 头签名，允许在该 crate 内部受限使用 `sha1` / `Hmac<sha1::Sha1>` 生成 V1 签名；该例外不得扩展到自有 OSS、通用阿里云 OpenAPI 或其它新链路。
 - 影响范围：`server-rs/Cargo.toml`、所有 `server-rs/crates/*/Cargo.toml`、`platform-oss`、`platform-auth`、后续新增 Rust crate 或新增 Rust 依赖的开发流程。
 - 验证方式：修改 Cargo 配置后先执行 `cargo metadata --manifest-path server-rs\Cargo.toml --format-version 1 --no-deps`，再按影响范围执行 `cargo check`、DDD 边界检查和编码检查。
 - 关联文档：`docs/technical/RUST_WORKSPACE_DEPENDENCY_CONSOLIDATION_2026-05-07.md`。
diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index ef90c6a9c..b6bda221d 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -2895,3 +2895,19 @@
 - 处理：`applyGateTarget` 进入不存在的新 target 时必须重置为新建态：`enabled=false`、`rolloutPercent=0`、allow / deny 列表为空，并使用 target 默认描述。只有显式点已有 gate 才 `fillForm` 复制服务端规则。
 - 验证：`npm run test -- apps/admin-web/src/pages/AdminGrayReleaseConfigPage.test.tsx`。
 - 关联：`apps/admin-web/src/pages/AdminGrayReleaseConfigPage.tsx`、`apps/admin-web/src/pages/AdminGrayReleaseConfigPage.test.tsx`。
+
+## 背景色决策喂 gpt-5-mini 的图不必按阿里云抠图那样归一化
+
+- 现象：担心带图背景色决策把源角色图原样 base64 塞给 gpt-5-mini（`resolve_media_source_as_data_url` 不做 resize / 字节上限），会像阿里云通用抠图那样因超尺寸 / 超体积被上游拒绝，于是想给决策链路也补一套图片归一化。
+- 原因：两条链路的上游限制完全不同。阿里云 SegmentCommonImage 有硬限制（≤3MB、分辨率 <2000×2000、最长边 ≤1999），必须归一化；而 gpt-5-mini（经 VectorEngine `/v1/responses`，Responses 协议 + `input_image`）对图片输入宽松得多，实测远超 App 真实源图范围仍全部 HTTP 200：纯色图到 5000×5000（隔离像素维度）正常识别；噪声图到 base64 请求体 34MB（隔离字节维度，PNG 25.8MB）仍成功返回。App 真实源角色图一般 ≤2048px、几 MB，稳落在安全区。
+- 处理：**不要**给 `resolve_editor_screen_background_color` 的带图路径加图片归一化——那是阿里云抠图链路（`platform-matting`）专属需求，两者别混。真要加保护也应放在字节 / 像素远高于当前实测通过档（如 base64 >40MB 或长边 >6000px）才截断，避免无谓重编码开销与画质损失。
+- 验证：探针脚本 `Myscripts/probe_gpt5mini_image_limits.py`（本地不入库，逐级放大纯色 / 噪声图打 `/v1/responses`，记录 HTTP 状态与响应）。2026-07-10 实测：solid 512²~5000² 全 200；noise 900²(4.1MB)~2600²(34.4MB) 全 200，无拒绝阈值出现在实用范围内。
+- 关联：`server-rs/crates/api-server/src/character_animation_assets.rs`（`resolve_media_source_as_data_url`）、`server-rs/crates/api-server/src/editor_screen_background_decision.rs`、`server-rs/crates/platform-matting/src/lib.rs`（对照：阿里云输入归一化）。
+
+## 不要把 BgFilter segModel 暴露为外部可选参数
+
+- 现象：看到 `EditorImageGenerationRequest`、`EditorIconSpritesheetGenerationRequest` 和 `EditorUiDesignAssetExtractionRequest` 能反序列化 `segModel`，容易认为外部 OpenAPI 也应公开该字段，或让用户在 `birefnet` 与 `anime-seg` 间自行选择。
+- 原因：`segModel` 是 BgFilter 内部调用链的有效兼容字段，不等于稳定的外部产品契约。当前 BgFilter 服务受进程内存和并发容量约束，不同分割模型的资源消耗不能交给外部调用方控制；任意开放模型切换会让容量规划、超时和故障隔离失去确定性。
+- 处理：产品 UI 不提供模型选择，应用内调用固定 `birefnet`；外部编辑器 OpenAPI 不声明 `segModel`，并保持相关请求 schema 的 `additionalProperties: false`，使外部请求携带该字段时被契约拒绝。只有维护 BgFilter 模型与容量的后端代码可使用该内部字段；若未来需要开放，先完成各模型的内存、并发和超时压测，再明确版本化外部契约。
+- 验证：检查 `docs/openapi/genarrative-external-v1.openapi.json` 的图片生成、图标 spritesheet 和 UI 素材提取请求 schema 均未包含 `segModel`，且均保持 `additionalProperties: false`。
+- 关联：`server-rs/crates/api-server/src/editor_project.rs`、`src/services/image-editor/editorProjectClient.ts`、`docs/project-memory/shared-memory/decision-log.md`。
diff --git a/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md b/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md
index 0e2fe57f6..767b59d62 100644
--- a/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md
+++ b/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md
@@ -21,7 +21,7 @@
 - 生成资源右上角显示元数据按钮，点击打开独立元数据窗口。图片信息页不展示后端组装后的生图 Prompt，也不提供复制 Prompt；只展示该图片生成时用户在面板里提交的输入快照，包括普通生成提示词、规范表单字段、角色设定、图标素材描述、快速编辑提示词、重绘提示词，以及角色规范 / 常规参考图 / 图标规范 / 编辑参考图等参考图卡片，并提供“复制信息”复制当前可见字段。参考图输入快照只保存 `refType/refId` 行引用，其中 `refType="project-resource"` 指向 `editor_project_resource.resourceId`，`refType="asset"` 指向 `editor_asset.assetId`；不得把图片 Data URL、普通 URL 或 `objectKey` 写入 `generationInputs.references`。旧数据或上传图片没有输入快照时显示 `-`，禁止回退展示内部 Prompt。
 - 对生成资源执行重绘时，在右侧创建新的生成结果图层，并自动调整视图显示原图和新图；重绘面板不因提交成功自动关闭，便于连续改提示词。重绘 / 改造输入框只允许从 `generationInputs.fields` 中恢复用户可见输入快照，例如普通生成提示词、视频描述、音效 `prompt`、背景音乐 `gpt_description_prompt`、角色设定、UI 用户输入、图标素材描述、规范表单和宣发素材字段；禁止回退展示资源 `prompt` / `actualPrompt` 中的后端拼接 Prompt、固定生成模板或模型默认提示词。没有用户输入快照的旧图层打开改造时保持空输入，等待用户重新填写。
 - 图片生成 / 修改统一经 api-server BFF 接入 VectorEngine。普通生成、生成规范和重绘保留既有 `gpt-image-2` 路径；图片快速编辑统一打开框选区域 + 单提示词 + 模型选择面板，默认沿用原图模型，不展示参考图或比例 / 尺寸控件；其中生成规范类图片固定 `16:9`、`2K`、`gpt-image-2`，面板底部用与可编辑面板一致的比例 / 尺寸 / 模型胶囊按钮展示固定参数，但按钮为禁用态，不允许在该面板改比例、尺寸或模型。`生成角色形象` 与 `生成图标素材` 支持 `nanobanana2`（`gemini-3.1-flash-image-preview`）和 `gpt-image-2`，默认 `nanobanana2`，并在两类面板之间沿用用户上次选择的模型；两类面板不展示抠图背景色或抠图模型选择；前端用户路径固定提交 `screenColor=auto` 和 `segModel=birefnet`，由后端自动决策具体抠图背景色，`anime-seg` 作为内部保留能力不在用户界面暴露。`nanobanana2` 走 `/v1beta/models/{model}:generateContent`，请求体写入 `generationConfig.imageConfig.aspectRatio/imageSize`；`gpt-image-2` 走 `/v1/images/generations` 或 `/v1/images/edits`，请求体按 VectorEngine 文档映射 `size`。宣发素材三个工作流（游戏首图、详情五图、运营海报）固定使用 `gpt-image-2`，面板模型胶囊为禁用态，不提供 `nanobanana2` 入口；前端按 workflow 同时提交 `outputSize`、`aspectRatio` 和 `imageSize`，其中游戏首图为 `720x540 / 4:3`、详情单图为 `720x1280 / 9:16`、运营海报为 `1280x720 / 16:9`；后端收到 `kind: "publication-material"` 时也强制归一为 `gpt-image-2` 生成和计费，生成回填图层优先使用生成占位的 `originalWidth/originalHeight`，即使上游回包尺寸漂移也不得把宣发素材卡片变成随机 `1:1` 或 `4:3`。纯文本生成走 `/api/editor/images/generations`，重绘在前端读入当前图层图片 Data URL 后走同一图片生成 BFF，并在原图右侧生成一张新图；普通图层重绘作为 `quick-edit` 参考图提交，角色图层重绘必须按 `kind: "character"` 提交，继续套用角色生成器提示词限定、透明 PNG 后处理和角色资产持久化。`生成视频` 走 `/api/editor/videos/generations`，前端模型入口仅展示 Seedance 2.0 Fast / Seedance 2.0 / Kling 3.0 / Kling 3.0 Omni，不展示 Veo 入口，默认 Seedance 2.0 Fast；视频参数按当前正式面板支持的比例、时长、清晰度和声音开关提交，且 Seedance Fast 与 Seedance 标准版必须按各自真实模型 ID 独立映射，不得混用。生成结果以视频图层加入画布。纯文本生成入口采用 Lovart 式画布内占位图 + 锚定生成输入框：点击生成图片后以当前视口世界中心为目标，经统一 placement 避让后创建选中的灰色占位框，输入框跟随占位框显示；待生成、生成中和失败后保留的占位图都必须继续支持拖动，生成完成时真实生成图或视频落在最新占位框位置，输入框继续跟随新生成图层；占位图失焦时隐藏高亮边框、左上角生成器名称和右上角原始尺寸，重新聚焦时再显示，且名称 / 尺寸在画布缩小时按 viewport 反向缩放保持屏幕尺寸稳定；点击所有图片 / 视频生成入口并确认请求开始后，必须隐藏对应设置面板，只保留画布内占位图或原图预览，并在预览上显示 Lovart 式生成中遮罩，避免“面板仍占屏”或“预览一起消失”。图片快速编辑和重绘在调用图片 BFF 前必须把当前图层图片源读取为图片 Data URL；视频素材快速编辑走视频生成 BFF，不允许走图片模型；角色动作的 `生成动画` 仍固定使用 `seedance2.0-fast` 动作 / 视频模型，角色动作素材的 `快速编辑` 按当前帧图片走图片编辑。前端不持有 provider 密钥；上游失败或配置缺失时恢复当前生成设置面板展示失败，不创建 mock 成功图。
-- 图片画布抠图分两类：手动去除背景面向用户任意图片，走登录态同源 BFF `POST /api/editor/images/background-removals` 并转发远端 BiRefNet；编辑器自己生成的标准纯色背景抠图资产在保存源图后统一调用独立 BgFilter 服务 `GENARRATIVE_EDITOR_BGFILTER_BASE_URL/remove-background`，默认 `http://58.87.105.82/bgfilter/remove-background`，默认请求超时 `45000ms`。角色形象生成、图标 spritesheet 生成和 UI 设计图素材提取的前端用户路径都固定把 `screenColor=auto` 注入请求体，但用户可见 `generationInputs.fields` 不再记录 `抠图背景色` 或 `抠图模型`；api-server 在组装 prompt 前调用背景决策模块，从 11 个候选色中选择具体 hex，最多重试 3 次，失败后兜底 `#CFEFFF`。后端仍保留手动 hex 解析能力供内部兼容。最终生图 prompt 和 BgFilter `screen_color` multipart 字段只接收解析后的具体 hex，不透传 `auto`。三条 BgFilter 路径还必须固定把默认 `segModel=birefnet` 传为 `seg_model`；后端仍保留识别 `anime-seg` 的内部兼容能力，但前端用户入口不展示也不提交该值。这里的 `birefnet` 只是 BgFilter 管线内部后端，不等同于手动去背景的独立 BiRefNet 服务。后端在调用 BgFilter 前必须先把带纯色背景 / 绿幕源图写入 OSS；若 BgFilter 请求失败、返回非成功状态、空图片或非法图片，api-server 对这些标准纯色背景生成图使用本地 `editor_green_screen` 按同一 `screenColor` 兜底去背；连续失败达到 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD=3` 后，冷却 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS=300` 秒内直接使用本地兜底。角色动作抽帧后的序列帧暂不接用户背景色选择，仍沿用 legacy `#00FF00` 绿幕和本地 `editor_green_screen` 透明化，不依赖 BiRefNet 或 BgFilter。BiRefNet 手动去背景服务地址为 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_BASE_URL/remove-background`，默认 `http://58.87.105.82/remove-background`；BgFilter 可选访问令牌来自 `GENARRATIVE_EDITOR_BGFILTER_TOKEN`，未配置时复用 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN`，所有令牌都只在服务端注入，前端不持有令牌。api-server 对上游结果做响应字节和图片尺寸上限保护，并先落 OSS / asset object，再返回 `imageSrc/objectKey/assetObjectId/taskId`；queue 模式下手动去背景进入 SpacetimeDB 外部生成队列，画布任务侧栏只展示服务器任务阶段，生成中才显示耗时，不显示百分比；有项目上下文时前端同时创建去背景生成占位并把 `canvasCompletion` 交给后端，完成后由后端写入结果图层和最新项目快照。
+- 图片画布抠图分两类：手动去除背景面向用户任意图片，走登录态同源 BFF `POST /api/editor/images/background-removals` 并转发远端 BiRefNet；编辑器自己生成的标准纯色背景抠图资产在保存源图后统一调用独立 BgFilter 服务 `GENARRATIVE_EDITOR_BGFILTER_BASE_URL/remove-background`，默认 `http://58.87.105.82/bgfilter/remove-background`，默认请求超时 `180000ms`（BgFilter CPU 推理）。角色形象生成、图标 spritesheet 生成和 UI 设计图素材提取的前端用户路径都固定把 `screenColor=auto` 注入请求体，但用户可见 `generationInputs.fields` 不再记录 `抠图背景色` 或 `抠图模型`；api-server 在组装 prompt 前调用背景决策模块，从 12 个候选色中选择具体 hex，最多重试 3 次，失败后兜底 `#CFEFFF`。后端仍保留手动 hex 解析能力供内部兼容。最终生图 prompt 和 BgFilter `screen_color` multipart 字段只接收解析后的具体 hex，不透传 `auto`。三条 BgFilter 路径还必须固定把默认 `segModel=birefnet` 传为 `seg_model`；后端仍保留识别 `anime-seg` 的内部兼容能力，但前端用户入口不展示也不提交该值。这里的 `birefnet` 只是 BgFilter 管线内部后端，不等同于手动去背景的独立 BiRefNet 服务。后端在调用 BgFilter 前必须先把带纯色背景 / 绿幕源图写入 OSS；BgFilter 请求失败、返回非成功状态、空图片或非法图片时，以及连续失败达到 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD=3` 后的 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS=300` 秒熔断期，api-server 都先调用阿里云通用抠图，只有阿里云失败才用本地 `editor_green_screen` 按同一 `screenColor` 兜底去背。角色动作生成的序列帧背景色已与生图统一：前端固定提交 `screenColor=auto`，后端视觉决策出具体 hex 并把源角色图合成到该背景色后再图生视频；抽帧后逐帧优先阿里云通用抠图，失败降级本地 `editor_green_screen`（按选定背景色，而非固定 `#00FF00`）。BiRefNet 手动去背景服务地址为 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_BASE_URL/remove-background`，默认 `http://58.87.105.82/remove-background`；BgFilter 可选访问令牌来自 `GENARRATIVE_EDITOR_BGFILTER_TOKEN`，未配置时复用 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN`，所有令牌都只在服务端注入，前端不持有令牌。api-server 对上游结果做响应字节和图片尺寸上限保护，并先落 OSS / asset object，再返回 `imageSrc/objectKey/assetObjectId/taskId`；queue 模式下手动去背景进入 SpacetimeDB 外部生成队列，画布任务侧栏只展示服务器任务阶段，生成中才显示耗时，不显示百分比；有项目上下文时前端同时创建去背景生成占位并把 `canvasCompletion` 交给后端，完成后由后端写入结果图层和最新项目快照。
 - 图片快速编辑面板只保留一个提示词输入框和模型选择，不展示额外参考图或比例 / 尺寸控件；原图 / 原素材作为 `/api/editor/images/edits` 的 `sourceImageSrc` 直接提交，不作为 `referenceImageSrcs`。打开快速编辑时画布必须自动平移缩放，让原素材完整落在可视区上半部分，底部面板固定出现在素材下方且不遮挡内容，竖屏 UI 素材也必须完整展示。快速编辑右侧显示矩形、椭圆、画笔框选工具，但进入时不默认启用；点击工具后显示选中态，再点同一工具取消启用。完成框选后，画布红色细框显示连续序号，提示词可按这些编号填写每个区域怎么改。点击 `修改` 后仍停留在当前快速编辑面板显示修改中，不创建独立 `Quick Edit Generator` 画布占位；生成成功后直接用结果覆盖原图图层，失败时保留当前面板并显示错误。
 - 底部生成类按钮每次点击都必须创建独立的画布生成对象；新建规范、角色形象或图标素材时，只切换当前编辑面板，不得销毁此前尚未生成或已生成后的其它生成对象状态。归档为非当前编辑对象的生成占位仍可拖动、删除和等待异步完成，完成 / 失败回写必须按生成对象 ID 读取最新占位状态，不能使用提交瞬间的旧快照。
 - 画布右上角提供自动隐藏任务侧栏。列表为空且侧栏关闭时只保留图标开关；生成或去背景任务进入时默认打开；用户可手动切换开关状态。
diff --git a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
index d48cd3f7a..679f32765 100644
--- a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
+++ b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
@@ -22,7 +22,7 @@ SpacetimeDB 版本口径：当前 Rust crate `spacetimedb`、`spacetimedb-sdk`
 
 - HTTP 服务：`api-server`。
 - 领域模块：`module-ai`、`module-assets`、`module-auth`、`module-bark-battle`、`module-big-fish`、`module-combat`、`module-creative-agent`、`module-editor-agent`、`module-custom-world`、`module-inventory`、`module-match3d`、`module-npc`、`module-progression`、`module-puzzle`、`module-quest`、`module-runtime`、`module-runtime-item`、`module-runtime-story`、`module-square-hole`、`module-story`、`module-visual-novel`。
-- 平台副作用：`platform-agent`、`platform-auth`、`platform-image`、`platform-llm`、`platform-oss`、`platform-wechat`、`platform-speech`。
+- 平台副作用：`platform-agent`、`platform-auth`、`platform-image`、`platform-llm`、`platform-matting`、`platform-oss`、`platform-wechat`、`platform-speech`。
 - 共享层：`shared-contracts`、`shared-kernel`、`shared-logging`。
 - SpacetimeDB：`spacetime-client`、`spacetime-module`。
 - 测试支撑：`tests-support`。
@@ -226,7 +226,7 @@ npm run check:server-rs-ddd
 
 - LLM：通用 LLM 门面继续使用 `GENARRATIVE_LLM_*`；创意 Agent `gpt-5.4-mini` Chat Completions 文本链路已于 2026-06 从 APIMart 迁移到 VectorEngine，使用 `VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY` 构造 OpenAI-compatible client，`api-server` 会把未带 `/v1` 的 VectorEngine base URL 规范化到 `/v1` 后请求 `/chat/completions`。通用 `/api/llm/chat/completions` 代理使用 `GENARRATIVE_LLM_PROVIDER=openai-compatible`、`GENARRATIVE_LLM_BASE_URL=https://api.vectorengine.cn/v1`、`GENARRATIVE_LLM_MODEL=gpt-5.4-mini`；未单独配置 `GENARRATIVE_LLM_API_KEY` 时可复用 `VECTOR_ENGINE_API_KEY`。`APIMART_BASE_URL` / `APIMART_API_KEY` 只作为历史残留，不再作为创意 Agent gpt-5.4-mini 客户端来源；后续排障时优先确认 VectorEngine `/v1/models`、`/v1/chat/completions` 和 `/v1/responses` 可用性。
 - 图片生成：VectorEngine `gpt-image-2` 图片 provider 归属 `platform-image`，密钥只在后端环境变量中；`api-server` 内的 `openai_image_generation.rs` 只是兼容调用面和外部失败审计桥接，不再承载 provider 协议实现。实际外部生成运行记录统一落 `tracking_event`，`event_key = external_generation_run`，metadata 记录开始 / 结束时间、耗时、状态、成功标记、失败原因、provider task id 和结果摘要，不再写回过时的 `ai_task`。DashScope 只按仍在使用的历史能力单独处理，不作为 GPT-image-2 兜底。VectorEngine `/v1/images/generations` 和 `/v1/images/edits` 上游 POST 使用 `libcurl` 发送；`reqwest` 只保留给参考图 URL 下载和响应中图片 URL 下载。`/v1/images/edits` 的 multipart 参考图必须作为 libcurl 文件上传 part 发送，字段名为 `image`，实现上使用 `Form::buffer(file_name, bytes)` 并设置 `Content-Type`；不能只用 `contents(...).filename(...)`，否则上游会把请求转码为缺少图片并返回 `image is required`。`request_send` 阶段的 curl timeout / connect error 按可重试传输错误处理，最多尝试 5 次，并使用指数退避加短抖动；排障时优先看 `attempt`、`max_attempts`、`retry_delay_ms`、`reference_image_bytes_total` 和 `request_params`，不要把 `SendRequest` 当成上游业务错误。
-- 编辑器抠图服务：手动 `POST /api/editor/images/background-removals` 继续代理独立 BiRefNet 服务，配置为 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_BASE_URL`、`GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN` 和 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_REQUEST_TIMEOUT_MS`。角色形象生成、图标 spritesheet 生成和 UI 设计图素材提取的生成后纯色背景透明化改走独立 BgFilter 服务，配置为 `GENARRATIVE_EDITOR_BGFILTER_BASE_URL`、`GENARRATIVE_EDITOR_BGFILTER_TOKEN` 和 `GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS`，默认 base URL 为 `http://58.87.105.82/bgfilter`，默认请求超时为 `45000ms`，token 未配置时复用 BiRefNet token。BgFilter 请求必须显式传 `screen_color=<screenColor>` 和 `seg_model=<segModel>`；前端用户路径不展示抠图模型选择并固定提交默认 `birefnet`，后端仍识别内部保留的 `anime-seg`，其中 `birefnet` 只表示 BgFilter 管线内部后端，不等同于手动去背景的独立 BiRefNet 服务。BgFilter 连续失败达到 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD`（默认 `3`）后，会在 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS`（默认 `300`）内直接使用本地 `editor_green_screen` 兜底，避免上游故障占住 worker。角色动作抽帧仍沿用 legacy `#00FF00` 和本地 `editor_green_screen` 透明化。
+- 编辑器抠图服务：手动 `POST /api/editor/images/background-removals` 继续代理独立 BiRefNet 服务，配置为 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_BASE_URL`、`GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN` 和 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_REQUEST_TIMEOUT_MS`。角色形象生成、图标 spritesheet 生成和 UI 设计图素材提取的生成后纯色背景透明化改走独立 BgFilter 服务，配置为 `GENARRATIVE_EDITOR_BGFILTER_BASE_URL`、`GENARRATIVE_EDITOR_BGFILTER_TOKEN` 和 `GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS`，默认 base URL 为 `http://58.87.105.82/bgfilter`，默认请求超时为 `180000ms`（BgFilter 当前为 CPU 推理，单次抠图较慢，必须留足超时），token 未配置时复用 BiRefNet token。BgFilter 请求必须显式传 `screen_color=<screenColor>` 和 `seg_model=<segModel>`；前端用户路径不展示抠图模型选择并固定提交默认 `birefnet`，后端仍识别内部保留的 `anime-seg`，其中 `birefnet` 只表示 BgFilter 管线内部后端，不等同于手动去背景的独立 BiRefNet 服务。BgFilter 调用失败，或连续失败达到 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD`（默认 `3`）并在 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS`（默认 `300`）内打开熔断时，均跳过或结束 BgFilter 调用后复用同一兜底链：先调用阿里云通用抠图，阿里云失败才使用本地 `editor_green_screen` 键色扣除；熔断期不得直接退化到本地兜底。角色动作视频生成的背景色已与生图链路统一：`screenColor=auto` 时由视觉 LLM（`gpt-5-mini`，Responses 协议、low 推理档）读源角色图自动决策，并经硬过滤器剔除与前景 / 皮肤撞色的候选，手动 hex 则尊重用户选择；透明源角色图在提交 Ark 图生视频前先合成到选定背景色实色，使视频背景等于抠图键色。抽帧后逐帧优先走阿里云通用抠图，失败时降级本地 `editor_green_screen` 键色兜底（按生成时选定的背景色，而非固定 `#00FF00`）。阿里云通用抠图配置为 `GENARRATIVE_ALIYUN_MATTING_ENABLED`、`GENARRATIVE_ALIYUN_MATTING_ENDPOINT`、`GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_ID`、`GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_SECRET` 和 `GENARRATIVE_ALIYUN_MATTING_REQUEST_TIMEOUT_MS`；未配置专用 AK/SK 时可复用 `ALIBABA_CLOUD_ACCESS_KEY_ID` / `ALIBABA_CLOUD_ACCESS_KEY_SECRET`，默认 endpoint 为 `imageseg.cn-shanghai.aliyuncs.com`。BgFilter 与阿里云抠图失败都写入 `external_api_call_failure` 审计。
 - Match3D 物品 sheet：关卡整图完成后走 VectorEngine `/v1/images/edits` multipart `image`，模型为 `gpt-image-2`，`2K 1:1` 输出 `10*10` spritesheet；物品 sheet prompt 固定要求单一纯绿色 `#00FF00 / RGB(0,255,0)` 绿幕背景，后端上传 OSS 前必须把绿幕扣成透明 PNG，并把透明整图写入 `itemSpritesheetImageSrc/itemSpritesheetImageObjectKey`。后端优先按透明 alpha 连通域从该 sheet 识别真实素材矩形并持久化 20 个物品、每个 5 个形态；识别数量不足时才回退 `10*10` 固定网格。通用系列素材图集的行列索引按每行 2 个物品计算，必须落在 `1..=10`，难度只决定运行态加载 3 / 9 / 15 / 20 种。
 - Match3D UI spritesheet 和背景派生图：关卡整图作为参考图并发生成 `1K 1:1` UI spritesheet 与 `1K 9:16` 背景图，模型均为 `gpt-image-2`。UI spritesheet prompt 固定要求单一纯绿色 `#00FF00 / RGB(0,255,0)` 绿幕背景，后端上传 OSS 前必须把绿幕扣成透明 PNG；背景图必须合成为全画幅不透明 PNG。
 - Match3D 1:1 容器 UI：VectorEngine `/v1/images/edits` multipart 参考图。该容器参考图是后端生图协议输入，必须通过 `include_bytes!` 随 `api-server` 编译进二进制，避免 API 单独发布或运行目录缺少 `public/` 时生成失败。
@@ -234,7 +234,7 @@ npm run check:server-rs-ddd
 - Hyper3D / Rodin：只保留后端安全代理和旧数据兼容；Rodin 提交、状态、下载和响应解析归属 `platform-hyper3d`，`api-server/src/hyper3d_generation.rs` 只做路由、配置和错误 envelope 映射；新 Match3D 草稿和批量新增不再生成 GLB。
 - 音频：视觉小说专用音频路由保留；VectorEngine Suno/Vidu provider 协议、任务提交/查询、音频 URL 提取、下载、MIME/extension 归一和 OSS put 请求准备归属 `platform-audio`。`api-server/src/vector_engine_audio_generation.rs` 只做路由、配置、计费、asset object confirm、entity binding 和错误 envelope 映射；拼图、抓大鹅和敲木鱼提示词生成音效入口暂时关闭，通用 `/api/creation/audio/*` 对这些目标返回 `410 Gone`。敲木鱼创作只接收上传 / 录音音频资产；前端选择或录音阶段只在浏览器本地处理待提交音频，统一限制裁切后最长 1 秒、裁掉前后声音过小片段，并用浏览器端近似响度算法平衡到 `-15 LKFS` 后做峰值保护。点击生成时才直传 OSS 并确认 `asset_object`，创作 JSON 只提交轻量 `WoodenFishAudioAsset`，不得继续上传 Data URL 音频；未提供时由 `api-server` 写回内置默认木鱼音 `/wooden-fish/default-hit-sound.mp3`。
 - OSS：私有 generated legacy path 进入浏览器前必须通过 `/api/assets/read-url` 换签；不要裸请求 `/generated-*`。前端如果收到同一 OSS bucket 的完整 `https://*.oss-*.aliyuncs.com/generated-*` 地址，也必须先归一为 legacy path 后走同一换签链路，避免裸连私有 bucket 403 或绕过签名缓存。OSS 签名、读签名、HEAD 和 PUT 的结构化日志由 `platform-oss` 输出，排查资产写入 / 确认失败时优先按 `operation`、`object_key` / `key_prefix`、`status_class`、`error_kind` 和 `elapsed_ms` 下钻。新上传 generated 私有对象默认写入 `Cache-Control: public, max-age=31536000, immutable`；旧对象若缺该头，只能依赖 `ETag` / `Last-Modified` 协商缓存，应通过 OSS 元数据刷新或 CDN 配置补齐，不要恢复 api-server 静态代理。`editor-agent/` 前缀只用于服务端内部读写画布 Agent 会话消息文档，不属于浏览器直传 legacy public prefix；`/api/assets/direct-upload-tickets` 必须拒绝 `legacyPrefix=editor-agent`，内部读取只允许 `editor-agent/{conversationId}.json` 形态。
-- 外部 API 失败审计：外部供应商调用未成功时，`api-server` 必须发送 OTLP 失败事件并写入 `tracking_event`。VectorEngine 图片 provider 在 `platform-image` 内输出结构化日志和 `PlatformImageFailureAudit`，覆盖 `request_send`、`response_body`、`upstream_status`、`response_parse`、`missing_image` 和 `image_download` 阶段；`api-server` 只把该 audit 映射成 `external_api_call_failure`，`scope_kind = module`、`scope_id = provider`、`module_key = external-api`。metadata 固定包含 provider、endpoint、operation、failureStage、statusCode、statusClass、timeout、retryable、errorMessage、latencyMs、promptChars、referenceImageCount、imageModel、rawExcerpt，以及在调用方可获得上下文时补充的 `userId`（触发者）和 `profileId`（草稿 / 作品 / 场景作用域）。图片生成入口应优先把 owner user id 和 profile id 透传到失败审计，不要只保留 provider 级聚合，否则很难按“谁触发、哪个作品触发”定位问题。入库优先复用 tracking outbox，outbox 不可写或保护阈值拒绝时回退同步写 SpacetimeDB；不得新增前端兜底或在 SpacetimeDB reducer 内做外部 I/O。
+- 外部 API 失败审计：外部供应商调用未成功时，`api-server` 必须发送 OTLP 失败事件并写入 `tracking_event`。VectorEngine 图片 provider 在 `platform-image` 内输出结构化日志和 `PlatformImageFailureAudit`，覆盖 `request_send`、`response_body`、`upstream_status`、`response_parse`、`missing_image` 和 `image_download` 阶段；编辑器 `screenColor=auto` 的 gpt-5-mini 背景色决策同样必须审计每次已发出的 LLM 调用失败，包括传输 / 超时、上游拒绝、响应体解析、空响应和返回候选外颜色；即使随后降级默认背景色并继续主流程也不得只记 warning。`api-server` 将这些失败映射成 `external_api_call_failure`，`scope_kind = module`、`scope_id = provider`、`module_key = external-api`。metadata 固定包含 provider、endpoint、operation、failureStage、statusCode、statusClass、timeout、retryable、errorMessage、latencyMs、promptChars、referenceImageCount、imageModel、rawExcerpt，以及在调用方可获得上下文时补充的 `userId`（触发者）和 `profileId`（草稿 / 作品 / 场景作用域）。图片生成入口应优先把 owner user id 和 profile id 透传到失败审计，不要只保留 provider 级聚合，否则很难按“谁触发、哪个作品触发”定位问题。入库优先复用 tracking outbox，outbox 不可写或保护阈值拒绝时回退同步写 SpacetimeDB；不得新增前端兜底或在 SpacetimeDB reducer 内做外部 I/O。
 - 外部生成运行记录：所有外部生成编排的完成态统一写入 `tracking_event`，`event_key = external_generation_run`，`scope_kind = module`，`scope_id = provider`，`module_key = external-generation`。metadata 固定包含 `runId`、`provider`、`operation`、`requestLabel`、`requestPayload`、`status`、`success`、`failureReason`、`providerRequestId`、`resultPayload`、`startedAtMicros`、`completedAtMicros` 和 `durationMs`。这类记录只用于运行审计和排障，不再走 `ai_task` 旧表。
 
 ## SpacetimeDB 表目录
diff --git a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
index 8bf64209d..498cee058 100644
--- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
+++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
@@ -61,7 +61,7 @@ Windows 本地如果已在 `%LOCALAPPDATA%\Genarrative\ffmpeg\bin` 安装 FFmpeg
 
 生产 worker 默认 `GENARRATIVE_EXTERNAL_GENERATION_WORKER_LEASE_SECONDS=600`，只覆盖 worker 心跳抖动和短暂断连窗口，不再把 lease 当成完整任务时长；默认 `GENARRATIVE_EXTERNAL_GENERATION_WORKER_JOB_TIMEOUT_SECONDS=900`，角色动画 / 视频类长任务使用 `GENARRATIVE_EXTERNAL_GENERATION_WORKER_LONG_JOB_TIMEOUT_SECONDS=1800`。worker 在单次尝试超过执行预算后会停止当前尝试、写入失败 / 重试状态并释放 worker 槽位；如果 SpacetimeDB 当时不可写，当前租约最多再保留到 lease 过期，之后任务重新变为可领取。生产部署和 provision 脚本会给 `/etc/genarrative/api-server.env` 与 `/etc/genarrative/external-generation-worker.env` 补齐这些变量；已有自定义值不覆盖，只会把历史旧默认 `3600` 迁移为 `600`。
 
-图片画布角色图、图标素材和 UI 素材提取在绿色 / 蓝色幕布去背景时优先调用 BgFilter；默认 `GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS=45000`，连续失败达到 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD=3` 后熔断 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS=300` 秒，熔断期直接走本地幕布色去背景兜底。修改这些变量后需要重启对应 `api-server` / worker 进程；排查时先从 worker 启动日志确认 lease 和 job timeout，再看 `editor_bgfilter_request_start`、`editor_bgfilter_fallback_to_local_screen_background_removal` 与 `editor_bgfilter_circuit_open_fallback_to_local_screen_background_removal` 日志。
+图片画布角色图、图标素材和 UI 素材提取在绿色 / 蓝色幕布去背景时优先调用 BgFilter；默认 `GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS=180000`，连续失败达到 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD=3` 后熔断 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS=300` 秒。BgFilter 调用失败和熔断期均先走阿里云通用抠图，只有阿里云失败才走本地幕布色去背景兜底。阿里云这层默认 `GENARRATIVE_ALIYUN_MATTING_ENABLED=true`，但必须在 `api-server.env` 填入 `GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_ID` / `GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_SECRET`（或标准 SDK 命名 `ALIBABA_CLOUD_ACCESS_KEY_ID` / `ALIBABA_CLOUD_ACCESS_KEY_SECRET`）才会真正启用；AccessKey 缺失时启动日志会打印「阿里云抠图 AccessKey 未配置，跳过抠图客户端初始化」，抠图直接塌成 BgFilter→本地两级，`npm run check:api-server-env` 也会给出对应告警。修改这些变量后需要重启对应 `api-server` / worker 进程；排查时先从 worker 启动日志确认 lease 和 job timeout，再看 `editor_bgfilter_request_start`、`editor_bgfilter_fallback_to_aliyun_matting`、`editor_bgfilter_circuit_open_fallback_to_aliyun_matting`，以及阿里云失败后的 `editor_aliyun_matting_fallback_to_local_screen_background_removal` 日志。
 
 `我的` 页签或排障面板展示队列等待时，只读取 BFF 队列接口：`GET /api/runtime/external-generation/queue-overview` 查看当前用户可见队列概览，`GET /api/runtime/external-generation/jobs/{jobId}` 查看单 job 状态。生成页 / 进度页不承接队列概览，只展示当前玩法业务进度；队列接口只提供等待 / 运行 / 失败 / 完成状态补充，最终草稿、作品和结果页仍要轮询对应玩法 session/detail 接口收敛到 ready 或 failed；不要直接查询 `external_generation_job` private table，也不要把 worker 内部 payload 暴露到前端。
 
diff --git a/docs/【编辑器】模型定价配置管理方案-2026-06-22.md b/docs/【编辑器】模型定价配置管理方案-2026-06-22.md
index 3cbc833cf..d9c3e5873 100644
--- a/docs/【编辑器】模型定价配置管理方案-2026-06-22.md
+++ b/docs/【编辑器】模型定价配置管理方案-2026-06-22.md
@@ -55,7 +55,7 @@
 - `GET /admin/api/editor-generation-pricing`：后台读取当前模型定价。
 - `POST /admin/api/editor-generation-pricing`：后台保存完整模型定价，并写入 override 文件。
 
-后端 `AppState` 启动时加载默认配置和 override。所有会调用外部生成 provider 的编辑器生成请求都必须由后端以运行时配置重新计算价格，前端请求不提交价格字段；计算完成后统一进入 `execute_billable_asset_operation_with_cost` 预扣泥点，预扣失败不得继续调用上游。普通图片、规范、角色、UI 设计、宣发素材、快速编辑 / 图片修改、图标 spritesheet、UI 设计图提取素材、视频、角色动作、音效和背景音乐均遵循该规则。需要向前端展示实际扣费时，由后端在响应中返回 `priceMudPoints`。
+后端 `AppState` 启动时加载默认配置和 override。所有会调用外部生成 provider 的编辑器生成请求都必须由后端以运行时配置重新计算价格，前端请求不提交价格字段；计算完成后统一进入 `execute_billable_asset_operation_with_cost` 预扣泥点，预扣失败不得继续调用上游。普通图片、规范、角色、UI 设计、宣发素材、快速编辑 / 图片修改、图标 spritesheet、UI 设计图提取素材、视频、角色动作、音效和背景音乐均遵循该规则。背景色决策（gpt-5-mini）本身也是一次上游调用，同样必须在预扣泥点之后发起：预扣前只做颜色无关的算价 / 校验（动画用默认色占位算价），决策放进 billable 闭包，余额不足则决策不跑、决策失败走失败退款。需要向前端展示实际扣费时，由后端在响应中返回 `priceMudPoints`。
 
 ## 管理端
 
diff --git a/docs/【编辑器】画板UI设计图生成入口设计-2026-06-17.md b/docs/【编辑器】画板UI设计图生成入口设计-2026-06-17.md
index 84a4f9de7..1829eb851 100644
--- a/docs/【编辑器】画板UI设计图生成入口设计-2026-06-17.md
+++ b/docs/【编辑器】画板UI设计图生成入口设计-2026-06-17.md
@@ -28,7 +28,7 @@
 - 支持自定义画面比例和大小尺寸。
 - 模型固定为 `gpt-image-2`，模型展示对齐角色规范面板底部固定模型样式，不响应点击、不弹出模型切换菜单；历史草稿如果残留其他模型，提交时也必须强制改为 `gpt-image-2`。
 - 默认画面比例为 `16:9`，默认大小为 `1K`。
-- UI 素材提取面板不展示抠图背景色或抠图模型选择；前端用户路径固定提交 `screenColor=auto` 和 `segModel=birefnet`。后端先在 11 个候选色中自动决策具体 hex，最多重试 3 次，失败兜底 `#CFEFFF`；后端调用 BgFilter 时只把解析后的具体 hex 作为 `screen_color` 传入。后端仍识别内部保留的 `anime-seg`，但该选项不对用户可见。
+- UI 素材提取面板不展示抠图背景色或抠图模型选择；前端用户路径固定提交 `screenColor=auto` 和 `segModel=birefnet`。后端先在 12 个候选色中自动决策具体 hex，最多重试 3 次，失败兜底 `#CFEFFF`；后端调用 BgFilter 时只把解析后的具体 hex 作为 `screen_color` 传入。后端仍识别内部保留的 `anime-seg`，但该选项不对用户可见。
 
 ## 提示词契约
 
diff --git a/docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md b/docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md
index d55d5a2c2..fe9c1bec7 100644
--- a/docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md
+++ b/docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md
@@ -153,7 +153,7 @@
 - 后端 prompt 使用以下固定骨架，并把面板输入追加到 `动作描述：` 后：
 
 ```text
-生成游戏角色动画，参考图作为首帧和尾帧，画面中心构图，角色主体完整置于画面中央，禁止镜头透视，禁止特写。背景固定为单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕，只作为抠像底色；绿幕背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具；角色主体不得带绿色描边、绿色投影或绿色反光；禁止出现建筑、室内布景、风景、地面道具、漂浮物、烟雾叙事元素、文字或其他角色以外的场景内容。
+生成游戏角色动画，参考图作为首帧和尾帧，画面中心构图，角色主体完整置于画面中央，禁止镜头透视，禁止特写。背景使用后端自动决策出的单一纯色抠像底色；纯色背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具；角色主体不得带与抠像底色相近的描边、投影或反光；禁止出现建筑、室内布景、风景、地面道具、漂浮物、烟雾叙事元素、文字或其他角色以外的场景内容。
 动作描述：
 <用户输入的动画描述>
 ```
@@ -162,9 +162,9 @@
 
 - 视频生成完成后，后端按面板选择抽取对应帧数：`32`、`40` 或 `48`。
 - 抽帧采样必须按目标帧数预留视频尾部安全步长，例如 `32帧·4秒` 最后一帧采 `3.875s`，避免 FFmpeg 在尾点附近返回成功但输出 `0` 帧。
-- 每帧必须先把带 legacy `#00FF00` 绿幕源图写入 OSS，再执行 `editor_green_screen` 统一绿幕去背，输出透明背景 PNG。角色动作暂不接入角色 / 图标生图的 `screenColor` 选择。
+- 每帧必须先把带自动决策纯色背景的源图写入 OSS，再优先调用阿里云通用抠图输出透明背景 PNG；阿里云失败时降级执行本地 `editor_green_screen`，并按同一次生成已选定的 `screenColor` 去背。
 - 抽帧结果写入 OSS，并返回帧路径、帧尺寸、帧数、fps、预览视频路径、模型、价格和实际 prompt。
 - 画板前端回填角色动作结果时，必须以 `frames[0].imageSrc` 创建 `mediaType: "image-sequence"`、`assetKind: "character-animation"` 图层，并把完整 `frames` 保存为图层 `imageSequenceFrames`；`previewVideoPath` 只保留为上游预览视频来源，不作为画布主媒体。
 - 角色动作图层在画布中使用序列帧播放器循环展示透明 PNG 帧；刷新恢复时必须继续读取 `imageSequenceFrames`，不能回退到 `<video>` 预览。
 - 点击角色动作图层下载时，必须打包下载序列帧 ZIP；画布素材 ZIP 导出时，角色动作写入 `sequences/<编号-标题>/frames/`，而不是导出预览视频。
-- `frames[0].imageSrc` 仍作为后续动作素材快速编辑或再次生成动作时的透明帧来源。该规则不得跳过后端原有的视频生成、抽帧、绿幕去背和帧素材落盘流程。
+- `frames[0].imageSrc` 仍作为后续动作素材快速编辑或再次生成动作时的透明帧来源。该规则不得跳过后端原有的视频生成、抽帧、透明化处理和帧素材落盘流程。
diff --git a/packages/shared/src/assets/chromaKey.test.ts b/packages/shared/src/assets/chromaKey.test.ts
deleted file mode 100644
index 125bb5393..000000000
--- a/packages/shared/src/assets/chromaKey.test.ts
+++ /dev/null
@@ -1,67 +0,0 @@
-import { describe, expect, it } from 'vitest';
-
-import { removeBackgroundFromRgba } from './chromaKey';
-
-function createSolidRgbaBuffer({
-  width,
-  height,
-  color,
-}: {
-  width: number;
-  height: number;
-  color: [number, number, number, number];
-}) {
-  const pixels = new Uint8ClampedArray(width * height * 4);
-  for (let index = 0; index < width * height; index += 1) {
-    pixels.set(color, index * 4);
-  }
-  return pixels;
-}
-
-function setPixel(
-  pixels: Uint8ClampedArray,
-  width: number,
-  x: number,
-  y: number,
-  color: [number, number, number, number],
-) {
-  pixels.set(color, (y * width + x) * 4);
-}
-
-function alphaAt(
-  pixels: Uint8ClampedArray,
-  width: number,
-  x: number,
-  y: number,
-) {
-  return pixels[(y * width + x) * 4 + 3] ?? 0;
-}
-
-describe('chromaKey', () => {
-  it('removes near-white canvas background without breaking an enclosed white character', () => {
-    const width = 9;
-    const height = 9;
-    const pixels = createSolidRgbaBuffer({
-      width,
-      height,
-      color: [250, 250, 250, 255],
-    });
-
-    for (let y = 2; y <= 6; y += 1) {
-      for (let x = 2; x <= 6; x += 1) {
-        setPixel(pixels, width, x, y, [92, 80, 72, 255]);
-      }
-    }
-    for (let y = 3; y <= 5; y += 1) {
-      for (let x = 3; x <= 5; x += 1) {
-        setPixel(pixels, width, x, y, [246, 246, 244, 255]);
-      }
-    }
-
-    expect(removeBackgroundFromRgba(pixels, width, height)).toBe(true);
-
-    expect(alphaAt(pixels, width, 0, 0)).toBe(0);
-    expect(alphaAt(pixels, width, 4, 4)).toBe(255);
-    expect(alphaAt(pixels, width, 2, 2)).toBeGreaterThan(200);
-  });
-});
diff --git a/packages/shared/src/assets/chromaKey.ts b/packages/shared/src/assets/chromaKey.ts
deleted file mode 100644
index 7b517cc66..000000000
--- a/packages/shared/src/assets/chromaKey.ts
+++ /dev/null
@@ -1,478 +0,0 @@
-export type MutableRgbaBuffer = Uint8Array | Uint8ClampedArray;
-
-const SOFT_EDGE_ALPHA_THRESHOLD = 224;
-const FOREGROUND_NEIGHBOR_ALPHA_THRESHOLD = 96;
-
-function clamp01(value: number) {
-  return Math.max(0, Math.min(1, value));
-}
-
-function lerp(from: number, to: number, t: number) {
-  return from + (to - from) * clamp01(t);
-}
-
-function computeGreenBackgroundScore(
-  red: number,
-  green: number,
-  blue: number,
-  alpha: number,
-) {
-  if (alpha === 0) {
-    return 1;
-  }
-
-  const greenLead = green - Math.max(red, blue);
-  if (green < 52 || greenLead <= 8) {
-    return 0;
-  }
-
-  const greenRatio = green / Math.max(1, red + blue);
-  if (greenRatio <= 0.52) {
-    return 0;
-  }
-
-  return clamp01(
-    ((green - 52) / 168) * 0.22 +
-      ((greenLead - 8) / 96) * 0.53 +
-      ((greenRatio - 0.52) / 0.82) * 0.25,
-  );
-}
-
-function computeWhiteBackgroundScore(
-  red: number,
-  green: number,
-  blue: number,
-  alpha: number,
-) {
-  if (alpha === 0) {
-    return 1;
-  }
-
-  const maxChannel = Math.max(red, green, blue);
-  const minChannel = Math.min(red, green, blue);
-  const average = (red + green + blue) / 3;
-  if (average < 188 || minChannel < 168) {
-    return 0;
-  }
-
-  const spread = maxChannel - minChannel;
-  const neutrality = 1 - clamp01((spread - 6) / 34);
-  const brightness = clamp01((average - 188) / 55);
-  const floor = clamp01((minChannel - 168) / 60);
-  return clamp01(neutrality * (brightness * 0.85 + floor * 0.15));
-}
-
-function collectForegroundNeighborColor(
-  pixels: MutableRgbaBuffer,
-  width: number,
-  height: number,
-  x: number,
-  y: number,
-  backgroundMask: Uint8Array,
-  backgroundHints: Float32Array,
-) {
-  let totalWeight = 0;
-  let totalRed = 0;
-  let totalGreen = 0;
-  let totalBlue = 0;
-
-  for (let offsetY = -2; offsetY <= 2; offsetY += 1) {
-    for (let offsetX = -2; offsetX <= 2; offsetX += 1) {
-      if (offsetX === 0 && offsetY === 0) {
-        continue;
-      }
-
-      const nextX = x + offsetX;
-      const nextY = y + offsetY;
-      if (nextX < 0 || nextX >= width || nextY < 0 || nextY >= height) {
-        continue;
-      }
-
-      const nextPixelIndex = nextY * width + nextX;
-      if (backgroundMask[nextPixelIndex]) {
-        continue;
-      }
-
-      if ((backgroundHints[nextPixelIndex] ?? 0) >= 0.18) {
-        continue;
-      }
-
-      const nextOffset = nextPixelIndex * 4;
-      const nextAlpha = pixels[nextOffset + 3] ?? 0;
-      if (nextAlpha < FOREGROUND_NEIGHBOR_ALPHA_THRESHOLD) {
-        continue;
-      }
-
-      const distance = Math.abs(offsetX) + Math.abs(offsetY);
-      const weight =
-        (nextAlpha / 255) *
-        (distance <= 1 ? 1.8 : distance === 2 ? 1.2 : 0.7);
-
-      totalWeight += weight;
-      totalRed += (pixels[nextOffset] ?? 0) * weight;
-      totalGreen += (pixels[nextOffset + 1] ?? 0) * weight;
-      totalBlue += (pixels[nextOffset + 2] ?? 0) * weight;
-    }
-  }
-
-  if (totalWeight <= 0) {
-    return null;
-  }
-
-  return {
-    red: Math.round(totalRed / totalWeight),
-    green: Math.round(totalGreen / totalWeight),
-    blue: Math.round(totalBlue / totalWeight),
-  };
-}
-
-export function removeBackgroundFromRgba(
-  pixels: MutableRgbaBuffer,
-  width: number,
-  height: number,
-) {
-  const pixelCount = width * height;
-  if (pixelCount <= 0) {
-    return false;
-  }
-
-  const backgroundMask = new Uint8Array(pixelCount);
-  const greenScores = new Float32Array(pixelCount);
-  const whiteScores = new Float32Array(pixelCount);
-  const backgroundHints = new Float32Array(pixelCount);
-  const queue: number[] = [];
-  let queueIndex = 0;
-  let changed = false;
-
-  for (let pixelIndex = 0; pixelIndex < pixelCount; pixelIndex += 1) {
-    const offset = pixelIndex * 4;
-    const red = pixels[offset] ?? 0;
-    const green = pixels[offset + 1] ?? 0;
-    const blue = pixels[offset + 2] ?? 0;
-    const alpha = pixels[offset + 3] ?? 0;
-    const greenScore = computeGreenBackgroundScore(red, green, blue, alpha);
-    const whiteScore = computeWhiteBackgroundScore(red, green, blue, alpha);
-    const transparencyHint = clamp01((56 - alpha) / 56) * 0.75;
-
-    greenScores[pixelIndex] = greenScore;
-    whiteScores[pixelIndex] = whiteScore;
-    backgroundHints[pixelIndex] = Math.max(
-      greenScore,
-      whiteScore,
-      transparencyHint,
-    );
-  }
-
-  const trySeedBackground = (pixelIndex: number) => {
-    if (backgroundMask[pixelIndex]) {
-      return;
-    }
-
-    const offset = pixelIndex * 4;
-    const alpha = pixels[offset + 3] ?? 0;
-    const strongCandidate =
-      alpha < 40 ||
-      (greenScores[pixelIndex] ?? 0) > 0.12 ||
-      (whiteScores[pixelIndex] ?? 0) > 0.32;
-
-    if (!strongCandidate) {
-      return;
-    }
-
-    backgroundMask[pixelIndex] = 1;
-    queue.push(pixelIndex);
-  };
-
-  for (let x = 0; x < width; x += 1) {
-    trySeedBackground(x);
-    trySeedBackground((height - 1) * width + x);
-  }
-
-  for (let y = 1; y < height - 1; y += 1) {
-    trySeedBackground(y * width);
-    trySeedBackground(y * width + width - 1);
-  }
-
-  while (queueIndex < queue.length) {
-    const pixelIndex = queue[queueIndex]!;
-    queueIndex += 1;
-
-    const x = pixelIndex % width;
-    const y = Math.floor(pixelIndex / width);
-    const neighborIndexes = [
-      x > 0 ? pixelIndex - 1 : -1,
-      x + 1 < width ? pixelIndex + 1 : -1,
-      y > 0 ? pixelIndex - width : -1,
-      y + 1 < height ? pixelIndex + width : -1,
-    ];
-
-    for (const nextPixelIndex of neighborIndexes) {
-      if (nextPixelIndex < 0 || backgroundMask[nextPixelIndex]) {
-        continue;
-      }
-
-      const nextOffset = nextPixelIndex * 4;
-      const nextAlpha = pixels[nextOffset + 3] ?? 0;
-      const nextGreenScore = greenScores[nextPixelIndex] ?? 0;
-      const nextWhiteScore = whiteScores[nextPixelIndex] ?? 0;
-      const nextHint = backgroundHints[nextPixelIndex] ?? 0;
-      const reachableSoftEdge =
-        nextHint > 0.08 &&
-        nextAlpha < SOFT_EDGE_ALPHA_THRESHOLD &&
-        (nextGreenScore > 0.04 || nextWhiteScore > 0.08 || nextAlpha < 180);
-
-      if (
-        nextAlpha < 40 ||
-        nextGreenScore > 0.12 ||
-        nextWhiteScore > 0.32 ||
-        reachableSoftEdge
-      ) {
-        backgroundMask[nextPixelIndex] = 1;
-        queue.push(nextPixelIndex);
-      }
-    }
-  }
-
-  for (let iteration = 0; iteration < 2; iteration += 1) {
-    const expandedMask = new Uint8Array(backgroundMask);
-
-    for (let y = 0; y < height; y += 1) {
-      for (let x = 0; x < width; x += 1) {
-        const pixelIndex = y * width + x;
-        if (expandedMask[pixelIndex]) {
-          continue;
-        }
-
-        const alpha = pixels[pixelIndex * 4 + 3] ?? 0;
-        const hint = backgroundHints[pixelIndex] ?? 0;
-        if (alpha >= SOFT_EDGE_ALPHA_THRESHOLD || hint <= 0.06) {
-          continue;
-        }
-
-        let adjacentBackgroundCount = 0;
-        for (let offsetY = -1; offsetY <= 1; offsetY += 1) {
-          for (let offsetX = -1; offsetX <= 1; offsetX += 1) {
-            if (offsetX === 0 && offsetY === 0) {
-              continue;
-            }
-
-            const nextX = x + offsetX;
-            const nextY = y + offsetY;
-            if (nextX < 0 || nextX >= width || nextY < 0 || nextY >= height) {
-              continue;
-            }
-
-            if (backgroundMask[nextY * width + nextX]) {
-              adjacentBackgroundCount += 1;
-            }
-          }
-        }
-
-        if (
-          adjacentBackgroundCount >= 2 ||
-          (adjacentBackgroundCount >= 1 && hint > 0.18)
-        ) {
-          expandedMask[pixelIndex] = 1;
-        }
-      }
-    }
-
-    backgroundMask.set(expandedMask);
-  }
-
-  for (let y = 0; y < height; y += 1) {
-    for (let x = 0; x < width; x += 1) {
-      const pixelIndex = y * width + x;
-      if (!backgroundMask[pixelIndex]) {
-        continue;
-      }
-
-      const offset = pixelIndex * 4;
-      const alpha = pixels[offset + 3] ?? 0;
-      if (alpha === 0) {
-        continue;
-      }
-
-      const matteScore = Math.max(
-        backgroundHints[pixelIndex] ?? 0,
-        greenScores[pixelIndex] ?? 0,
-        whiteScores[pixelIndex] ?? 0,
-      );
-
-      let foregroundSupport = 0;
-      for (let offsetY = -1; offsetY <= 1; offsetY += 1) {
-        for (let offsetX = -1; offsetX <= 1; offsetX += 1) {
-          if (offsetX === 0 && offsetY === 0) {
-            continue;
-          }
-
-          const nextX = x + offsetX;
-          const nextY = y + offsetY;
-          if (nextX < 0 || nextX >= width || nextY < 0 || nextY >= height) {
-            continue;
-          }
-
-          const nextPixelIndex = nextY * width + nextX;
-          if (backgroundMask[nextPixelIndex]) {
-            continue;
-          }
-
-          const nextAlpha = pixels[nextPixelIndex * 4 + 3] ?? 0;
-          if (nextAlpha >= FOREGROUND_NEIGHBOR_ALPHA_THRESHOLD) {
-            foregroundSupport += 1;
-          }
-        }
-      }
-
-      let nextAlpha = alpha;
-      if (matteScore > 0.9 || foregroundSupport === 0) {
-        nextAlpha = 0;
-      } else if (matteScore > 0.72 && foregroundSupport <= 1) {
-        nextAlpha = Math.min(alpha, Math.round(alpha * 0.08));
-      } else {
-        nextAlpha = Math.min(
-          alpha,
-          Math.round(alpha * Math.max(0.08, 1 - matteScore * 0.95)),
-        );
-      }
-
-      if (foregroundSupport >= 3 && matteScore < 0.55) {
-        nextAlpha = Math.max(nextAlpha, Math.round(alpha * 0.22));
-      }
-
-      if (nextAlpha < 10) {
-        nextAlpha = 0;
-      }
-
-      if (nextAlpha !== alpha) {
-        pixels[offset + 3] = nextAlpha;
-        changed = true;
-      }
-    }
-  }
-
-  for (let y = 0; y < height; y += 1) {
-    for (let x = 0; x < width; x += 1) {
-      const pixelIndex = y * width + x;
-      const offset = pixelIndex * 4;
-      const alpha = pixels[offset + 3] ?? 0;
-      if (alpha === 0) {
-        continue;
-      }
-
-      let touchesTransparentEdge = false;
-      for (let offsetY = -1; offsetY <= 1; offsetY += 1) {
-        for (let offsetX = -1; offsetX <= 1; offsetX += 1) {
-          if (offsetX === 0 && offsetY === 0) {
-            continue;
-          }
-
-          const nextX = x + offsetX;
-          const nextY = y + offsetY;
-          if (nextX < 0 || nextX >= width || nextY < 0 || nextY >= height) {
-            touchesTransparentEdge = true;
-            continue;
-          }
-
-          const nextPixelIndex = nextY * width + nextX;
-          if (
-            backgroundMask[nextPixelIndex] ||
-            (pixels[nextPixelIndex * 4 + 3] ?? 0) < 16
-          ) {
-            touchesTransparentEdge = true;
-          }
-        }
-      }
-
-      if (!touchesTransparentEdge) {
-        continue;
-      }
-
-      const greenScore = greenScores[pixelIndex] ?? 0;
-      const whiteScore = whiteScores[pixelIndex] ?? 0;
-      const contamination = Math.max(
-        greenScore,
-        whiteScore,
-        backgroundMask[pixelIndex] ? 0.35 : 0,
-        alpha < 220 ? ((220 - alpha) / 220) * 0.25 : 0,
-      );
-
-      if (contamination < 0.06) {
-        continue;
-      }
-
-      let red = pixels[offset] ?? 0;
-      let green = pixels[offset + 1] ?? 0;
-      let blue = pixels[offset + 2] ?? 0;
-      const sample = collectForegroundNeighborColor(
-        pixels,
-        width,
-        height,
-        x,
-        y,
-        backgroundMask,
-        backgroundHints,
-      );
-      const blend = clamp01(
-        Math.max(contamination * 0.82, touchesTransparentEdge ? 0.22 : 0),
-      );
-
-      if (sample) {
-        red = Math.round(lerp(red, sample.red, blend));
-        green = Math.round(lerp(green, sample.green, blend));
-        blue = Math.round(lerp(blue, sample.blue, blend));
-
-        if (greenScore > 0.04) {
-          green = Math.min(green, sample.green + 18);
-        }
-
-        if (whiteScore > 0.1) {
-          red = Math.min(red, sample.red + 26);
-          green = Math.min(green, sample.green + 26);
-          blue = Math.min(blue, sample.blue + 26);
-        }
-      } else {
-        if (greenScore > 0.04) {
-          green = Math.max(
-            Math.max(red, blue),
-            Math.round(green - (green - Math.max(red, blue)) * 0.78),
-          );
-        }
-
-        if (whiteScore > 0.12) {
-          const spread = Math.max(red, green, blue) - Math.min(red, green, blue);
-          if (spread < 20) {
-            const tonedValue = Math.round(((red + green + blue) / 3) * 0.88);
-            red = Math.min(red, tonedValue);
-            green = Math.min(green, tonedValue);
-            blue = Math.min(blue, tonedValue);
-          }
-        }
-      }
-
-      let nextAlpha = alpha;
-      const edgeFade = Math.max(greenScore * 0.35, whiteScore * 0.28);
-      if (edgeFade > 0.08) {
-        nextAlpha = Math.min(alpha, Math.round(alpha * (1 - edgeFade)));
-        if (nextAlpha < 10) {
-          nextAlpha = 0;
-        }
-      }
-
-      if (
-        red !== (pixels[offset] ?? 0) ||
-        green !== (pixels[offset + 1] ?? 0) ||
-        blue !== (pixels[offset + 2] ?? 0) ||
-        nextAlpha !== alpha
-      ) {
-        pixels[offset] = red;
-        pixels[offset + 1] = green;
-        pixels[offset + 2] = blue;
-        pixels[offset + 3] = nextAlpha;
-        changed = true;
-      }
-    }
-  }
-
-  return changed;
-}
diff --git a/packages/shared/src/assets/qwenSprite.ts b/packages/shared/src/assets/qwenSprite.ts
deleted file mode 100644
index 67957218c..000000000
--- a/packages/shared/src/assets/qwenSprite.ts
+++ /dev/null
@@ -1 +0,0 @@
-export * from '../prompts/qwenSprite.js';
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index cc84c6f11..23bbb0c45 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -1,4 +1,3 @@
-export * from './assets/qwenSprite';
 export * from './contracts/auth';
 export type * from './contracts/bigFish';
 export * from './contracts/common';
diff --git a/packages/shared/src/prompts/qwenSprite.ts b/packages/shared/src/prompts/qwenSprite.ts
deleted file mode 100644
index 560a22b45..000000000
--- a/packages/shared/src/prompts/qwenSprite.ts
+++ /dev/null
@@ -1,176 +0,0 @@
-/**
- * 共享 sprite / 角色资产正式 prompt 模板。
- *
- * 这份脚本属于“正式模型 prompt 模板层”，不负责从角色卡里挑默认文本。
- * 它的定位是：
- * - 给后端角色主图生成链路提供标准主图 prompt 骨架
- * - 给后端角色动作视频生成链路提供标准动作 prompt 骨架
- *
- * 当前角色资产主链中的关系是：
- * 1. 前端或 Rust 后端先拿到一段较短的描述文本
- * 2. 当前角色资产链路调用本文件 buildMasterPrompt / buildVideoActionPrompt
- *    把短描述扩成正式给模型吃的 prompt
- *
- * 因此本文件不要承载“角色卡字段挑选”或“UI 默认值”职责，
- * 只维护共享的正式 prompt 骨架与动作模板。
- */
-export type QwenSpriteActionTemplateId =
-  | 'idle'
-  | 'run'
-  | 'attack_slash'
-  | 'hurt'
-  | 'die';
-
-export type QwenSpriteActionTemplate = {
-  id: QwenSpriteActionTemplateId;
-  label: string;
-  loop: boolean;
-  defaultFps: number;
-  bodyTravel: string;
-  weaponRule: string;
-  sequenceLines: [string, string, string, string];
-  ending: string;
-};
-
-export const QWEN_SPRITE_ACTION_TEMPLATES: QwenSpriteActionTemplate[] = [
-  {
-    id: 'idle',
-    label: '待机循环',
-    loop: true,
-    defaultFps: 8,
-    bodyTravel: '原地',
-    weaponRule: '武器始终在主手，位置稳定',
-    sequenceLines: [
-      '1-4 帧：稳定站姿，轻微呼吸起伏',
-      '5-8 帧：胸腔与肩膀轻微抬起，衣摆极轻微变化',
-      '9-12 帧：呼气回落，重心恢复',
-      '13-16 帧：逐渐回到与首帧接近的站姿',
-    ],
-    ending: '第 16 帧自然衔接第 1 帧',
-  },
-  {
-    id: 'run',
-    label: '奔跑循环',
-    loop: true,
-    defaultFps: 12,
-    bodyTravel: '小幅前移但角色中心基本固定',
-    weaponRule: '武器始终在主手，不换手',
-    sequenceLines: [
-      '1-4 帧：右腿前摆，左腿后蹬，身体略前倾',
-      '5-8 帧：双腿交叉经过身体下方，手臂反向摆动',
-      '9-12 帧：左腿前摆，右腿后蹬，继续前倾',
-      '13-16 帧：完成另一半跑步循环并回到可接第 1 帧的状态',
-    ],
-    ending: '第 16 帧能无缝接回第 1 帧',
-  },
-  {
-    id: 'attack_slash',
-    label: '横斩攻击',
-    loop: false,
-    defaultFps: 12,
-    bodyTravel: '中幅前探',
-    weaponRule: '右手持武器，始终右手，不换手',
-    sequenceLines: [
-      '1-4 帧：轻微收身蓄力，武器向后收',
-      '5-8 帧：重心前压，挥击开始',
-      '9-12 帧：斩击达到最大幅度，动作力量最强',
-      '13-16 帧：顺势收招，回到可接下一动作的稳定姿态',
-    ],
-    ending: '第 16 帧停在收招后稳定姿态',
-  },
-  {
-    id: 'hurt',
-    label: '受击后仰',
-    loop: false,
-    defaultFps: 10,
-    bodyTravel: '原地或极小后仰',
-    weaponRule: '武器不要脱手，不要换手',
-    sequenceLines: [
-      '1-4 帧：突然受击，头肩后仰',
-      '5-8 帧：身体失衡最明显',
-      '9-12 帧：手臂和武器随惯性摆动',
-      '13-16 帧：逐渐恢复到勉强站稳的姿态',
-    ],
-    ending: '第 16 帧能接回 idle 或下一个动作',
-  },
-  {
-    id: 'die',
-    label: '倒地死亡',
-    loop: false,
-    defaultFps: 8,
-    bodyTravel: '明显倒地位移',
-    weaponRule: '武器不可瞬间消失',
-    sequenceLines: [
-      '1-4 帧：受创失衡，重心被打断',
-      '5-8 帧：身体明显下坠或后仰',
-      '9-12 帧：倒地过程完成，动作幅度最大',
-      '13-16 帧：停在清晰的终止姿态',
-    ],
-    ending: '第 16 帧停在死亡结束姿态，不需要循环',
-  },
-];
-
-const BODY_RATIO_TEXT =
-  '横版像素动作角色体型，头身比优先控制在 3 到 4 头身，头部只允许略大于写实比例，保留清楚的头、躯干、双臂和双腿轮廓，不要退化成软萌 Q版大头贴或儿童绘本比例。';
-const PIXEL_STYLE_TEXT =
-  '明确的像素动作角色设定稿气质，整体按像素游戏角色设计方向组织，使用深色清楚轮廓、稳定剪影、有限大色块和硬朗边缘，不要柔和厚涂插画感，发型、服装、配饰优先形成醒目可读的像素级识别点，身体始终朝右，适合横版动作 sprite 资产。';
-
-export function getActionTemplateById(id: QwenSpriteActionTemplateId) {
-  return (
-    QWEN_SPRITE_ACTION_TEMPLATES.find((template) => template.id === id) ??
-    QWEN_SPRITE_ACTION_TEMPLATES[0]
-  );
-}
-
-/**
- * 正式角色主图 prompt 骨架。
- *
- * 输入应该是一段已经整理好的角色摘要或视觉描述，
- * 这里会把它嵌进统一的 sprite 资产约束中，
- * 输出真正发给图像模型的完整 prompt。
- */
-export function buildMasterPrompt(characterBrief: string) {
-  return [
-    '单人，2D 横版游戏角色标准设定图，主体完整可见，底部轮廓完整，身体比例稳定，轮廓清楚，适合后续制作 sprite sheet 动画。',
-    `视角要求：角色采用横版动作素材常用的右向斜侧身站姿，身体整体朝右，但保留少量正面信息，能读到面部轮廓与胸肩结构，不是完全 90 度纯右视图，也不是正面立绘。`,
-    `主体要求：画面中只保留单个角色主体，不要额外人物、动物、召唤物、载具或陪体。`,
-    `画面要求：1:1 正方形画布，画面中心构图，角色主体完整置于画面中央，不要裁切主体顶部和底部，不要镜头透视，不要特写。背景固定为单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕，只作为抠像底色，不出现建筑、室内布景、风景、地面道具、漂浮物、烟雾叙事元素或其他角色以外的场景内容。`,
-    `风格要求：${BODY_RATIO_TEXT} ${PIXEL_STYLE_TEXT} 高可读性游戏角色设定图，形体清晰，服装层次明确，优先体现像素动作角色感而不是软萌 Q版插画感，便于后续连续动作生成。`,
-    '请先拆解设定中的“身份词、主题词、身体结构词”。如果文字设定没有明确要求非人身体结构，默认优先使用参考图对应的人类或类人动作角色骨架，保持清楚的头、躯干、手臂和双腿轮廓，只有当文字设定明确要求非人结构时，才改为对应非人身体。',
-    '主题词默认只作用在角色自身的服装剪裁、材质、纹样、饰品、发光细节上，不要把主题词自动扩写成背景建筑、自然场景、漂浮装饰或额外环境物件。',
-    '视觉优先级应当是：身体结构词第一，身份词第二，主题词第三。没有明确身体结构词时，默认用人形拟人化表现，再把主题词转译成服装和装饰。',
-    characterBrief.trim(),
-  ]
-    .filter(Boolean)
-    .join('\n');
-}
-
-/**
- * 正式动作视频 prompt 骨架。
- *
- * 输入应该是已经整理好的动作细节与角色摘要，
- * 这里负责统一拼装成 sprite 动作生成所需的正式 prompt，
- * 包括视角、像素风格、动作模板、绿幕约束等。
- */
-export function buildVideoActionPrompt(options: {
-  actionTemplate: QwenSpriteActionTemplate;
-  actionDetailText: string;
-  useChromaKey: boolean;
-  characterBrief: string;
-}) {
-  return [
-    `单人全身角色动作视频，动作英文名是 ${options.actionTemplate.id}。`,
-    `角色固定为图1同一角色，保持右向斜侧身动作视角，镜头稳定，轮廓清晰，不要退化成完全 90 度纯右视图。`,
-    `视角要求：角色采用横版动作素材常用的右向斜侧身站姿，身体整体朝右，但保留少量正面信息，能读到面部轮廓与胸肩结构，不是完全 90 度纯右视图，也不是正面立绘。`,
-    `主体要求：画面中只保留单个角色主体，不要额外人物、动物、召唤物、载具或陪体。`,
-    `画面要求：1:1 正方形画布，画面中心构图，角色主体完整置于画面中央，不要裁切主体顶部和底部，不要镜头透视，不要特写。背景固定为单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕，只作为抠像底色，不出现建筑、室内布景、风景、地面道具、漂浮物、烟雾叙事元素或其他角色以外的场景内容。`,
-    `风格要求：${BODY_RATIO_TEXT} ${PIXEL_STYLE_TEXT} 高可读性游戏角色设定图，偏像素动画前置设计稿，形体清晰，服装层次明确，道具/权杖/武器如有则存在关系合理，优先保证像素动作角色感，不要退化成只剩 Q 版比例的普通插画，便于后续连续动作生成。`,
-    `动作结构：${options.actionTemplate.sequenceLines.join('；')}。结尾要求：${options.actionTemplate.ending}。`,
-    options.useChromaKey
-      ? '背景为单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕，无其他人物和场景元素，方便后期抽帧与抠像。'
-      : '背景简洁纯净，无复杂场景。',
-    `动作补充细节：${options.actionDetailText.trim() || '保持动作清晰、节奏明确、适合后续抽帧为 sprite sheet。'}`,
-    `角色设定：${options.characterBrief.trim()}`,
-    '目标是后续抽帧为横版动作游戏精灵表，因此不要镜头切换，不要景别变化，不要角色漂移。',
-  ].join(' ');
-}
diff --git a/scripts/check-api-server-env.mjs b/scripts/check-api-server-env.mjs
index 212523cc0..4b6f87b04 100644
--- a/scripts/check-api-server-env.mjs
+++ b/scripts/check-api-server-env.mjs
@@ -47,6 +47,31 @@ if (typoKeys.length > 0) {
   );
 }
 
+// 阿里云通用抠图兜底层：默认 enabled=true，但 AccessKey 缺失时会被静默跳过，
+// BgFilter 失败直接本地去背（质量下降）。属可选降级项，只告警不阻断部署。
+console.log('[api-server-env] 抠图兜底（阿里云通用抠图）配置检查');
+const mattingEnabled = env.GENARRATIVE_ALIYUN_MATTING_ENABLED !== 'false';
+const mattingKeyPresent =
+  hasValue(env.GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_ID) ||
+  hasValue(env.ALIBABA_CLOUD_ACCESS_KEY_ID);
+const mattingSecretPresent =
+  hasValue(env.GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_SECRET) ||
+  hasValue(env.ALIBABA_CLOUD_ACCESS_KEY_SECRET);
+printStatus(
+  'GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_ID / ALIBABA_CLOUD_ACCESS_KEY_ID',
+  mattingKeyPresent,
+);
+printStatus(
+  'GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_SECRET / ALIBABA_CLOUD_ACCESS_KEY_SECRET',
+  mattingSecretPresent,
+);
+if (mattingEnabled && !(mattingKeyPresent && mattingSecretPresent)) {
+  console.warn(
+    '[api-server-env] 警告：GENARRATIVE_ALIYUN_MATTING_ENABLED 未关闭但缺少 AccessKey，' +
+      '阿里云抠图兜底层将被跳过，BgFilter 失败后直接本地去背（质量下降）。',
+  );
+}
+
 if (missing.length > 0) {
   console.error(`[api-server-env] 缺少：${missing.join(', ')}`);
   process.exit(1);
diff --git a/scripts/deploy/production-api-deploy.sh b/scripts/deploy/production-api-deploy.sh
index ae4350900..efeb02958 100644
--- a/scripts/deploy/production-api-deploy.sh
+++ b/scripts/deploy/production-api-deploy.sh
@@ -255,7 +255,7 @@ ensure_runtime_env_and_dirs() {
   ensure_env_value_migrates_old_default "${api_env_file}" "GENARRATIVE_EXTERNAL_GENERATION_WORKER_LEASE_SECONDS" "3600" "600"
   ensure_env_value "${api_env_file}" "GENARRATIVE_EXTERNAL_GENERATION_WORKER_JOB_TIMEOUT_SECONDS" "900"
   ensure_env_value "${api_env_file}" "GENARRATIVE_EXTERNAL_GENERATION_WORKER_LONG_JOB_TIMEOUT_SECONDS" "1800"
-  ensure_env_value "${api_env_file}" "GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS" "45000"
+  ensure_env_value_migrates_old_default "${api_env_file}" "GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS" "45000" "180000"
   ensure_env_value "${api_env_file}" "GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD" "3"
   ensure_env_value "${api_env_file}" "GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS" "300"
 
diff --git a/scripts/jenkins-server-provision.sh b/scripts/jenkins-server-provision.sh
index edea458aa..2145bf803 100755
--- a/scripts/jenkins-server-provision.sh
+++ b/scripts/jenkins-server-provision.sh
@@ -479,7 +479,7 @@ ensure_api_runtime_env_defaults() {
   ensure_env_value_migrates_old_default "${API_ENV_FILE}" "GENARRATIVE_EXTERNAL_GENERATION_WORKER_LEASE_SECONDS" "3600" "600"
   ensure_env_value "${API_ENV_FILE}" "GENARRATIVE_EXTERNAL_GENERATION_WORKER_JOB_TIMEOUT_SECONDS" "900"
   ensure_env_value "${API_ENV_FILE}" "GENARRATIVE_EXTERNAL_GENERATION_WORKER_LONG_JOB_TIMEOUT_SECONDS" "1800"
-  ensure_env_value "${API_ENV_FILE}" "GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS" "45000"
+  ensure_env_value_migrates_old_default "${API_ENV_FILE}" "GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS" "45000" "180000"
   ensure_env_value "${API_ENV_FILE}" "GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD" "3"
   ensure_env_value "${API_ENV_FILE}" "GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS" "300"
 }
diff --git a/server-rs/Cargo.lock b/server-rs/Cargo.lock
index 181cd0ac8..ae19afaf0 100644
--- a/server-rs/Cargo.lock
+++ b/server-rs/Cargo.lock
@@ -241,6 +241,7 @@ dependencies = [
  "platform-hyper3d",
  "platform-image",
  "platform-llm",
+ "platform-matting",
  "platform-oss",
  "platform-speech",
  "platform-wechat",
@@ -4476,6 +4477,29 @@ dependencies = [
  "tokio",
 ]
 
+[[package]]
+name = "platform-matting"
+version = "0.1.0"
+dependencies = [
+ "base64 0.22.1",
+ "dotenvy",
+ "hex",
+ "hmac",
+ "httpdate",
+ "image",
+ "platform-oss",
+ "reqwest 0.12.28",
+ "serde",
+ "serde_json",
+ "serde_urlencoded",
+ "sha1",
+ "sha2",
+ "time",
+ "tokio",
+ "tracing",
+ "uuid",
+]
+
 [[package]]
 name = "platform-oss"
 version = "0.1.0"
diff --git a/server-rs/Cargo.toml b/server-rs/Cargo.toml
index c7681f2fb..64ce7ba85 100644
--- a/server-rs/Cargo.toml
+++ b/server-rs/Cargo.toml
@@ -38,6 +38,7 @@ members = [
     "crates/platform-hyper3d",
     "crates/platform-image",
     "crates/platform-llm",
+    "crates/platform-matting",
     "crates/platform-wechat",
     "crates/platform-speech",
     "crates/platform-agent",
@@ -88,6 +89,7 @@ platform-audio = { path = "crates/platform-audio", default-features = false }
 platform-hyper3d = { path = "crates/platform-hyper3d", default-features = false }
 platform-image = { path = "crates/platform-image", default-features = false }
 platform-llm = { path = "crates/platform-llm", default-features = false }
+platform-matting = { path = "crates/platform-matting", default-features = false }
 platform-oss = { path = "crates/platform-oss", default-features = false }
 platform-speech = { path = "crates/platform-speech", default-features = false }
 platform-wechat = { path = "crates/platform-wechat", default-features = false }
diff --git a/server-rs/crates/api-server/Cargo.toml b/server-rs/crates/api-server/Cargo.toml
index a38b50da4..8949fdca5 100644
--- a/server-rs/crates/api-server/Cargo.toml
+++ b/server-rs/crates/api-server/Cargo.toml
@@ -43,6 +43,7 @@ platform-auth = { workspace = true }
 platform-hyper3d = { workspace = true }
 platform-image = { workspace = true }
 platform-llm = { workspace = true }
+platform-matting = { workspace = true }
 platform-oss = { workspace = true }
 platform-speech = { workspace = true }
 platform-wechat = { workspace = true }
diff --git a/server-rs/crates/api-server/src/aliyun_matting.rs b/server-rs/crates/api-server/src/aliyun_matting.rs
new file mode 100644
index 000000000..d3c684d57
--- /dev/null
+++ b/server-rs/crates/api-server/src/aliyun_matting.rs
@@ -0,0 +1,165 @@
+//! 阿里云通用抠图在 api-server 侧的适配层。
+//!
+//! 输入 URL 策略：抠图服务只认上海地域 OSS URL，而我们没有上海地域自有 OSS，
+//! 统一由 platform-matting 上传 VIAPI 官方临时桶（1 天自动过期，无需清理）。
+
+use axum::http::StatusCode;
+use platform_matting::MattingError;
+use serde_json::json;
+
+use crate::{
+    http_error::AppError, openai_image_generation::DownloadedOpenAiImage, state::AppState,
+};
+
+/// 图片字节 → 阿里云通用抠图 → 原尺寸透明 PNG。
+/// 未配置抠图客户端时返回错误，由调用方决定是否降级本地算法。
+pub(crate) async fn segment_image_with_aliyun_matting(
+    state: &AppState,
+    image: &DownloadedOpenAiImage,
+    log_label: &str,
+) -> Result<DownloadedOpenAiImage, AppError> {
+    let matting_client = state
+        .matting_client()
+        .ok_or_else(aliyun_matting_unconfigured_error)?;
+
+    let file_name = format!("{log_label}.png");
+    let started_at = std::time::Instant::now();
+    let output_bytes = matting_client
+        .segment_image_to_transparent_png(image.bytes.as_slice(), &file_name)
+        .await
+        .map_err(|error| {
+            aliyun_matting_failure_to_app_error(&error, started_at.elapsed().as_millis() as u64)
+        })?;
+    tracing::info!(
+        provider = "aliyun-matting",
+        log_label,
+        elapsed_ms = started_at.elapsed().as_millis() as u64,
+        "阿里云通用抠图完成"
+    );
+
+    Ok(DownloadedOpenAiImage {
+        bytes: output_bytes,
+        mime_type: "image/png".to_string(),
+        extension: "png".to_string(),
+    })
+}
+
+/// 把 platform-matting 的错误映射成审计友好的 AppError。
+///
+/// 分类（是否外部调用、超时、传输层故障、上游 HTTP 状态）由 platform-matting 在错误发生处
+/// 结构化捕获，这里只做协议中立的读取，不再从中文 message 反推——外部供应商协议归属留在
+/// platform-* 层。`InvalidConfig` / `InvalidRequest` / `Sign` 是发请求前的本地预检失败，
+/// `external_call_attempted()` 为 false，据此跳过外部失败审计。
+fn aliyun_matting_failure_to_app_error(error: &MattingError, latency_ms: u64) -> AppError {
+    let message = error.message();
+    if !error.external_call_attempted() {
+        // 本地预检失败（未配置 / 图片解码失败 / 尺寸过小 / 签名构造失败），未触达阿里云。
+        return AppError::from_status(StatusCode::UNPROCESSABLE_ENTITY).with_details(json!({
+            "provider": "aliyun-matting",
+            "message": message,
+            "timeout": false,
+            "transport": false,
+            "externalCallAttempted": false,
+            "latencyMs": latency_ms,
+            "rawExcerpt": message.chars().take(500).collect::<String>(),
+        }));
+    }
+    let timeout = error.is_timeout();
+    let status = if timeout {
+        StatusCode::GATEWAY_TIMEOUT
+    } else {
+        StatusCode::BAD_GATEWAY
+    };
+    AppError::from_status(status).with_details(json!({
+        "provider": "aliyun-matting",
+        "message": message,
+        "timeout": timeout,
+        "transport": error.is_transport(),
+        "upstreamStatus": error.upstream_status(),
+        "latencyMs": latency_ms,
+        "rawExcerpt": message.chars().take(500).collect::<String>(),
+    }))
+}
+
+fn aliyun_matting_unconfigured_error() -> AppError {
+    AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_details(json!({
+        "provider": "aliyun-matting",
+        "message": "阿里云抠图客户端未配置或未启用。",
+        "externalCallAttempted": false,
+    }))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn aliyun_matting_unconfigured_error_marks_no_external_call_attempt() {
+        let error = aliyun_matting_unconfigured_error();
+
+        assert!(!crate::external_api_audit::matting_failure_external_call_attempted(&error));
+    }
+
+    #[test]
+    fn local_preflight_failures_do_not_count_as_external_call() {
+        for error in [
+            MattingError::InvalidRequest(
+                "待抠图图片尺寸 16x16 过小，阿里云通用抠图要求每条边大于 32 像素".to_string(),
+            ),
+            MattingError::InvalidRequest("解析待抠图图片失败：invalid png".to_string()),
+            MattingError::InvalidConfig("endpoint 为空".to_string()),
+            MattingError::Sign("初始化 OSS V1 签名器失败".to_string()),
+        ] {
+            let mapped = aliyun_matting_failure_to_app_error(&error, 3);
+
+            assert!(
+                !crate::external_api_audit::matting_failure_external_call_attempted(&mapped),
+                "本地预检失败不应记为外部调用：{}",
+                error.message()
+            );
+            let details = mapped.details().expect("details present");
+            assert_eq!(details.get("transport").and_then(|v| v.as_bool()), Some(false));
+            assert_eq!(details.get("timeout").and_then(|v| v.as_bool()), Some(false));
+        }
+    }
+
+    #[test]
+    fn upstream_transport_failure_maps_to_retryable_transport() {
+        let error =
+            MattingError::upstream_transport_error("通用抠图请求失败：dns error".to_string(), false);
+        let mapped = aliyun_matting_failure_to_app_error(&error, 12);
+
+        assert!(crate::external_api_audit::matting_failure_external_call_attempted(&mapped));
+        let details = mapped.details().expect("details present");
+        // 无 HTTP 状态的传输层失败标记为可重试 transport 故障，且不带 upstreamStatus。
+        assert_eq!(details.get("transport").and_then(|v| v.as_bool()), Some(true));
+        assert_eq!(details.get("timeout").and_then(|v| v.as_bool()), Some(false));
+        assert!(details.get("upstreamStatus").is_some_and(|v| v.is_null()));
+    }
+
+    #[test]
+    fn upstream_timeout_failure_maps_to_gateway_timeout() {
+        let error =
+            MattingError::upstream_transport_error("通用抠图请求失败：timed out".to_string(), true);
+        let mapped = aliyun_matting_failure_to_app_error(&error, 7);
+
+        assert_eq!(mapped.status_code(), StatusCode::GATEWAY_TIMEOUT);
+        let details = mapped.details().expect("details present");
+        assert_eq!(details.get("timeout").and_then(|v| v.as_bool()), Some(true));
+        assert_eq!(details.get("transport").and_then(|v| v.as_bool()), Some(true));
+    }
+
+    #[test]
+    fn upstream_http_status_failure_carries_status_without_transport() {
+        let error = MattingError::upstream_http_error(
+            "通用抠图接口返回失败（HTTP 429，Code=Throttled）：QPS exceeded".to_string(),
+            429,
+        );
+        let mapped = aliyun_matting_failure_to_app_error(&error, 5);
+
+        assert!(crate::external_api_audit::matting_failure_external_call_attempted(&mapped));
+        let details = mapped.details().expect("details present");
+        assert_eq!(details.get("transport").and_then(|v| v.as_bool()), Some(false));
+        assert_eq!(details.get("upstreamStatus").and_then(|v| v.as_u64()), Some(429));
+    }
+}
diff --git a/server-rs/crates/api-server/src/character_animation_assets.rs b/server-rs/crates/api-server/src/character_animation_assets.rs
index ea44c174b..7a0b4f7ee 100644
--- a/server-rs/crates/api-server/src/character_animation_assets.rs
+++ b/server-rs/crates/api-server/src/character_animation_assets.rs
@@ -61,12 +61,16 @@ use crate::{
         editor_generation_source_entity_id, enqueue_editor_generation_job,
     },
     editor_green_screen::{
-        LEGACY_EDITOR_GREEN_SCREEN_CHARACTER_PROMPT_CLAUSE,
-        legacy_editor_green_screen_background_color,
+        EditorScreenBackgroundColor, editor_green_screen_character_prompt_clause,
         remove_editor_generated_green_screen_background,
     },
+    editor_screen_background_decision::{
+        EditorScreenBackgroundDecisionInput, EditorScreenBackgroundDecisionKind,
+        resolve_editor_screen_background_color,
+    },
     editor_project::{
         EditorCanvasGeneratedLayerInput, PersistEditorGeneratedAssetRequest,
+        apply_editor_screen_background_decision_to_generation_inputs,
         build_editor_canvas_generated_layer_item, complete_editor_canvas_generation_with_items,
         persist_editor_generated_media_asset,
     },
@@ -105,6 +109,7 @@ const FIXED_ARK_CHARACTER_VIDEO_RESOLUTION: &str = "480p";
 const FIXED_ARK_CHARACTER_VIDEO_RATIO: &str = "1:1";
 const FIXED_ARK_CHARACTER_VIDEO_DURATION_SECONDS: u32 = 4;
 const ARK_VIDEO_TASK_POLL_INTERVAL_MS: u64 = 5_000;
+const SOURCE_IMAGE_RESOLVE_TIMEOUT_MS: u64 = 30_000;
 const EDITOR_CHARACTER_ANIMATION_MODEL: &str = "seedance2.0-fast";
 const EDITOR_CHARACTER_ANIMATION_ASSET_KIND: &str = "editor_character_animation";
 const EDITOR_GREEN_SCREEN_SOURCE_ASSET_KIND: &str = "editor_green_screen_source";
@@ -564,9 +569,13 @@ pub async fn generate_editor_character_animation(
                 })),
             )
         })?;
-        let normalized =
-            normalize_editor_character_animation_request_with_pricing(payload.clone(), &pricing)
-                .map_err(|error| character_animation_error_response(&request_context, error))?;
+        // 队列路径只取定价，背景色决策留到实际执行时再做，这里用默认色占位。
+        let normalized = normalize_editor_character_animation_request_with_pricing(
+            payload.clone(),
+            &pricing,
+            crate::editor_green_screen::default_editor_screen_background_color(),
+        )
+        .map_err(|error| character_animation_error_response(&request_context, error))?;
         let source_entity_id = editor_generation_source_entity_id(
             payload.project_id.as_deref(),
             payload.source_layer_id.as_str(),
@@ -628,31 +637,85 @@ pub(crate) async fn generate_editor_character_animation_for_owner(
             })),
         )
     })?;
-    let normalized =
-        normalize_editor_character_animation_request_with_pricing(payload, &pricing)
-            .map_err(|error| character_animation_error_response(&request_context, error))?;
-    let settings = require_editor_character_animation_settings(&state, &normalized)
+    // 先解析源角色图：图生视频的主体颜色完全由源图决定，背景色决策必须看到这张图。
+    let source_resolve_client = build_upstream_http_client(SOURCE_IMAGE_RESOLVE_TIMEOUT_MS)
         .map_err(|error| character_animation_error_response(&request_context, error))?;
-    let extraction_settings = resolve_backend_frame_extraction_settings(&state);
-    let http_client = build_upstream_http_client(settings.ark.request_timeout_ms)
-        .map_err(|error| character_animation_error_response(&request_context, error))?;
-    let task_id = generate_ai_task_id(current_utc_micros());
     let source_data_url = resolve_media_source_as_data_url(
         &state,
-        &http_client,
-        normalized.source_image_src.as_str(),
+        &source_resolve_client,
+        payload.source_image_src.trim(),
         "sourceImageSrc",
     )
     .await
     .map_err(|error| character_animation_error_response(&request_context, error))?;
+    // 定价 / 上游设置先于扣费，且都不依赖背景色：用默认色占位归一化（与队列路径一致），
+    // 把背景色决策挪到预扣泥点之后，避免余额不足 / 生成注定失败时仍白发一次 gpt-5-mini 决策。
+    let priced = normalize_editor_character_animation_request_with_pricing(
+        payload.clone(),
+        &pricing,
+        crate::editor_green_screen::default_editor_screen_background_color(),
+    )
+    .map_err(|error| character_animation_error_response(&request_context, error))?;
+    let settings = require_editor_character_animation_settings(&state, &priced)
+        .map_err(|error| character_animation_error_response(&request_context, error))?;
+    let http_client = build_upstream_http_client(settings.ark.request_timeout_ms)
+        .map_err(|error| character_animation_error_response(&request_context, error))?;
+    let extraction_settings = resolve_backend_frame_extraction_settings(&state);
+    let task_id = generate_ai_task_id(current_utc_micros());
+    // 抠图供应商失败审计上下文：逐帧阿里云抠图失败即使兜底成功，也要进 OTLP + tracking_event。
+    let matting_audit = crate::external_api_audit::ExternalApiAuditContext {
+        user_id: Some(owner_user_id.clone()),
+        profile_id: project_id.clone(),
+        request_id: Some(request_context.request_id().to_string()),
+    };
 
     let result = execute_billable_asset_operation_with_cost(
         &state,
         owner_user_id.as_str(),
         EDITOR_CHARACTER_ANIMATION_ASSET_KIND,
         task_id.as_str(),
-        u64::from(normalized.price_mud_points),
+        u64::from(priced.price_mud_points),
         async {
+            // 背景色决策：预扣泥点之后才发起（显式传入 → 视觉 LLM 按源图主体配色自动决策 → 默认色）。
+            // 决策失败会让本 future 返回 Err，走 execute_billable 的失败退款，用户不损失泥点。
+            let screen_background_decision = resolve_editor_screen_background_color(
+                state.llm_client(),
+                state.creative_agent_gpt5_client(),
+                EditorScreenBackgroundDecisionInput {
+                    kind: EditorScreenBackgroundDecisionKind::CharacterAnimation,
+                    screen_color: payload.screen_color.clone(),
+                    prompt: payload.prompt_text.clone(),
+                    icon_descriptions: Vec::new(),
+                    reference_count: 1,
+                    source_image_data_url: Some(source_data_url.clone()),
+                },
+                Some(&crate::editor_screen_background_decision::EditorScreenBackgroundDecisionAuditContext {
+                    state: &state,
+                    context: crate::external_api_audit::ExternalApiAuditContext {
+                        user_id: Some(owner_user_id.clone()),
+                        profile_id: project_id.clone(),
+                        request_id: Some(request_context.request_id().to_string()),
+                    },
+                }),
+            )
+            .await?;
+            // 把实际选定的背景色落进资产记录，供后续以该资产为参考图时反查旧背景色。
+            let generation_inputs = apply_editor_screen_background_decision_to_generation_inputs(
+                generation_inputs,
+                Some(&screen_background_decision),
+            );
+            // 用决策色重新归一化以拿到最终提示词（价格 / 校验已在预扣前用占位色完成）。
+            let normalized = normalize_editor_character_animation_request_with_pricing(
+                payload,
+                &pricing,
+                screen_background_decision.color,
+            )?;
+            // 透明源图先合成到选定背景色：让视频背景确定性地等于抠图键色，而不是赌模型服从提示词。
+            let source_data_url = composite_source_image_onto_screen_color(
+                source_data_url.as_str(),
+                screen_background_decision.color,
+            )
+            .unwrap_or(source_data_url);
             let generated = request_editor_character_animation_preview(
                 &state,
                 &http_client,
@@ -672,15 +735,16 @@ pub(crate) async fn generate_editor_character_animation_for_owner(
                 generated.preview_video_path.as_str(),
                 &normalized,
                 &extraction_settings,
+                &matting_audit,
             )
             .await?;
 
-            Ok::<_, AppError>((generated, frames))
+            Ok::<_, AppError>((generated, frames, normalized, generation_inputs))
         },
     )
     .await;
 
-    let (generated, frames) =
+    let (generated, frames, normalized, generation_inputs) =
         result.map_err(|error| character_animation_error_response(&request_context, error))?;
     let completed_project = if let Some(completion) = canvas_completion.as_ref() {
         let frame_payload_json = serde_json::to_value(&frames).map_err(|error| {
@@ -2049,6 +2113,7 @@ async fn extract_and_persist_editor_character_animation_frames(
     preview_video_path: &str,
     request: &NormalizedEditorCharacterAnimationRequest,
     extraction_settings: &BackendFrameExtractionSettings,
+    audit: &crate::external_api_audit::ExternalApiAuditContext,
 ) -> Result<Vec<EditorCharacterAnimationFramePayload>, AppError> {
     let plan = AnimationFrameExtractionPlan {
         frame_count: request.frame_count,
@@ -2075,10 +2140,14 @@ async fn extract_and_persist_editor_character_animation_frames(
     )
     .await?;
     let finalized_frames = remove_editor_character_animation_frame_backgrounds(
+        state,
         finalized_frames,
         request.frame_width,
         request.frame_height,
-    )?;
+        request.screen_color,
+        audit,
+    )
+    .await?;
 
     let mut frame_payloads = Vec::with_capacity(finalized_frames.len());
     for (index, frame) in finalized_frames.into_iter().enumerate() {
@@ -2147,30 +2216,76 @@ async fn persist_editor_character_animation_green_screen_source_frames(
     Ok(())
 }
 
-fn remove_editor_character_animation_frame_backgrounds(
+/// 逐帧抠图：优先阿里云通用抠图，失败降级本地键色（使用生成时的纯色背景色）。
+/// 小并发保序处理，单帧降级不影响其他帧。
+async fn remove_editor_character_animation_frame_backgrounds(
+    state: &AppState,
     frames: Vec<FinalizedAnimationFrame>,
     frame_width: u32,
     frame_height: u32,
+    screen_color: EditorScreenBackgroundColor,
+    audit: &crate::external_api_audit::ExternalApiAuditContext,
 ) -> Result<Vec<FinalizedAnimationFrame>, AppError> {
-    let mut removed_frames = Vec::with_capacity(frames.len());
-    for frame in frames {
-        let removed = remove_editor_generated_green_screen_background(
-            &DownloadedOpenAiImage {
+    use futures_util::{StreamExt as _, TryStreamExt as _};
+
+    const FRAME_MATTING_CONCURRENCY: usize = 3;
+
+    futures_util::stream::iter(frames.into_iter().enumerate().map(
+        |(frame_index, frame)| async move {
+            let image = DownloadedOpenAiImage {
                 bytes: frame.bytes,
                 mime_type: frame.mime_type,
                 extension: frame.extension,
-            },
-            legacy_editor_green_screen_background_color(),
-        )?;
-        removed_frames.push(finalize_animation_frame_payload(
-            removed.bytes.as_slice(),
-            removed.mime_type.as_str(),
-            frame_width,
-            frame_height,
-            false,
-        )?);
-    }
-    Ok(removed_frames)
+            };
+            let removed = match crate::aliyun_matting::segment_image_with_aliyun_matting(
+                state,
+                &image,
+                "editor-animation-frame",
+            )
+            .await
+            {
+                Ok(removed) => removed,
+                Err(error) => {
+                    tracing::warn!(
+                        provider = "aliyun-matting",
+                        frame_index,
+                        screen_color = screen_color.hex,
+                        error = %error,
+                        error_details = ?error.details(),
+                        "editor_animation_frame_aliyun_matting_fallback_to_local"
+                    );
+                    if crate::external_api_audit::matting_failure_external_call_attempted(&error) {
+                        crate::external_api_audit::record_matting_external_api_failure(
+                            state,
+                            audit,
+                            "aliyun-matting",
+                            state.config.aliyun_matting_endpoint.clone(),
+                            "editor-character-animation-frame-matting",
+                            "aliyun_segment",
+                            crate::external_api_audit::matting_failure_audit_status_code(&error),
+                            crate::external_api_audit::matting_failure_audit_timeout(&error),
+                            crate::external_api_audit::matting_failure_audit_latency_ms(&error),
+                            error.message().to_string(),
+                            crate::external_api_audit::matting_failure_audit_raw_excerpt(&error)
+                                .or_else(|| Some(format!("frame_index={frame_index}"))),
+                        )
+                        .await;
+                    }
+                    remove_editor_generated_green_screen_background(&image, screen_color)?
+                }
+            };
+            finalize_animation_frame_payload(
+                removed.bytes.as_slice(),
+                removed.mime_type.as_str(),
+                frame_width,
+                frame_height,
+                false,
+            )
+        },
+    ))
+    .buffered(FRAME_MATTING_CONCURRENCY)
+    .try_collect::<Vec<_>>()
+    .await
 }
 
 async fn publish_animation_set(
@@ -2835,12 +2950,17 @@ fn normalize_editor_character_animation_request(
 ) -> Result<NormalizedEditorCharacterAnimationRequest, AppError> {
     let pricing = crate::editor_generation_config::load_editor_generation_pricing_from_paths(None)
         .expect("默认模型定价配置必须合法");
-    normalize_editor_character_animation_request_with_pricing(payload, &pricing)
+    normalize_editor_character_animation_request_with_pricing(
+        payload,
+        &pricing,
+        crate::editor_green_screen::default_editor_screen_background_color(),
+    )
 }
 
 fn normalize_editor_character_animation_request_with_pricing(
     payload: EditorCharacterAnimationGenerateRequest,
     pricing: &EditorGenerationPricingConfig,
+    screen_color: EditorScreenBackgroundColor,
 ) -> Result<NormalizedEditorCharacterAnimationRequest, AppError> {
     let source_layer_id = normalize_required_text(payload.source_layer_id.as_str(), "");
     if source_layer_id.is_empty() {
@@ -2848,7 +2968,8 @@ fn normalize_editor_character_animation_request_with_pricing(
             "sourceLayerId 不能为空。",
         ));
     }
-    let source_image_src = trim_optional_text(Some(payload.source_image_src.as_str()))
+    // 源图在 handler 里已提前解析（决策要看图）；这里保留空值校验，队列路径入队前也走这份校验。
+    trim_optional_text(Some(payload.source_image_src.as_str()))
         .ok_or_else(|| editor_character_animation_bad_request("sourceImageSrc 不能为空。"))?;
     let prompt_text = payload
         .prompt_text
@@ -2880,12 +3001,12 @@ fn normalize_editor_character_animation_request_with_pricing(
         ratio,
         resolution,
     );
-    let prompt = build_editor_character_animation_prompt(prompt_text.as_str());
+    let prompt = build_editor_character_animation_prompt(prompt_text.as_str(), screen_color);
 
     Ok(NormalizedEditorCharacterAnimationRequest {
         source_layer_id,
-        source_image_src,
         prompt,
+        screen_color,
         resolution: resolution.to_string(),
         ratio: resolve_editor_character_animation_provider_ratio(
             ratio,
@@ -3385,10 +3506,13 @@ fn editor_video_bad_request(message: impl Into<String>) -> AppError {
     }))
 }
 
-fn build_editor_character_animation_prompt(prompt_text: &str) -> String {
+fn build_editor_character_animation_prompt(
+    prompt_text: &str,
+    screen_color: EditorScreenBackgroundColor,
+) -> String {
     format!(
         "生成游戏角色动画，参考图作为首帧和尾帧，画面中心构图，角色主体完整置于画面中央，禁止镜头透视，禁止特写。{}；禁止出现建筑、室内布景、风景、地面道具、漂浮物、烟雾叙事元素、文字或其他角色以外的场景内容。\n动作描述：\n{}",
-        LEGACY_EDITOR_GREEN_SCREEN_CHARACTER_PROMPT_CLAUSE,
+        editor_green_screen_character_prompt_clause(screen_color),
         prompt_text.trim()
     )
 }
@@ -4004,6 +4128,68 @@ fn parse_media_data_url(value: &str) -> Option<MediaPayload> {
     })
 }
 
+/// 把带透明通道的源图合成到选定背景色上，返回新的 PNG data URL。
+/// 视频模型不支持 alpha：透明源图会被按白底理解，且图生视频里源图背景的视觉证据
+/// 权重高于文字提示，导致提示词指定的背景色被无视。先填成实色让源图和提示词一致，
+/// 视频背景就是抠图键色。源图本身不透明或无法解码时返回 None（沿用原图）。
+fn composite_source_image_onto_screen_color(
+    source_data_url: &str,
+    screen_color: EditorScreenBackgroundColor,
+) -> Option<String> {
+    let payload = parse_media_data_url(source_data_url)?;
+    if !payload.mime_type.starts_with("image/") {
+        return None;
+    }
+    let Ok(image) = image::load_from_memory(payload.bytes.as_slice()) else {
+        tracing::warn!("character_animation_source_composite_skip_undecodable_image");
+        return None;
+    };
+    let rgba = image.to_rgba8();
+    if rgba.pixels().all(|pixel| pixel.0[3] == u8::MAX) {
+        return None;
+    }
+    let background = [
+        f32::from(screen_color.red),
+        f32::from(screen_color.green),
+        f32::from(screen_color.blue),
+    ];
+    let mut composited = RgbaImage::new(rgba.width(), rgba.height());
+    for (x, y, pixel) in rgba.enumerate_pixels() {
+        let [red, green, blue, alpha] = pixel.0;
+        let opacity = f32::from(alpha) / 255.0;
+        let blend = |source: u8, background: f32| -> u8 {
+            (f32::from(source) * opacity + background * (1.0 - opacity)).round() as u8
+        };
+        composited.put_pixel(
+            x,
+            y,
+            Rgba([
+                blend(red, background[0]),
+                blend(green, background[1]),
+                blend(blue, background[2]),
+                u8::MAX,
+            ]),
+        );
+    }
+    let mut bytes = Vec::new();
+    if PngEncoder::new(&mut bytes)
+        .write_image(
+            composited.as_raw(),
+            composited.width(),
+            composited.height(),
+            ColorType::Rgba8.into(),
+        )
+        .is_err()
+    {
+        tracing::warn!("character_animation_source_composite_skip_encode_failed");
+        return None;
+    }
+    Some(format!(
+        "data:image/png;base64,{}",
+        encode_base64(bytes.as_slice())
+    ))
+}
+
 fn resolve_object_key_from_legacy_path(value: &str, field: &str) -> Result<String, AppError> {
     let trimmed = value.trim();
     if trimmed.is_empty() {
@@ -5081,7 +5267,6 @@ struct EditorVideoSettings {
 #[derive(Debug)]
 struct NormalizedEditorCharacterAnimationRequest {
     source_layer_id: String,
-    source_image_src: String,
     prompt: String,
     resolution: String,
     ratio: String,
@@ -5091,6 +5276,7 @@ struct NormalizedEditorCharacterAnimationRequest {
     frame_width: u32,
     frame_height: u32,
     fps: u32,
+    screen_color: EditorScreenBackgroundColor,
 }
 
 #[derive(Debug)]
@@ -5183,6 +5369,56 @@ mod tests {
         assert!(parse_video_data_url("data:image/png;base64,aGVsbG8=").is_none());
     }
 
+    fn encode_rgba_png_data_url(image: &RgbaImage) -> String {
+        let mut bytes = Vec::new();
+        PngEncoder::new(&mut bytes)
+            .write_image(
+                image.as_raw(),
+                image.width(),
+                image.height(),
+                ColorType::Rgba8.into(),
+            )
+            .expect("test image should encode");
+        format!("data:image/png;base64,{}", encode_base64(bytes.as_slice()))
+    }
+
+    #[test]
+    fn composites_transparent_source_onto_screen_color() {
+        let mut image = RgbaImage::from_pixel(8, 8, Rgba([0, 0, 0, 0]));
+        image.put_pixel(4, 4, Rgba([10, 20, 30, 255]));
+        let screen_color = crate::editor_green_screen::EDITOR_SCREEN_BACKGROUND_COLORS[0];
+
+        let composited =
+            composite_source_image_onto_screen_color(&encode_rgba_png_data_url(&image), screen_color)
+                .expect("透明源图应被合成");
+        let payload = parse_media_data_url(&composited).expect("合成结果应是图片 data URL");
+        let output = image::load_from_memory(payload.bytes.as_slice())
+            .expect("合成结果应可解码")
+            .to_rgba8();
+
+        assert_eq!(
+            output.get_pixel(0, 0).0,
+            [screen_color.red, screen_color.green, screen_color.blue, 255],
+            "透明像素应填成背景色"
+        );
+        assert_eq!(output.get_pixel(4, 4).0, [10, 20, 30, 255], "不透明像素应保持原色");
+    }
+
+    #[test]
+    fn opaque_source_image_skips_compositing() {
+        let image = RgbaImage::from_pixel(4, 4, Rgba([1, 2, 3, 255]));
+        let screen_color = crate::editor_green_screen::EDITOR_SCREEN_BACKGROUND_COLORS[0];
+
+        assert!(
+            composite_source_image_onto_screen_color(
+                &encode_rgba_png_data_url(&image),
+                screen_color
+            )
+            .is_none(),
+            "不透明源图应沿用原图"
+        );
+    }
+
     #[test]
     fn sanitize_storage_segment_falls_back_for_chinese_label() {
         assert_eq!(
@@ -5319,6 +5555,7 @@ mod tests {
                 source_width: 768,
                 source_height: 1024,
                 prompt_text: "待机呼吸，轻微摆动。".to_string(),
+                screen_color: None,
                 resolution: "720p".to_string(),
                 ratio: "same".to_string(),
                 frame_count: 48,
@@ -5357,6 +5594,7 @@ mod tests {
                 source_width: 1024,
                 source_height: 1024,
                 prompt_text: "待机呼吸".to_string(),
+                screen_color: None,
                 resolution: "480p".to_string(),
                 ratio: "same".to_string(),
                 frame_count: 32,
@@ -5384,6 +5622,7 @@ mod tests {
                 source_width: 1024,
                 source_height: 1024,
                 prompt_text: "奔跑".to_string(),
+                screen_color: None,
                 resolution: "480p".to_string(),
                 ratio: "1:1".to_string(),
                 frame_count: 48,
@@ -5400,14 +5639,17 @@ mod tests {
     }
 
     #[test]
-    fn editor_character_animation_builds_required_green_screen_prompt() {
-        let prompt = build_editor_character_animation_prompt("行走两步后回到站姿。");
+    fn editor_character_animation_builds_required_screen_background_prompt() {
+        let color = crate::editor_green_screen::default_editor_screen_background_color();
+        let prompt = build_editor_character_animation_prompt("行走两步后回到站姿。", color);
 
         assert!(prompt.contains("生成游戏角色动画"));
         assert!(prompt.contains("参考图作为首帧和尾帧"));
-        assert!(prompt.contains("背景固定为单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕"));
-        assert!(prompt.contains("绿幕背景必须平整无纹理、无渐变、无阴影"));
-        assert!(prompt.contains("角色主体不得带绿色描边、绿色投影或绿色反光"));
+        assert!(prompt.contains(color.hex));
+        assert!(prompt.contains("纯色背景必须平整无纹理、无渐变、无阴影"));
+        assert!(
+            prompt.contains("角色主体及其服饰、道具的颜色必须与背景色明显区分，不得带与背景色相同或相近的描边、投影或反光")
+        );
         assert!(prompt.contains("动作描述：\n行走两步后回到站姿。"));
     }
 
diff --git a/server-rs/crates/api-server/src/config.rs b/server-rs/crates/api-server/src/config.rs
index ad6ffa74f..10e8b1d63 100644
--- a/server-rs/crates/api-server/src/config.rs
+++ b/server-rs/crates/api-server/src/config.rs
@@ -20,9 +20,11 @@ pub(crate) const DEFAULT_VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS: u64 = 1_000_000
 const DEFAULT_EDITOR_BACKGROUND_REMOVAL_BASE_URL: &str = "http://58.87.105.82";
 const DEFAULT_EDITOR_BACKGROUND_REMOVAL_REQUEST_TIMEOUT_MS: u64 = 120_000;
 const DEFAULT_EDITOR_BGFILTER_BASE_URL: &str = "http://58.87.105.82/bgfilter";
-const DEFAULT_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS: u64 = 45_000;
+const DEFAULT_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS: u64 = 180_000;
 const DEFAULT_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD: u32 = 3;
 const DEFAULT_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS: u64 = 300;
+const DEFAULT_ALIYUN_MATTING_ENDPOINT: &str = "imageseg.cn-shanghai.aliyuncs.com";
+const DEFAULT_ALIYUN_MATTING_REQUEST_TIMEOUT_MS: u64 = 30_000;
 
 // 集中管理 api-server 的启动配置，避免入口层直接散落环境变量解析逻辑。
 #[derive(Clone, Debug)]
@@ -68,6 +70,11 @@ pub struct AppConfig {
     pub editor_bgfilter_base_url: String,
     pub editor_bgfilter_token: Option<String>,
     pub editor_bgfilter_request_timeout_ms: u64,
+    pub aliyun_matting_enabled: bool,
+    pub aliyun_matting_endpoint: String,
+    pub aliyun_matting_access_key_id: Option<String>,
+    pub aliyun_matting_access_key_secret: Option<String>,
+    pub aliyun_matting_request_timeout_ms: u64,
     pub editor_bgfilter_circuit_failure_threshold: u32,
     pub editor_bgfilter_circuit_cooldown: Duration,
     pub image_editor_agent_sidebar_enabled: bool,
@@ -309,6 +316,11 @@ impl Default for AppConfig {
             editor_bgfilter_base_url: DEFAULT_EDITOR_BGFILTER_BASE_URL.to_string(),
             editor_bgfilter_token: None,
             editor_bgfilter_request_timeout_ms: DEFAULT_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS,
+            aliyun_matting_enabled: true,
+            aliyun_matting_endpoint: DEFAULT_ALIYUN_MATTING_ENDPOINT.to_string(),
+            aliyun_matting_access_key_id: None,
+            aliyun_matting_access_key_secret: None,
+            aliyun_matting_request_timeout_ms: DEFAULT_ALIYUN_MATTING_REQUEST_TIMEOUT_MS,
             editor_bgfilter_circuit_failure_threshold:
                 DEFAULT_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD,
             editor_bgfilter_circuit_cooldown: Duration::from_secs(
@@ -518,6 +530,25 @@ impl AppConfig {
         {
             config.editor_bgfilter_request_timeout_ms = timeout_ms;
         }
+        if let Some(enabled) = read_first_bool_env(&["GENARRATIVE_ALIYUN_MATTING_ENABLED"]) {
+            config.aliyun_matting_enabled = enabled;
+        }
+        if let Some(endpoint) = read_first_non_empty_env(&["GENARRATIVE_ALIYUN_MATTING_ENDPOINT"]) {
+            config.aliyun_matting_endpoint = endpoint;
+        }
+        config.aliyun_matting_access_key_id = read_first_non_empty_env(&[
+            "GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_ID",
+            "ALIBABA_CLOUD_ACCESS_KEY_ID",
+        ]);
+        config.aliyun_matting_access_key_secret = read_first_non_empty_env(&[
+            "GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_SECRET",
+            "ALIBABA_CLOUD_ACCESS_KEY_SECRET",
+        ]);
+        if let Some(timeout_ms) =
+            read_first_positive_u64_env(&["GENARRATIVE_ALIYUN_MATTING_REQUEST_TIMEOUT_MS"])
+        {
+            config.aliyun_matting_request_timeout_ms = timeout_ms;
+        }
         if let Some(threshold) =
             read_first_u32_env(&["GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD"])
         {
@@ -2303,7 +2334,7 @@ mod tests {
                 "GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN",
                 "shared-token",
             );
-            std::env::set_var("GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS", "180000");
+            std::env::set_var("GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS", "240000");
         }
 
         let config = AppConfig::from_env();
@@ -2312,7 +2343,7 @@ mod tests {
             config.editor_bgfilter_token.as_deref(),
             Some("shared-token")
         );
-        assert_eq!(config.editor_bgfilter_request_timeout_ms, 180_000);
+        assert_eq!(config.editor_bgfilter_request_timeout_ms, 240_000);
 
         unsafe {
             std::env::set_var("GENARRATIVE_EDITOR_BGFILTER_TOKEN", "bgfilter-token");
@@ -2332,6 +2363,63 @@ mod tests {
         }
     }
 
+    #[test]
+    fn from_env_reads_aliyun_matting_settings_and_reuses_alibaba_cloud_keys() {
+        let _guard = ENV_LOCK
+            .get_or_init(|| Mutex::new(()))
+            .lock()
+            .expect("env lock should not poison");
+
+        unsafe {
+            std::env::remove_var("GENARRATIVE_ALIYUN_MATTING_ENABLED");
+            std::env::remove_var("GENARRATIVE_ALIYUN_MATTING_ENDPOINT");
+            std::env::remove_var("GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_ID");
+            std::env::remove_var("GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_SECRET");
+            std::env::remove_var("GENARRATIVE_ALIYUN_MATTING_REQUEST_TIMEOUT_MS");
+            std::env::remove_var("ALIBABA_CLOUD_ACCESS_KEY_ID");
+            std::env::remove_var("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
+            std::env::set_var("ALIBABA_CLOUD_ACCESS_KEY_ID", "shared-ak-id");
+            std::env::set_var("ALIBABA_CLOUD_ACCESS_KEY_SECRET", "shared-ak-secret");
+            std::env::set_var("GENARRATIVE_ALIYUN_MATTING_REQUEST_TIMEOUT_MS", "45000");
+        }
+
+        let config = AppConfig::from_env();
+        assert!(config.aliyun_matting_enabled);
+        assert_eq!(
+            config.aliyun_matting_endpoint,
+            "imageseg.cn-shanghai.aliyuncs.com"
+        );
+        assert_eq!(
+            config.aliyun_matting_access_key_id.as_deref(),
+            Some("shared-ak-id")
+        );
+        assert_eq!(
+            config.aliyun_matting_access_key_secret.as_deref(),
+            Some("shared-ak-secret")
+        );
+        assert_eq!(config.aliyun_matting_request_timeout_ms, 45_000);
+
+        unsafe {
+            std::env::set_var("GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_ID", "matting-ak-id");
+            std::env::set_var("GENARRATIVE_ALIYUN_MATTING_ENABLED", "false");
+        }
+
+        let config = AppConfig::from_env();
+        assert!(!config.aliyun_matting_enabled);
+        assert_eq!(
+            config.aliyun_matting_access_key_id.as_deref(),
+            Some("matting-ak-id")
+        );
+
+        unsafe {
+            std::env::remove_var("GENARRATIVE_ALIYUN_MATTING_ENABLED");
+            std::env::remove_var("GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_ID");
+            std::env::remove_var("GENARRATIVE_ALIYUN_MATTING_REQUEST_TIMEOUT_MS");
+            std::env::remove_var("ALIBABA_CLOUD_ACCESS_KEY_ID");
+            std::env::remove_var("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
+        }
+    }
+
     #[test]
     fn from_env_reads_editor_bgfilter_circuit_settings() {
         let _guard = ENV_LOCK
diff --git a/server-rs/crates/api-server/src/editor_green_screen.rs b/server-rs/crates/api-server/src/editor_green_screen.rs
index 586b682d1..5840533de 100644
--- a/server-rs/crates/api-server/src/editor_green_screen.rs
+++ b/server-rs/crates/api-server/src/editor_green_screen.rs
@@ -16,7 +16,7 @@ pub(crate) struct EditorScreenBackgroundColor {
     pub(crate) blue: u8,
 }
 
-pub(crate) const EDITOR_SCREEN_BACKGROUND_COLORS: [EditorScreenBackgroundColor; 11] = [
+pub(crate) const EDITOR_SCREEN_BACKGROUND_COLORS: [EditorScreenBackgroundColor; 12] = [
     EditorScreenBackgroundColor {
         label: "浅雾蓝",
         hex: "#CFEFFF",
@@ -94,21 +94,21 @@ pub(crate) const EDITOR_SCREEN_BACKGROUND_COLORS: [EditorScreenBackgroundColor;
         green: 247,
         blue: 240,
     },
+    // 中明度低饱和柔雾绿：填补安全弧的绿色段。浅粉彩绿（淡薄荷绿）会被露肤角色的皮肤规则剔除，
+    // 故绿色改用中明度以过 RGB 分离（Rule 3）；色相远离皮肤橙调，过色调投影（Rule 2）。
+    EditorScreenBackgroundColor {
+        label: "灰竹绿",
+        hex: "#A0BBA0",
+        red: 160,
+        green: 187,
+        blue: 160,
+    },
 ];
 
 pub(crate) fn default_editor_screen_background_color() -> EditorScreenBackgroundColor {
     EDITOR_SCREEN_BACKGROUND_COLORS[0]
 }
 
-pub(crate) fn legacy_editor_green_screen_background_color() -> EditorScreenBackgroundColor {
-    EditorScreenBackgroundColor {
-        label: "纯绿色",
-        hex: "#00FF00",
-        red: 0,
-        green: 255,
-        blue: 0,
-    }
-}
 
 pub(crate) fn parse_editor_screen_background_color(
     value: Option<&str>,
@@ -136,15 +136,11 @@ pub(crate) fn parse_editor_screen_background_color(
 pub(crate) const EDITOR_GREEN_SCREEN_BACKGROUND_GUARDRAILS: &str =
     "纯色背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具";
 pub(crate) const EDITOR_GREEN_SCREEN_ASSET_GUARDRAILS: &str =
-    "素材自身不要出现与背景色相同或相近的描边、底板、投影或反光";
+    "素材主体及其配色必须与背景色明显区分，不要出现与背景色相同或相近的描边、底板、投影或反光";
 pub(crate) const EDITOR_GREEN_SCREEN_CHARACTER_GUARDRAILS: &str =
-    "角色主体不得带与背景色相同或相近的描边、投影或反光";
-pub(crate) const LEGACY_EDITOR_GREEN_SCREEN_CHARACTER_PROMPT_CLAUSE: &str = "背景固定为单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕，只作为抠像底色；绿幕背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具；角色主体不得带绿色描边、绿色投影或绿色反光";
+    "角色主体及其服饰、道具的颜色必须与背景色明显区分，不得带与背景色相同或相近的描边、投影或反光";
 
 fn editor_screen_background_color_prompt(color: EditorScreenBackgroundColor) -> String {
-    if color.hex == "#00FF00" {
-        return "单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕".to_string();
-    }
     format!(
         "单一纯色背景 {} {} / RGB({},{},{})",
         color.label, color.hex, color.red, color.green, color.blue
diff --git a/server-rs/crates/api-server/src/editor_project.rs b/server-rs/crates/api-server/src/editor_project.rs
index 81253a6e8..a65ff8cdb 100644
--- a/server-rs/crates/api-server/src/editor_project.rs
+++ b/server-rs/crates/api-server/src/editor_project.rs
@@ -64,8 +64,7 @@ use crate::{
     },
     editor_screen_background_decision::{
         EditorScreenBackgroundDecision, EditorScreenBackgroundDecisionInput,
-        EditorScreenBackgroundDecisionKind, format_editor_screen_background_decision_input,
-        resolve_editor_screen_background_color,
+        EditorScreenBackgroundDecisionKind, resolve_editor_screen_background_color,
     },
     generated_image_assets::{
         GeneratedImageAssetAdapter, GeneratedImageAssetDataUrl,
@@ -1358,26 +1357,10 @@ pub(crate) async fn generate_editor_image_for_owner(
 
     let normalized_kind = payload.kind.as_deref().map(str::trim);
     let is_character_generation = matches!(normalized_kind, Some("character"));
-    let screen_background_decision = if is_character_generation {
-        Some(
-            resolve_editor_screen_background_color(
-                state.llm_client(),
-                EditorScreenBackgroundDecisionInput {
-                    kind: EditorScreenBackgroundDecisionKind::Character,
-                    screen_color: payload.screen_color.clone(),
-                    prompt: role_setting.clone(),
-                    icon_descriptions: Vec::new(),
-                    reference_count: payload.reference_image_srcs.as_ref().map_or(0, Vec::len),
-                },
-            )
-            .await?,
-        )
-    } else {
-        None
-    };
-    let screen_color = screen_background_decision
-        .as_ref()
-        .map(|decision| decision.color);
+    // 背景色决策挪到预扣泥点之后（见下方 execute_billable 闭包），避免余额不足 / 生成注定失败时
+    // 仍白发一次 gpt-5-mini 决策。这里先固化决策需要、但随后会被 payload 消费掉的输入。
+    let requested_screen_color = payload.screen_color.clone();
+    let reference_count = payload.reference_image_srcs.as_ref().map_or(0, Vec::len);
     let seg_model = if is_character_generation {
         Some(parse_editor_bgfilter_seg_model(
             payload.seg_model.as_deref(),
@@ -1404,24 +1387,6 @@ pub(crate) async fn generate_editor_image_for_owner(
         has_dimension_options,
         &generation_options,
     );
-    let submitted_prompt = if is_character_generation {
-        build_editor_character_image_prompt(
-            role_setting.as_str(),
-            screen_color.expect("character generation should have screen color"),
-        )
-    } else if is_ui_design_generation {
-        build_editor_ui_design_prompt(
-            role_setting.as_str(),
-            payload
-                .reference_image_srcs
-                .as_ref()
-                .is_some_and(|references| {
-                    references.iter().any(|source| !source.trim().is_empty())
-                }),
-        )
-    } else {
-        role_setting.clone()
-    };
     let failure_context = match normalized_kind {
         Some("character") => "图片画布生成角色形象",
         Some("spec") => "图片画布生成规范",
@@ -1443,6 +1408,9 @@ pub(crate) async fn generate_editor_image_for_owner(
         .filter(|source| !source.is_empty())
         .take(reference_limit)
         .collect::<Vec<_>>();
+    // 决策移入闭包后 payload.reference_image_srcs 已被 reference_sources 消费，
+    // 这里从过滤后的 reference_sources 预先固化 ui-design 的「是否带参考图」布尔。
+    let ui_has_references = !reference_sources.is_empty();
     let settings = require_openai_image_settings(state)?.with_external_api_audit_context(
         request_context,
         caller.audit_subject_user_id.clone(),
@@ -1484,7 +1452,52 @@ pub(crate) async fn generate_editor_image_for_owner(
             Some(generation_options.image_size),
         );
     let generate_operation = async {
-        if generation_options.model == EDITOR_IMAGE_MODEL_NANOBANANA2 {
+        // 背景色决策：预扣泥点之后才发起，仅角色生图需要（决策失败→future 返回 Err→失败退款，
+        // 用户不损失泥点，平台也只在用户确有余额时才付这次 gpt-5-mini 决策）。
+        let screen_background_decision = if is_character_generation {
+            Some(
+                resolve_editor_screen_background_color(
+                    state.llm_client(),
+                    state.creative_agent_gpt5_client(),
+                    EditorScreenBackgroundDecisionInput {
+                        kind: EditorScreenBackgroundDecisionKind::Character,
+                        screen_color: requested_screen_color.clone(),
+                        prompt: role_setting.clone(),
+                        icon_descriptions: Vec::new(),
+                        reference_count,
+                        source_image_data_url: None,
+                    },
+                    Some(&crate::editor_screen_background_decision::EditorScreenBackgroundDecisionAuditContext {
+                        state,
+                        context: crate::external_api_audit::ExternalApiAuditContext {
+                            user_id: caller.audit_subject_user_id.clone(),
+                            profile_id: caller
+                                .audit_project_id
+                                .clone()
+                                .or_else(|| payload.project_id.clone()),
+                            request_id: Some(request_context.request_id().to_string()),
+                        },
+                    }),
+                )
+                .await?,
+            )
+        } else {
+            None
+        };
+        let screen_color = screen_background_decision
+            .as_ref()
+            .map(|decision| decision.color);
+        let submitted_prompt = if is_character_generation {
+            build_editor_character_image_prompt(
+                role_setting.as_str(),
+                screen_color.expect("character generation should have screen color"),
+            )
+        } else if is_ui_design_generation {
+            build_editor_ui_design_prompt(role_setting.as_str(), ui_has_references)
+        } else {
+            role_setting.clone()
+        };
+        let generated = if generation_options.model == EDITOR_IMAGE_MODEL_NANOBANANA2 {
             create_openai_nanobanana_generate_content(
                 &http_client,
                 &settings,
@@ -1496,7 +1509,7 @@ pub(crate) async fn generate_editor_image_for_owner(
                 reference_images.as_slice(),
                 failure_context,
             )
-            .await
+            .await?
         } else if reference_images.is_empty() {
             create_openai_image_generation_with_model(
                 &http_client,
@@ -1509,7 +1522,7 @@ pub(crate) async fn generate_editor_image_for_owner(
                 &[],
                 failure_context,
             )
-            .await
+            .await?
         } else {
             create_openai_image_edit_with_references_and_model(
                 &http_client,
@@ -1522,18 +1535,23 @@ pub(crate) async fn generate_editor_image_for_owner(
                 reference_images.as_slice(),
                 failure_context,
             )
-            .await
-        }
+            .await?
+        };
+        Ok::<_, AppError>((generated, submitted_prompt, screen_background_decision))
     };
-    let generated = execute_billable_asset_operation_with_cost(
-        state,
-        caller.owner_user_id.as_str(),
-        editor_image_generation_billing_asset_kind(normalized_kind),
-        request_context.request_id(),
-        u64::from(configured_price_mud_points),
-        generate_operation,
-    )
-    .await?;
+    let (generated, submitted_prompt, screen_background_decision) =
+        execute_billable_asset_operation_with_cost(
+            state,
+            caller.owner_user_id.as_str(),
+            editor_image_generation_billing_asset_kind(normalized_kind),
+            request_context.request_id(),
+            u64::from(configured_price_mud_points),
+            generate_operation,
+        )
+        .await?;
+    let screen_color = screen_background_decision
+        .as_ref()
+        .map(|decision| decision.color);
     let mut image = generated.images.into_iter().next().ok_or_else(|| {
         AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
             "provider": "vector-engine",
@@ -1552,11 +1570,20 @@ pub(crate) async fn generate_editor_image_for_owner(
             "character-image",
         )
         .await?;
+        let matting_audit = crate::external_api_audit::ExternalApiAuditContext {
+            user_id: caller.audit_subject_user_id.clone(),
+            profile_id: caller
+                .audit_project_id
+                .clone()
+                .or_else(|| payload.project_id.clone()),
+            request_id: Some(request_context.request_id().to_string()),
+        };
         image = remove_editor_generated_screen_background_with_bgfilter(
             state,
             &image,
             screen_color.expect("character generation should have screen color"),
             seg_model.expect("character generation should have BgFilter seg model"),
+            &matting_audit,
         )
         .await?;
     }
@@ -1650,25 +1677,21 @@ fn editor_image_generation_billing_asset_kind(normalized_kind: Option<&str>) ->
     }
 }
 
-fn apply_editor_screen_background_decision_to_generation_inputs(
+pub(crate) fn apply_editor_screen_background_decision_to_generation_inputs(
     generation_inputs: Option<Value>,
     decision: Option<&EditorScreenBackgroundDecision>,
 ) -> Option<Value> {
     let Some(decision) = decision else {
         return generation_inputs;
     };
-    let mut value = generation_inputs?;
-    let Some(fields) = value.get_mut("fields").and_then(Value::as_array_mut) else {
-        return Some(value);
+    let mut value = match generation_inputs {
+        Some(value) if value.is_object() => value,
+        Some(other) => return Some(other),
+        None => json!({ "fields": [], "references": [] }),
     };
-    let resolved_value = format_editor_screen_background_decision_input(decision);
-    for field in fields {
-        let title = field.get("title").and_then(Value::as_str);
-        if title == Some("抠图背景色") {
-            field["value"] = Value::String(resolved_value);
-            break;
-        }
-    }
+    // 抠图背景色是内部自动决策 / 兜底细节，产品契约要求不进用户可见的 generationInputs.fields；
+    // 只写顶层内部可追踪元数据 screenColorHex（不属于用户输入快照，前端展示不读取）。
+    value["screenColorHex"] = Value::String(decision.color.hex.to_string());
     Some(value)
 }
 
@@ -2218,16 +2241,19 @@ async fn remove_editor_generated_screen_background_with_bgfilter(
     image: &DownloadedOpenAiImage,
     screen_color: EditorScreenBackgroundColor,
     seg_model: &str,
+    audit: &crate::external_api_audit::ExternalApiAuditContext,
 ) -> Result<DownloadedOpenAiImage, AppError> {
     if let Some(remaining) = editor_bgfilter_circuit_open_remaining(state) {
+        // 熔断打开只跳过 BgFilter 调用本身，仍要走阿里云兜底；绝不能在 cooldown 内直接退化到
+        // 低质量本地扣色，否则整段冷却期从「双供应商降级」退化成单一本地键色扣除。
         tracing::warn!(
             provider = "bgfilter",
             screen_color = screen_color.hex,
             seg_model,
             cooldown_ms = remaining.as_millis() as u64,
-            "editor_bgfilter_circuit_open_fallback_to_local_screen_background_removal"
+            "editor_bgfilter_circuit_open_fallback_to_aliyun_matting"
         );
-        return remove_editor_generated_green_screen_background(image, screen_color);
+        return fallback_editor_screen_background_removal(state, image, screen_color, audit).await;
     }
 
     match request_editor_generated_screen_background_with_bgfilter(
@@ -2250,8 +2276,67 @@ async fn remove_editor_generated_screen_background_with_bgfilter(
                 seg_model,
                 error = %error,
                 error_details = ?error.details(),
-                "editor_bgfilter_fallback_to_local_screen_background_removal"
+                "editor_bgfilter_fallback_to_aliyun_matting"
             );
+            crate::external_api_audit::record_matting_external_api_failure(
+                state,
+                audit,
+                "bgfilter",
+                state.config.editor_bgfilter_base_url.clone(),
+                "editor-screen-background-removal",
+                "bgfilter_segment",
+                crate::external_api_audit::matting_failure_audit_status_code(&error),
+                crate::external_api_audit::matting_failure_audit_timeout(&error),
+                crate::external_api_audit::matting_failure_audit_latency_ms(&error),
+                error.message().to_string(),
+                crate::external_api_audit::matting_failure_audit_raw_excerpt(&error),
+            )
+            .await;
+            fallback_editor_screen_background_removal(state, image, screen_color, audit).await
+        }
+    }
+}
+
+/// BgFilter 不可用（熔断打开或调用失败）时的统一兜底链：先阿里云通用抠图，失败再退本地键色扣除。
+/// 熔断打开路径与 BgFilter 调用失败路径共用此链，确保 cooldown 内仍是「阿里云 → 本地」而非直接本地。
+async fn fallback_editor_screen_background_removal(
+    state: &AppState,
+    image: &DownloadedOpenAiImage,
+    screen_color: EditorScreenBackgroundColor,
+    audit: &crate::external_api_audit::ExternalApiAuditContext,
+) -> Result<DownloadedOpenAiImage, AppError> {
+    match crate::aliyun_matting::segment_image_with_aliyun_matting(
+        state,
+        image,
+        "editor-screen-background",
+    )
+    .await
+    {
+        Ok(image) => Ok(image),
+        Err(error) => {
+            tracing::warn!(
+                provider = "aliyun-matting",
+                screen_color = screen_color.hex,
+                error = %error,
+                error_details = ?error.details(),
+                "editor_aliyun_matting_fallback_to_local_screen_background_removal"
+            );
+            if crate::external_api_audit::matting_failure_external_call_attempted(&error) {
+                crate::external_api_audit::record_matting_external_api_failure(
+                    state,
+                    audit,
+                    "aliyun-matting",
+                    state.config.aliyun_matting_endpoint.clone(),
+                    "editor-screen-background-removal",
+                    "aliyun_segment",
+                    crate::external_api_audit::matting_failure_audit_status_code(&error),
+                    crate::external_api_audit::matting_failure_audit_timeout(&error),
+                    crate::external_api_audit::matting_failure_audit_latency_ms(&error),
+                    error.message().to_string(),
+                    crate::external_api_audit::matting_failure_audit_raw_excerpt(&error),
+                )
+                .await;
+            }
             remove_editor_generated_green_screen_background(image, screen_color)
         }
     }
@@ -2368,14 +2453,15 @@ async fn request_editor_generated_screen_background_with_bgfilter(
         request = request.header("X-Genarrative-Image-Token", token);
     }
     let response = request.send().await.map_err(|error| {
+        let latency_ms = request_started_at.elapsed().as_millis() as u64;
         tracing::warn!(
             %call_id,
-            elapsed_ms = request_started_at.elapsed().as_millis() as u64,
+            elapsed_ms = latency_ms,
             timeout = error.is_timeout(),
             error = %error,
             "editor_bgfilter_request_failed"
         );
-        map_editor_bgfilter_error(error)
+        map_editor_bgfilter_error(error, latency_ms)
     })?;
     let status = response.status();
     if !status.is_success() {
@@ -2395,6 +2481,7 @@ async fn request_editor_generated_screen_background_with_bgfilter(
                 "provider": "bgfilter",
                 "message": "BgFilter 服务返回非成功状态",
                 "upstreamStatus": status.as_u16(),
+                "latencyMs": request_started_at.elapsed().as_millis() as u64,
                 "upstreamMessage": message.chars().take(500).collect::<String>(),
             })),
         );
@@ -2421,12 +2508,16 @@ async fn request_editor_generated_screen_background_with_bgfilter(
         .get("x-bgfilter-screen-color")
         .and_then(|value| value.to_str().ok())
         .map(ToOwned::to_owned);
-    let bytes = read_editor_image_removal_response_bytes(response, "bgfilter", "BgFilter").await?;
+    let bytes =
+        read_editor_image_removal_response_bytes(response, "bgfilter", "BgFilter", request_started_at)
+            .await?;
     if bytes.is_empty() {
+        // HTTP 已成功但 body 为空属于上游内容缺陷（5xx 归类正确），仍补 latencyMs 与 Aliyun 兜底口径对齐。
         return Err(
             AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
                 "provider": "bgfilter",
                 "message": "BgFilter 服务未返回图片",
+                "latencyMs": request_started_at.elapsed().as_millis() as u64,
             })),
         );
     }
@@ -2552,7 +2643,7 @@ async fn request_editor_background_removal_image(
         .get("x-birefnet-elapsed-ms")
         .and_then(|value| value.to_str().ok())
         .and_then(|value| value.parse::<u64>().ok());
-    let bytes = read_editor_background_removal_bytes(response).await?;
+    let bytes = read_editor_background_removal_bytes(response, request_started_at).await?;
     if bytes.is_empty() {
         return Err(
             AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
@@ -2651,7 +2742,7 @@ fn map_editor_background_removal_error(error: reqwest::Error) -> AppError {
     }))
 }
 
-fn map_editor_bgfilter_error(error: reqwest::Error) -> AppError {
+fn map_editor_bgfilter_error(error: reqwest::Error, latency_ms: u64) -> AppError {
     let status = if error.is_timeout() {
         StatusCode::GATEWAY_TIMEOUT
     } else {
@@ -2661,19 +2752,24 @@ fn map_editor_bgfilter_error(error: reqwest::Error) -> AppError {
         "provider": "bgfilter",
         "message": format!("请求 BgFilter 服务失败：{error}"),
         "timeout": error.is_timeout(),
+        "transport": true,
+        "latencyMs": latency_ms,
     }))
 }
 
 async fn read_editor_background_removal_bytes(
     response: reqwest::Response,
+    request_started_at: Instant,
 ) -> Result<Vec<u8>, AppError> {
-    read_editor_image_removal_response_bytes(response, "birefnet", "抠图服务").await
+    read_editor_image_removal_response_bytes(response, "birefnet", "抠图服务", request_started_at)
+        .await
 }
 
 async fn read_editor_image_removal_response_bytes(
     mut response: reqwest::Response,
     provider: &str,
     service_label: &str,
+    request_started_at: Instant,
 ) -> Result<Vec<u8>, AppError> {
     if response.content_length().is_some_and(|content_length| {
         content_length > EDITOR_BACKGROUND_REMOVAL_MAX_RESPONSE_BYTES as u64
@@ -2687,11 +2783,16 @@ async fn read_editor_image_removal_response_bytes(
         );
     }
     let mut bytes = Vec::new();
+    // response.chunk() 失败属于「HTTP 状态已成功、读 body 时链路断裂」的传输层故障，
+    // 必须打上 transport/timeout/latencyMs/rawExcerpt，否则外部 API 失败审计会把它错记成 502/5xx。
     while let Some(chunk) = response.chunk().await.map_err(|error| {
-        AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
-            "provider": provider,
-            "message": format!("读取{service_label}结果失败：{error}"),
-        }))
+        editor_image_removal_body_read_error(
+            provider,
+            service_label,
+            error.is_timeout(),
+            request_started_at.elapsed().as_millis() as u64,
+            &error.to_string(),
+        )
     })? {
         if bytes.len().saturating_add(chunk.len()) > EDITOR_BACKGROUND_REMOVAL_MAX_RESPONSE_BYTES {
             return Err(
@@ -2707,6 +2808,31 @@ async fn read_editor_image_removal_response_bytes(
     Ok(bytes)
 }
 
+/// 读取抠图上游响应体失败（response.chunk 中断）时构造的传输层失败错误。
+/// 与 `map_editor_bgfilter_error` 对齐：timeout 走 504、其余 502，均带 transport 标记以及
+/// latencyMs / rawExcerpt，供外部 API 失败审计正确归类为 transport 而非 5xx。
+fn editor_image_removal_body_read_error(
+    provider: &str,
+    service_label: &str,
+    is_timeout: bool,
+    latency_ms: u64,
+    error_text: &str,
+) -> AppError {
+    let status = if is_timeout {
+        StatusCode::GATEWAY_TIMEOUT
+    } else {
+        StatusCode::BAD_GATEWAY
+    };
+    AppError::from_status(status).with_details(json!({
+        "provider": provider,
+        "message": format!("读取{service_label}结果失败：{error_text}"),
+        "timeout": is_timeout,
+        "transport": true,
+        "latencyMs": latency_ms,
+        "rawExcerpt": error_text,
+    }))
+}
+
 fn decode_editor_background_removal_image(bytes: &[u8]) -> Result<image::DynamicImage, AppError> {
     decode_editor_removed_background_image(bytes, "birefnet")
 }
@@ -2787,18 +2913,10 @@ pub(crate) async fn generate_editor_icon_spritesheet_for_owner(
     payload: EditorIconSpritesheetGenerationRequest,
 ) -> Result<Json<Value>, AppError> {
     let icon_descriptions = normalize_icon_descriptions(payload.icon_descriptions)?;
-    let screen_background_decision = resolve_editor_screen_background_color(
-        state.llm_client(),
-        EditorScreenBackgroundDecisionInput {
-            kind: EditorScreenBackgroundDecisionKind::IconSpritesheet,
-            screen_color: payload.screen_color.clone(),
-            prompt: icon_descriptions.join("\n"),
-            icon_descriptions: icon_descriptions.clone(),
-            reference_count: 1 + payload.reference_image_srcs.as_ref().map_or(0, Vec::len),
-        },
-    )
-    .await?;
-    let screen_color = screen_background_decision.color;
+    // 背景色决策挪到预扣泥点之后（见下方 execute_billable 闭包），避免余额不足 / 生成注定失败时
+    // 仍白发一次 gpt-5-mini 决策。这里先固化决策需要的输入。
+    let requested_screen_color = payload.screen_color.clone();
+    let reference_count = 1 + payload.reference_image_srcs.as_ref().map_or(0, Vec::len);
     let seg_model = parse_editor_bgfilter_seg_model(payload.seg_model.as_deref())?;
     let mut reference_images =
         Vec::with_capacity(1 + payload.reference_image_srcs.as_ref().map_or(0, Vec::len));
@@ -2843,7 +2961,6 @@ pub(crate) async fn generate_editor_icon_spritesheet_for_owner(
         Some(generation_options.image_size),
     )?;
     let size = generation_options.size.as_str();
-    let prompt = build_editor_icon_spritesheet_prompt(&icon_descriptions, screen_color);
 
     let settings = require_openai_image_settings(state)?.with_external_api_audit_context(
         request_context,
@@ -2854,43 +2971,73 @@ pub(crate) async fn generate_editor_icon_spritesheet_for_owner(
             .or_else(|| payload.project_id.clone()),
     );
     let http_client = build_openai_image_http_client(&settings)?;
-    let generated = execute_billable_asset_operation_with_cost(
-        state,
-        caller.owner_user_id.as_str(),
-        "editor_icon_spritesheet",
-        request_context.request_id(),
-        u64::from(expected_price_mud_points),
-        async {
-            if generation_options.model == EDITOR_IMAGE_MODEL_NANOBANANA2 {
-                create_openai_nanobanana_generate_content(
-                    &http_client,
-                    &settings,
-                    generation_options.model,
-                    prompt.as_str(),
-                    None,
-                    generation_options.aspect_ratio,
-                    generation_options.provider_image_size,
-                    reference_images.as_slice(),
-                    "图片画布生成图标素材 spritesheet",
+    let (generated, prompt, screen_background_decision) =
+        execute_billable_asset_operation_with_cost(
+            state,
+            caller.owner_user_id.as_str(),
+            "editor_icon_spritesheet",
+            request_context.request_id(),
+            u64::from(expected_price_mud_points),
+            async {
+                // 背景色决策：预扣泥点之后才发起（决策失败→future 返回 Err→失败退款）。
+                let screen_background_decision = resolve_editor_screen_background_color(
+                    state.llm_client(),
+                    state.creative_agent_gpt5_client(),
+                    EditorScreenBackgroundDecisionInput {
+                        kind: EditorScreenBackgroundDecisionKind::IconSpritesheet,
+                        screen_color: requested_screen_color.clone(),
+                        prompt: icon_descriptions.join("\n"),
+                        icon_descriptions: icon_descriptions.clone(),
+                        reference_count,
+                        source_image_data_url: None,
+                    },
+                    Some(&crate::editor_screen_background_decision::EditorScreenBackgroundDecisionAuditContext {
+                        state,
+                        context: crate::external_api_audit::ExternalApiAuditContext {
+                            user_id: caller.audit_subject_user_id.clone(),
+                            profile_id: caller
+                                .audit_project_id
+                                .clone()
+                                .or_else(|| payload.project_id.clone()),
+                            request_id: Some(request_context.request_id().to_string()),
+                        },
+                    }),
                 )
-                .await
-            } else {
-                create_openai_image_edit_with_references_and_model(
-                    &http_client,
-                    &settings,
-                    generation_options.model,
-                    prompt.as_str(),
-                    None,
-                    size,
-                    1,
-                    reference_images.as_slice(),
-                    "图片画布生成图标素材 spritesheet",
-                )
-                .await
-            }
-        },
-    )
-    .await?;
+                .await?;
+                let screen_color = screen_background_decision.color;
+                let prompt = build_editor_icon_spritesheet_prompt(&icon_descriptions, screen_color);
+                let generated = if generation_options.model == EDITOR_IMAGE_MODEL_NANOBANANA2 {
+                    create_openai_nanobanana_generate_content(
+                        &http_client,
+                        &settings,
+                        generation_options.model,
+                        prompt.as_str(),
+                        None,
+                        generation_options.aspect_ratio,
+                        generation_options.provider_image_size,
+                        reference_images.as_slice(),
+                        "图片画布生成图标素材 spritesheet",
+                    )
+                    .await?
+                } else {
+                    create_openai_image_edit_with_references_and_model(
+                        &http_client,
+                        &settings,
+                        generation_options.model,
+                        prompt.as_str(),
+                        None,
+                        size,
+                        1,
+                        reference_images.as_slice(),
+                        "图片画布生成图标素材 spritesheet",
+                    )
+                    .await?
+                };
+                Ok::<_, AppError>((generated, prompt, screen_background_decision))
+            },
+        )
+        .await?;
+    let screen_color = screen_background_decision.color;
     let image = generated.images.into_iter().next().ok_or_else(|| {
         AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
             "provider": "vector-engine",
@@ -2908,11 +3055,20 @@ pub(crate) async fn generate_editor_icon_spritesheet_for_owner(
         "spritesheet",
     )
     .await?;
+    let matting_audit = crate::external_api_audit::ExternalApiAuditContext {
+        user_id: caller.audit_subject_user_id.clone(),
+        profile_id: caller
+            .audit_project_id
+            .clone()
+            .or_else(|| payload.project_id.clone()),
+        request_id: Some(request_context.request_id().to_string()),
+    };
     let image = remove_editor_generated_screen_background_with_bgfilter(
         state,
         &image,
         screen_color,
         seg_model,
+        &matting_audit,
     )
     .await?;
     let (spritesheet_width, spritesheet_height) = image::load_from_memory(image.bytes.as_slice())
@@ -3054,21 +3210,14 @@ pub(crate) async fn extract_editor_ui_design_assets_for_owner(
     caller: EditorGenerationCaller,
     payload: EditorUiDesignAssetExtractionRequest,
 ) -> Result<Json<Value>, AppError> {
-    let screen_background_decision = resolve_editor_screen_background_color(
-        state.llm_client(),
-        EditorScreenBackgroundDecisionInput {
-            kind: EditorScreenBackgroundDecisionKind::UiDesignAssetExtraction,
-            screen_color: payload.screen_color.clone(),
-            prompt: format!(
-                "从 UI 设计图提取被红色框选的素材，输出 spritesheet。目标规格 {} {}。",
-                payload.aspect_ratio, payload.image_size
-            ),
-            icon_descriptions: Vec::new(),
-            reference_count: 1 + payload.reference_image_srcs.as_ref().map_or(0, Vec::len),
-        },
-    )
-    .await?;
-    let screen_color = screen_background_decision.color;
+    // 背景色决策挪到预扣泥点之后（见下方 execute_billable 闭包），避免余额不足 / 生成注定失败时
+    // 仍白发一次 gpt-5-mini 决策。这里先固化决策需要的输入。
+    let requested_screen_color = payload.screen_color.clone();
+    let reference_count = 1 + payload.reference_image_srcs.as_ref().map_or(0, Vec::len);
+    let decision_prompt = format!(
+        "从 UI 设计图提取被红色框选的素材，输出 spritesheet。目标规格 {} {}。",
+        payload.aspect_ratio, payload.image_size
+    );
     let seg_model = parse_editor_bgfilter_seg_model(payload.seg_model.as_deref())?;
     let reference_image = parse_editor_reference_image(
         state,
@@ -3119,44 +3268,73 @@ pub(crate) async fn extract_editor_ui_design_assets_for_owner(
             .or_else(|| payload.project_id.clone()),
     );
     let http_client = build_openai_image_http_client(&settings)?;
-    let prompt = editor_ui_design_asset_extraction_prompt(screen_color);
-    let generated = execute_billable_asset_operation_with_cost(
-        state,
-        caller.owner_user_id.as_str(),
-        "editor_ui_design_asset_extraction",
-        request_context.request_id(),
-        u64::from(expected_price_mud_points),
-        async {
-            if generation_options.model == EDITOR_IMAGE_MODEL_NANOBANANA2 {
-                create_openai_nanobanana_generate_content(
-                    &http_client,
-                    &settings,
-                    generation_options.model,
-                    prompt.as_str(),
-                    None,
-                    generation_options.aspect_ratio,
-                    generation_options.provider_image_size,
-                    reference_images.as_slice(),
-                    "图片画布提取UI设计图素材 spritesheet",
+    let (generated, prompt, screen_background_decision) =
+        execute_billable_asset_operation_with_cost(
+            state,
+            caller.owner_user_id.as_str(),
+            "editor_ui_design_asset_extraction",
+            request_context.request_id(),
+            u64::from(expected_price_mud_points),
+            async {
+                // 背景色决策：预扣泥点之后才发起（决策失败→future 返回 Err→失败退款）。
+                let screen_background_decision = resolve_editor_screen_background_color(
+                    state.llm_client(),
+                    state.creative_agent_gpt5_client(),
+                    EditorScreenBackgroundDecisionInput {
+                        kind: EditorScreenBackgroundDecisionKind::UiDesignAssetExtraction,
+                        screen_color: requested_screen_color.clone(),
+                        prompt: decision_prompt.clone(),
+                        icon_descriptions: Vec::new(),
+                        reference_count,
+                        source_image_data_url: None,
+                    },
+                    Some(&crate::editor_screen_background_decision::EditorScreenBackgroundDecisionAuditContext {
+                        state,
+                        context: crate::external_api_audit::ExternalApiAuditContext {
+                            user_id: caller.audit_subject_user_id.clone(),
+                            profile_id: caller
+                                .audit_project_id
+                                .clone()
+                                .or_else(|| payload.project_id.clone()),
+                            request_id: Some(request_context.request_id().to_string()),
+                        },
+                    }),
                 )
-                .await
-            } else {
-                create_openai_image_edit_with_references_and_model(
-                    &http_client,
-                    &settings,
-                    generation_options.model,
-                    prompt.as_str(),
-                    None,
-                    generation_options.size.as_str(),
-                    1,
-                    reference_images.as_slice(),
-                    "图片画布提取UI设计图素材 spritesheet",
-                )
-                .await
-            }
-        },
-    )
-    .await?;
+                .await?;
+                let screen_color = screen_background_decision.color;
+                let prompt = editor_ui_design_asset_extraction_prompt(screen_color);
+                let generated = if generation_options.model == EDITOR_IMAGE_MODEL_NANOBANANA2 {
+                    create_openai_nanobanana_generate_content(
+                        &http_client,
+                        &settings,
+                        generation_options.model,
+                        prompt.as_str(),
+                        None,
+                        generation_options.aspect_ratio,
+                        generation_options.provider_image_size,
+                        reference_images.as_slice(),
+                        "图片画布提取UI设计图素材 spritesheet",
+                    )
+                    .await?
+                } else {
+                    create_openai_image_edit_with_references_and_model(
+                        &http_client,
+                        &settings,
+                        generation_options.model,
+                        prompt.as_str(),
+                        None,
+                        generation_options.size.as_str(),
+                        1,
+                        reference_images.as_slice(),
+                        "图片画布提取UI设计图素材 spritesheet",
+                    )
+                    .await?
+                };
+                Ok::<_, AppError>((generated, prompt, screen_background_decision))
+            },
+        )
+        .await?;
+    let screen_color = screen_background_decision.color;
     let image = generated.images.into_iter().next().ok_or_else(|| {
         AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
             "provider": "vector-engine",
@@ -3174,11 +3352,20 @@ pub(crate) async fn extract_editor_ui_design_assets_for_owner(
         "spritesheet",
     )
     .await?;
+    let matting_audit = crate::external_api_audit::ExternalApiAuditContext {
+        user_id: caller.audit_subject_user_id.clone(),
+        profile_id: caller
+            .audit_project_id
+            .clone()
+            .or_else(|| payload.project_id.clone()),
+        request_id: Some(request_context.request_id().to_string()),
+    };
     let image = remove_editor_generated_screen_background_with_bgfilter(
         state,
         &image,
         screen_color,
         seg_model,
+        &matting_audit,
     )
     .await?;
     let (spritesheet_width, spritesheet_height) = image::load_from_memory(image.bytes.as_slice())
@@ -5587,6 +5774,115 @@ mod tests {
         );
     }
 
+    #[test]
+    fn bgfilter_body_read_failure_audits_as_transport_not_5xx() {
+        // HTTP 状态已成功、但读 body 时链路断裂：外部 API 失败审计必须归类为 transport，
+        // 并保留 latencyMs / rawExcerpt，而不是被错记成 502/5xx。
+        let error = editor_image_removal_body_read_error(
+            "bgfilter",
+            "BgFilter",
+            false,
+            137,
+            "error reading a body from connection: connection reset",
+        );
+
+        assert_eq!(error.status_code(), StatusCode::BAD_GATEWAY);
+        assert_eq!(
+            crate::external_api_audit::matting_failure_audit_status_code(&error),
+            None,
+            "body-read 传输故障不应带 HTTP statusCode，否则会落成 5xx"
+        );
+        assert!(!crate::external_api_audit::matting_failure_audit_timeout(&error));
+        assert_eq!(
+            crate::external_api_audit::matting_failure_audit_latency_ms(&error),
+            Some(137)
+        );
+        assert_eq!(
+            crate::external_api_audit::matting_failure_audit_raw_excerpt(&error).as_deref(),
+            Some("error reading a body from connection: connection reset")
+        );
+    }
+
+    #[test]
+    fn bgfilter_body_read_timeout_maps_to_gateway_timeout_and_transport() {
+        let error =
+            editor_image_removal_body_read_error("bgfilter", "BgFilter", true, 42, "operation timed out");
+
+        assert_eq!(error.status_code(), StatusCode::GATEWAY_TIMEOUT);
+        assert_eq!(
+            crate::external_api_audit::matting_failure_audit_status_code(&error),
+            None
+        );
+        assert!(crate::external_api_audit::matting_failure_audit_timeout(&error));
+        assert_eq!(
+            crate::external_api_audit::matting_failure_audit_latency_ms(&error),
+            Some(42)
+        );
+    }
+
+    fn manual_screen_background_decision(hex: &str) -> EditorScreenBackgroundDecision {
+        EditorScreenBackgroundDecision {
+            color: parse_editor_screen_background_color(Some(hex))
+                .expect("hex should be a known background color candidate"),
+            mode: crate::editor_screen_background_decision::EditorScreenBackgroundDecisionMode::Manual,
+            attempts: 0,
+            fallback: false,
+        }
+    }
+
+    #[test]
+    fn screen_background_decision_records_hex_without_touching_visible_fields() {
+        let decision = manual_screen_background_decision("#B0C2E0");
+
+        // 用户可见的 fields 不被注入抠图背景色，只写内部 screenColorHex。
+        let updated = apply_editor_screen_background_decision_to_generation_inputs(
+            Some(json!({
+                "fields": [{ "title": "角色设定", "value": "红发骑士" }],
+                "references": [],
+            })),
+            Some(&decision),
+        )
+        .expect("generation inputs should be preserved");
+        assert_eq!(updated["screenColorHex"], json!("#B0C2E0"));
+        assert_eq!(
+            updated["fields"],
+            json!([{ "title": "角色设定", "value": "红发骑士" }]),
+        );
+
+        // 无 generation_inputs 时创建骨架并写入内部元数据，fields 保持为空。
+        let created =
+            apply_editor_screen_background_decision_to_generation_inputs(None, Some(&decision))
+                .expect("missing generation inputs should still record the decision");
+        assert_eq!(
+            created,
+            json!({
+                "fields": [],
+                "references": [],
+                "screenColorHex": "#B0C2E0",
+            }),
+        );
+    }
+
+    #[test]
+    fn screen_background_decision_leaves_existing_visible_fields_untouched() {
+        let decision = manual_screen_background_decision("#CFEFFF");
+
+        // 即使旧数据的 fields 里残留了抠图背景色，后端也不修改用户可见字段。
+        let updated = apply_editor_screen_background_decision_to_generation_inputs(
+            Some(json!({
+                "fields": [{ "title": "抠图背景色", "value": "旧值" }],
+                "references": [],
+            })),
+            Some(&decision),
+        )
+        .expect("generation inputs should be preserved");
+        assert_eq!(
+            updated["fields"],
+            json!([{ "title": "抠图背景色", "value": "旧值" }]),
+        );
+        assert_eq!(updated["screenColorHex"], json!("#CFEFFF"));
+    }
+
     fn apply_editor_canvas_generation_completion(
         layers: Value,
         completion: &EditorCanvasGenerationCompletionRequest,
@@ -6257,7 +6553,9 @@ mod tests {
         assert!(prompt.contains("生成游戏角色立绘"));
         assert!(prompt.contains("背景固定为单一纯色背景 暖浅桃色 #FFD6C2 / RGB(255,214,194)"));
         assert!(prompt.contains("纯色背景必须平整无纹理、无渐变、无阴影"));
-        assert!(prompt.contains("角色主体不得带与背景色相同或相近的描边、投影或反光"));
+        assert!(
+            prompt.contains("角色主体及其服饰、道具的颜色必须与背景色明显区分，不得带与背景色相同或相近的描边、投影或反光")
+        );
         assert!(prompt.contains("禁止镜头透视"));
         assert!(prompt.contains("角色设定：菜市场卖菜大妈"));
     }
@@ -6799,7 +7097,9 @@ mod tests {
         assert!(prompt.contains("参考图1的图标素材规范"));
         assert!(prompt.contains("背景必须是单一纯色背景 中度天蓝 #7FB3FF / RGB(127,179,255)"));
         assert!(prompt.contains("平整无纹理、无渐变、无阴影"));
-        assert!(prompt.contains("素材自身不要出现与背景色相同或相近的描边、底板、投影或反光"));
+        assert!(
+            prompt.contains("素材主体及其配色必须与背景色明显区分，不要出现与背景色相同或相近的描边、底板、投影或反光")
+        );
         assert!(prompt.contains("返回按钮、设置按钮、下一关按钮"));
     }
 
@@ -6821,7 +7121,7 @@ mod tests {
                 parse_editor_screen_background_color(None)
                     .expect("default screen color should parse")
             ),
-            "仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用单一纯色背景 浅雾蓝 #CFEFFF / RGB(207,239,255)。纯色背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现与背景色相同或相近的描边、底板、投影或反光。"
+            "仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用单一纯色背景 浅雾蓝 #CFEFFF / RGB(207,239,255)。纯色背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材主体及其配色必须与背景色明显区分，不要出现与背景色相同或相近的描边、底板、投影或反光。"
         );
     }
 
@@ -7344,12 +7644,25 @@ mod tests {
                 "remove_editor_generated_screen_background_with_bgfilter",
             ],
         );
-        assert_function_contains(
+        assert_function_contains_in_order(
             source,
             "async fn remove_editor_generated_screen_background_with_bgfilter",
+            "async fn fallback_editor_screen_background_removal",
+            &[
+                // 熔断打开分支必须先委派统一兜底链（阿里云→本地），不能直接退化本地扣色；
+                // BgFilter 调用失败分支同样走该兜底链。
+                "editor_bgfilter_circuit_open_remaining",
+                "fallback_editor_screen_background_removal",
+                "request_editor_generated_screen_background_with_bgfilter",
+                "fallback_editor_screen_background_removal",
+            ],
+        );
+        assert_function_contains_in_order(
+            source,
+            "async fn fallback_editor_screen_background_removal",
             "async fn request_editor_generated_screen_background_with_bgfilter",
             &[
-                "request_editor_generated_screen_background_with_bgfilter",
+                "segment_image_with_aliyun_matting",
                 "remove_editor_generated_green_screen_background",
             ],
         );
diff --git a/server-rs/crates/api-server/src/editor_screen_background_decision.rs b/server-rs/crates/api-server/src/editor_screen_background_decision.rs
index 021988940..77e3dcc2c 100644
--- a/server-rs/crates/api-server/src/editor_screen_background_decision.rs
+++ b/server-rs/crates/api-server/src/editor_screen_background_decision.rs
@@ -1,4 +1,6 @@
-use platform_llm::{LlmClient, LlmTextRequest};
+use platform_llm::{
+    LlmClient, LlmError, LlmMessage, LlmProvider, LlmResponseReasoningEffort, LlmTextRequest,
+};
 use serde_json::json;
 use tracing::{info, warn};
 
@@ -7,7 +9,16 @@ use crate::{
         EDITOR_SCREEN_BACKGROUND_COLORS, EditorScreenBackgroundColor,
         default_editor_screen_background_color, parse_editor_screen_background_color,
     },
+    editor_screen_background_filter::{
+        ScreenBackgroundColorSafetyReport, decode_image_data_url,
+        filter_editor_screen_background_colors, safety_report_log_json,
+    },
+    external_api_audit::{
+        ExternalApiAuditContext, ExternalApiFailureDraft, is_retryable_external_api_failure,
+        record_external_api_failure,
+    },
     http_error::AppError,
+    state::AppState,
 };
 
 const EDITOR_SCREEN_BACKGROUND_AUTO_VALUE: &str = "auto";
@@ -31,6 +42,7 @@ pub(crate) struct EditorScreenBackgroundDecision {
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub(crate) enum EditorScreenBackgroundDecisionKind {
     Character,
+    CharacterAnimation,
     IconSpritesheet,
     UiDesignAssetExtraction,
 }
@@ -39,10 +51,20 @@ impl EditorScreenBackgroundDecisionKind {
     fn label(self) -> &'static str {
         match self {
             Self::Character => "角色形象生成",
+            Self::CharacterAnimation => "角色动作视频生成",
             Self::IconSpritesheet => "图标素材 spritesheet 生成",
             Self::UiDesignAssetExtraction => "UI 设计图素材提取",
         }
     }
+
+    fn audit_operation_key(self) -> &'static str {
+        match self {
+            Self::Character => "character",
+            Self::CharacterAnimation => "character_animation",
+            Self::IconSpritesheet => "icon_spritesheet",
+            Self::UiDesignAssetExtraction => "ui_design_asset_extraction",
+        }
+    }
 }
 
 #[derive(Clone, Debug)]
@@ -52,11 +74,22 @@ pub(crate) struct EditorScreenBackgroundDecisionInput {
     pub(crate) prompt: String,
     pub(crate) icon_descriptions: Vec<String>,
     pub(crate) reference_count: usize,
+    /// 主体参考图（data URL）。图生视频等主体颜色由参考图决定的场景必须传，
+    /// 让视觉 LLM 按主体实际配色避开撞色背景；纯文生图场景可为 None。
+    pub(crate) source_image_data_url: Option<String>,
+}
+
+/// 自动决策虽可业务降级，但已发出的 LLM 调用失败仍须进入 OTLP 和失败事件审计。
+pub(crate) struct EditorScreenBackgroundDecisionAuditContext<'a> {
+    pub(crate) state: &'a AppState,
+    pub(crate) context: ExternalApiAuditContext,
 }
 
 pub(crate) async fn resolve_editor_screen_background_color(
     llm_client: Option<&LlmClient>,
-    input: EditorScreenBackgroundDecisionInput,
+    vision_llm_client: Option<&LlmClient>,
+    mut input: EditorScreenBackgroundDecisionInput,
+    audit: Option<&EditorScreenBackgroundDecisionAuditContext<'_>>,
 ) -> Result<EditorScreenBackgroundDecision, AppError> {
     if !is_auto_screen_background_color(input.screen_color.as_deref()) {
         return Ok(EditorScreenBackgroundDecision {
@@ -67,7 +100,53 @@ pub(crate) async fn resolve_editor_screen_background_color(
         });
     }
 
-    let fallback_color = default_editor_screen_background_color();
+    let has_source_image = input
+        .source_image_data_url
+        .as_deref()
+        .map(str::trim)
+        .is_some_and(|value| !value.is_empty());
+    // 硬过滤先于 LLM：按参考图前景配色剔除撞色候选，LLM 只在安全集合里做审美选择。
+    // 分析失败（图片不可解码、前景不足）只降级为不过滤，不阻断生成。
+    let safety_report = if has_source_image {
+        resolve_screen_background_safety_report(&input)
+    } else {
+        None
+    };
+    let candidate_colors: Vec<EditorScreenBackgroundColor> = safety_report
+        .as_ref()
+        .map(|report| report.allowed.clone())
+        .unwrap_or_else(|| EDITOR_SCREEN_BACKGROUND_COLORS.to_vec());
+
+    // 决策统一走 VectorEngine gpt-5-mini：有图用视觉档、无图用文本档（两个独立常量），
+    // 都不继承 Ark 默认文本模型（豆包，选色能力弱）。仅当 gpt5 客户端未配置时才降级回默认
+    // llm_client；该默认客户端是纯文本模型（Ark），收到图片分片会被上游 400 拒绝，故先丢弃图片分片。
+    let (llm_client, decision_model) = match vision_llm_client {
+        Some(client) if has_source_image => (
+            Some(client),
+            Some(crate::llm_model_routing::EDITOR_SCREEN_BACKGROUND_VISION_LLM_MODEL),
+        ),
+        Some(client) => (
+            Some(client),
+            Some(crate::llm_model_routing::EDITOR_SCREEN_BACKGROUND_TEXT_LLM_MODEL),
+        ),
+        None => {
+            if has_source_image {
+                warn!(
+                    kind = input.kind.label(),
+                    "editor_screen_background_vision_client_missing_downgrade_to_text"
+                );
+                input.source_image_data_url = None;
+            }
+            (llm_client, None)
+        }
+    };
+
+    // 默认兜底色被过滤掉时，改用危险度最小的候选兜底。
+    let default_color = default_editor_screen_background_color();
+    let fallback_color = match safety_report.as_ref() {
+        Some(report) if !report.contains(default_color.hex) => report.safest,
+        _ => default_color,
+    };
     let Some(llm_client) = llm_client else {
         warn!(
             kind = input.kind.label(),
@@ -83,15 +162,45 @@ pub(crate) async fn resolve_editor_screen_background_color(
     };
 
     let system_prompt = editor_screen_background_decision_system_prompt();
-    let user_prompt = editor_screen_background_decision_user_prompt(&input);
+    let user_prompt =
+        editor_screen_background_decision_user_prompt(&input, &candidate_colors, fallback_color);
+    let source_image_data_url = input
+        .source_image_data_url
+        .as_deref()
+        .map(str::trim)
+        .filter(|value| !value.is_empty());
+    let audit_prompt_chars = system_prompt
+        .chars()
+        .count()
+        .saturating_add(user_prompt.chars().count());
+    let audit_reference_image_count = usize::from(source_image_data_url.is_some());
     let mut last_error: Option<String> = None;
     for attempt in 1..=EDITOR_SCREEN_BACKGROUND_DECISION_MAX_ATTEMPTS {
-        let request = LlmTextRequest::single_turn(system_prompt, user_prompt.as_str())
-            .with_max_tokens(96)
+        let user_message = match source_image_data_url {
+            Some(image_url) => {
+                LlmMessage::user(user_prompt.as_str()).with_image_url(image_url)
+            }
+            None => LlmMessage::user(user_prompt.as_str()),
+        };
+        // 预算要够推理模型（如 gpt-5-mini）先花几百 token 推理、再吐 JSON 答案；
+        // 实测 low 档推理约 320~384 token，取 1024 留足余量。降级客户端遇 stop 提前结束，不会多花。
+        let mut request = LlmTextRequest::new(vec![LlmMessage::system(system_prompt), user_message])
+            .with_max_tokens(1024)
             .with_request_timeout_ms(EDITOR_SCREEN_BACKGROUND_DECISION_TIMEOUT_MS);
+        if let Some(decision_model) = decision_model {
+            // gpt-5-mini 是推理模型（有图视觉档 / 无图文本档均适用）：走 Responses 协议并压到 low
+            // 推理档，否则默认档会把预算全烧在推理上、返回空答案。
+            request = request
+                .with_model(decision_model)
+                .with_responses_api()
+                .with_response_reasoning_effort(LlmResponseReasoningEffort::Low);
+        }
         match llm_client.request_text(request).await {
             Ok(response) => {
-                match parse_editor_screen_background_decision_response(response.content.as_str()) {
+                match parse_editor_screen_background_decision_response(
+                    response.content.as_str(),
+                    &candidate_colors,
+                ) {
                     Some(color) => {
                         info!(
                             kind = input.kind.label(),
@@ -114,6 +223,24 @@ pub(crate) async fn resolve_editor_screen_background_color(
                             message = message.as_str(),
                             "editor_screen_background_auto_decision_invalid_response"
                         );
+                        record_editor_screen_background_decision_failure(
+                            audit,
+                            llm_client,
+                            input.kind,
+                            decision_model,
+                            true,
+                            attempt,
+                            "response_parse",
+                            Some(200),
+                            false,
+                            false,
+                            message.as_str(),
+                            None,
+                            Some(response.content.as_str()),
+                            audit_prompt_chars,
+                            audit_reference_image_count,
+                        )
+                        .await;
                         last_error = Some(message);
                     }
                 }
@@ -126,6 +253,18 @@ pub(crate) async fn resolve_editor_screen_background_color(
                     message = message.as_str(),
                     "editor_screen_background_auto_decision_request_failed"
                 );
+                record_editor_screen_background_decision_llm_error(
+                    audit,
+                    llm_client,
+                    input.kind,
+                    decision_model,
+                    true,
+                    attempt,
+                    &error,
+                    audit_prompt_chars,
+                    audit_reference_image_count,
+                )
+                .await;
                 last_error = Some(message);
             }
         }
@@ -146,6 +285,223 @@ pub(crate) async fn resolve_editor_screen_background_color(
     })
 }
 
+async fn record_editor_screen_background_decision_llm_error(
+    audit: Option<&EditorScreenBackgroundDecisionAuditContext<'_>>,
+    llm_client: &LlmClient,
+    kind: EditorScreenBackgroundDecisionKind,
+    decision_model: Option<&'static str>,
+    uses_responses_api: bool,
+    attempt: u8,
+    error: &LlmError,
+    prompt_chars: usize,
+    reference_image_count: usize,
+) {
+    let (failure_stage, status_code, timeout, retryable, error_source, raw_excerpt) = match error
+    {
+        LlmError::InvalidConfig(_) | LlmError::InvalidRequest(_) => return,
+        LlmError::Timeout { .. } => ("request_timeout", None, true, true, None, None),
+        LlmError::Connectivity { message, .. } => (
+            "request_send",
+            None,
+            false,
+            true,
+            Some(message.as_str()),
+            None,
+        ),
+        LlmError::Upstream {
+            status_code,
+            message,
+        } => (
+            "upstream_status",
+            Some(*status_code),
+            false,
+            is_retryable_external_api_failure(Some(*status_code), false, false),
+            None,
+            Some(message.as_str()),
+        ),
+        LlmError::Deserialize(message) => (
+            "response_parse",
+            Some(200),
+            false,
+            false,
+            Some(message.as_str()),
+            None,
+        ),
+        LlmError::EmptyResponse => ("missing_response", Some(200), false, false, None, None),
+        LlmError::StreamUnavailable => ("response_body", Some(200), false, true, None, None),
+        LlmError::Transport(message) => (
+            "transport",
+            None,
+            false,
+            true,
+            Some(message.as_str()),
+            None,
+        ),
+    };
+    record_editor_screen_background_decision_failure(
+        audit,
+        llm_client,
+        kind,
+        decision_model,
+        uses_responses_api,
+        attempt,
+        failure_stage,
+        status_code,
+        timeout,
+        retryable,
+        error.to_string().as_str(),
+        error_source,
+        raw_excerpt,
+        prompt_chars,
+        reference_image_count,
+    )
+    .await;
+}
+
+#[allow(clippy::too_many_arguments)]
+async fn record_editor_screen_background_decision_failure(
+    audit: Option<&EditorScreenBackgroundDecisionAuditContext<'_>>,
+    llm_client: &LlmClient,
+    kind: EditorScreenBackgroundDecisionKind,
+    decision_model: Option<&'static str>,
+    uses_responses_api: bool,
+    attempt: u8,
+    failure_stage: &'static str,
+    status_code: Option<u16>,
+    timeout: bool,
+    retryable: bool,
+    error_message: &str,
+    error_source: Option<&str>,
+    raw_excerpt: Option<&str>,
+    prompt_chars: usize,
+    reference_image_count: usize,
+) {
+    let Some(audit) = audit else {
+        return;
+    };
+    let draft = build_editor_screen_background_decision_failure_draft(
+        llm_client,
+        kind,
+        decision_model,
+        uses_responses_api,
+        attempt,
+        failure_stage,
+        status_code,
+        timeout,
+        retryable,
+        error_message,
+        error_source,
+        raw_excerpt,
+        prompt_chars,
+        reference_image_count,
+        &audit.context,
+    );
+    record_external_api_failure(audit.state, draft).await;
+}
+
+#[allow(clippy::too_many_arguments)]
+fn build_editor_screen_background_decision_failure_draft(
+    llm_client: &LlmClient,
+    kind: EditorScreenBackgroundDecisionKind,
+    decision_model: Option<&'static str>,
+    uses_responses_api: bool,
+    attempt: u8,
+    failure_stage: &'static str,
+    status_code: Option<u16>,
+    timeout: bool,
+    retryable: bool,
+    error_message: &str,
+    error_source: Option<&str>,
+    raw_excerpt: Option<&str>,
+    prompt_chars: usize,
+    reference_image_count: usize,
+    context: &ExternalApiAuditContext,
+) -> ExternalApiFailureDraft {
+    let endpoint = if uses_responses_api {
+        llm_client.config().responses_url()
+    } else {
+        llm_client.config().chat_completions_url()
+    };
+    let model = decision_model.unwrap_or_else(|| llm_client.config().model());
+    let message = format!(
+        "{}背景色自动决策第{attempt}/{EDITOR_SCREEN_BACKGROUND_DECISION_MAX_ATTEMPTS}次失败：{error_message}",
+        kind.label()
+    );
+    ExternalApiFailureDraft::new(
+        editor_screen_background_decision_provider(llm_client.config().provider()),
+        endpoint,
+        format!(
+            "editor_screen_background_decision:{}:{}",
+            kind.audit_operation_key(),
+            model
+        ),
+        failure_stage,
+        message,
+    )
+    .with_status_code(status_code)
+    .with_timeout(timeout)
+    .with_retryable(retryable)
+    .with_error_source(error_source.map(str::to_string))
+    .with_raw_excerpt(raw_excerpt.map(str::to_string))
+    .with_prompt_chars(Some(prompt_chars))
+    .with_reference_image_count(Some(reference_image_count))
+    .with_image_model(None)
+    .with_audit_context(context)
+}
+
+fn editor_screen_background_decision_provider(provider: LlmProvider) -> &'static str {
+    match provider {
+        LlmProvider::OpenAiCompatible => "vector-engine",
+        LlmProvider::Ark => "ark",
+        LlmProvider::DashScope => "dash-scope",
+    }
+}
+
+/// 解出参考图并做候选色硬过滤；任何一步失败都返回 None（降级为不过滤）。
+fn resolve_screen_background_safety_report(
+    input: &EditorScreenBackgroundDecisionInput,
+) -> Option<ScreenBackgroundColorSafetyReport> {
+    let data_url = input.source_image_data_url.as_deref()?.trim();
+    let Some(image_bytes) = decode_image_data_url(data_url) else {
+        warn!(
+            kind = input.kind.label(),
+            "editor_screen_background_filter_skip_undecodable_data_url"
+        );
+        return None;
+    };
+    // 角色/动作类启用皮肤专属硬否决（皮肤恒暖恒在，是约束最紧的前景）；图标/UI 类只跑统计过滤。
+    let apply_skin_veto = matches!(
+        input.kind,
+        EditorScreenBackgroundDecisionKind::Character
+            | EditorScreenBackgroundDecisionKind::CharacterAnimation
+    );
+    match filter_editor_screen_background_colors(&image_bytes, apply_skin_veto) {
+        Ok(report) => {
+            if report.excluded.is_empty() {
+                info!(
+                    kind = input.kind.label(),
+                    "editor_screen_background_filter_no_exclusion"
+                );
+            } else {
+                info!(
+                    kind = input.kind.label(),
+                    result = %safety_report_log_json(&report),
+                    "editor_screen_background_filter_excluded_colliding_colors"
+                );
+            }
+            Some(report)
+        }
+        Err(reason) => {
+            warn!(
+                kind = input.kind.label(),
+                reason = reason.as_str(),
+                "editor_screen_background_filter_skip_analysis_failed"
+            );
+            None
+        }
+    }
+}
+
 pub(crate) fn is_auto_screen_background_color(value: Option<&str>) -> bool {
     value
         .map(str::trim)
@@ -155,30 +511,16 @@ pub(crate) fn is_auto_screen_background_color(value: Option<&str>) -> bool {
         .unwrap_or(true)
 }
 
-pub(crate) fn format_editor_screen_background_decision_input(
-    decision: &EditorScreenBackgroundDecision,
-) -> String {
-    let resolved = format!("{} {}", decision.color.label, decision.color.hex);
-    match decision.mode {
-        EditorScreenBackgroundDecisionMode::Manual => resolved,
-        EditorScreenBackgroundDecisionMode::Auto => {
-            if decision.fallback {
-                format!("自动 -> {resolved}（兜底）")
-            } else {
-                format!("自动 -> {resolved}")
-            }
-        }
-    }
-}
-
 fn editor_screen_background_decision_system_prompt() -> &'static str {
-    "你是游戏素材生图的抠图背景色决策器。根据任务和用户输入，从候选列表中选择一个最不容易与主体混淆、最适合后续扣除的纯色背景。只能返回 JSON：{\"hex\":\"#RRGGBB\"}。不要解释，不要返回候选列表外的颜色。"
+    "你是游戏素材生图的抠图背景色决策器。根据任务和用户输入，从候选列表中选择一个最不容易与主体混淆、最适合后续扣除的纯色背景。如果附带了主体参考图，必须以图中主体（含服饰、道具、光效）的实际配色为准，选择色相距离最远的候选色，忽略图中已有的背景或透明区域。只能返回 JSON：{\"hex\":\"#RRGGBB\"}。不要解释，不要返回候选列表外的颜色。"
 }
 
 fn editor_screen_background_decision_user_prompt(
     input: &EditorScreenBackgroundDecisionInput,
+    candidate_colors: &[EditorScreenBackgroundColor],
+    fallback_color: EditorScreenBackgroundColor,
 ) -> String {
-    let colors = EDITOR_SCREEN_BACKGROUND_COLORS
+    let colors = candidate_colors
         .iter()
         .map(|color| {
             format!(
@@ -188,16 +530,23 @@ fn editor_screen_background_decision_user_prompt(
         })
         .collect::<Vec<_>>()
         .join("\n");
+    let has_source_image = input
+        .source_image_data_url
+        .as_deref()
+        .map(str::trim)
+        .is_some_and(|value| !value.is_empty());
     let context = json!({
         "task": input.kind.label(),
         "userPrompt": input.prompt,
         "iconDescriptions": input.icon_descriptions,
         "referenceCount": input.reference_count,
+        "hasSourceImage": has_source_image,
         "selectionCriteria": [
             "优先选择与主体、主题色、UI 面板底色、发光效果和描边明显区分的背景色",
             "避免选择可能出现在主体、服饰、道具、按钮、图标或 UI 面板里的颜色",
+            "有主体参考图时以图中主体实际配色为准，文本描述只作辅助",
             "角色类优先低干扰浅色，图标和 UI 提取类优先更高对比但仍保持纯净",
-            "信息不足时选择浅雾蓝 #CFEFFF"
+            format!("信息不足时选择{} {}", fallback_color.label, fallback_color.hex)
         ],
     });
     format!("候选背景色：\n{colors}\n\n任务上下文 JSON：\n{context}")
@@ -205,27 +554,32 @@ fn editor_screen_background_decision_user_prompt(
 
 fn parse_editor_screen_background_decision_response(
     content: &str,
+    candidate_colors: &[EditorScreenBackgroundColor],
 ) -> Option<EditorScreenBackgroundColor> {
     let trimmed = content.trim();
     let json_source = extract_json_object(trimmed).unwrap_or(trimmed);
     if let Ok(value) = serde_json::from_str::<serde_json::Value>(json_source) {
         if let Some(hex) = value.get("hex").and_then(serde_json::Value::as_str) {
-            return find_editor_screen_background_color(hex);
+            return find_editor_screen_background_color(candidate_colors, hex);
         }
         if let Some(hex) = value
             .get("screenColor")
             .or_else(|| value.get("screen_color"))
             .and_then(serde_json::Value::as_str)
         {
-            return find_editor_screen_background_color(hex);
+            return find_editor_screen_background_color(candidate_colors, hex);
         }
     }
-    find_hex_in_text(trimmed).and_then(find_editor_screen_background_color)
+    find_hex_in_text(trimmed)
+        .and_then(|hex| find_editor_screen_background_color(candidate_colors, hex))
 }
 
-fn find_editor_screen_background_color(value: &str) -> Option<EditorScreenBackgroundColor> {
+fn find_editor_screen_background_color(
+    candidate_colors: &[EditorScreenBackgroundColor],
+    value: &str,
+) -> Option<EditorScreenBackgroundColor> {
     let normalized = value.trim().to_ascii_uppercase();
-    EDITOR_SCREEN_BACKGROUND_COLORS
+    candidate_colors
         .iter()
         .copied()
         .find(|color| color.hex == normalized)
@@ -264,6 +618,7 @@ mod tests {
     #[tokio::test]
     async fn manual_screen_background_decision_keeps_selected_color() {
         let decision = resolve_editor_screen_background_color(
+            None,
             None,
             EditorScreenBackgroundDecisionInput {
                 kind: EditorScreenBackgroundDecisionKind::Character,
@@ -271,7 +626,9 @@ mod tests {
                 prompt: "绿色史莱姆".to_string(),
                 icon_descriptions: Vec::new(),
                 reference_count: 1,
+                source_image_data_url: None,
             },
+            None,
         )
         .await
         .expect("manual color should parse");
@@ -284,6 +641,7 @@ mod tests {
     #[tokio::test]
     async fn auto_screen_background_decision_falls_back_without_llm() {
         let decision = resolve_editor_screen_background_color(
+            None,
             None,
             EditorScreenBackgroundDecisionInput {
                 kind: EditorScreenBackgroundDecisionKind::IconSpritesheet,
@@ -291,7 +649,9 @@ mod tests {
                 prompt: String::new(),
                 icon_descriptions: vec!["金币按钮".to_string()],
                 reference_count: 2,
+                source_image_data_url: None,
             },
+            None,
         )
         .await
         .expect("auto fallback should succeed");
@@ -304,6 +664,7 @@ mod tests {
     #[tokio::test]
     async fn missing_screen_background_decision_uses_auto_default() {
         let decision = resolve_editor_screen_background_color(
+            None,
             None,
             EditorScreenBackgroundDecisionInput {
                 kind: EditorScreenBackgroundDecisionKind::UiDesignAssetExtraction,
@@ -311,7 +672,9 @@ mod tests {
                 prompt: "提取 UI 按钮".to_string(),
                 icon_descriptions: Vec::new(),
                 reference_count: 1,
+                source_image_data_url: None,
             },
+            None,
         )
         .await
         .expect("missing color should use auto fallback");
@@ -323,9 +686,11 @@ mod tests {
 
     #[test]
     fn parses_llm_json_background_decision() {
-        let color =
-            parse_editor_screen_background_decision_response("```json\n{\"hex\":\"#a8f7f0\"}\n```")
-                .expect("known color should parse");
+        let color = parse_editor_screen_background_decision_response(
+            "```json\n{\"hex\":\"#a8f7f0\"}\n```",
+            &EDITOR_SCREEN_BACKGROUND_COLORS,
+        )
+        .expect("known color should parse");
 
         assert_eq!(color.label, "高对比浅青");
     }
@@ -333,7 +698,315 @@ mod tests {
     #[test]
     fn rejects_unknown_llm_background_decision() {
         assert!(
-            parse_editor_screen_background_decision_response("{\"hex\":\"#123456\"}").is_none()
+            parse_editor_screen_background_decision_response(
+                "{\"hex\":\"#123456\"}",
+                &EDITOR_SCREEN_BACKGROUND_COLORS,
+            )
+            .is_none()
         );
     }
+
+    #[test]
+    fn rejects_filtered_out_llm_background_decision() {
+        // LLM 返回了被硬过滤剔除的颜色（不在候选集里）时按无效响应处理。
+        let allowed = [EDITOR_SCREEN_BACKGROUND_COLORS[0]];
+        assert!(
+            parse_editor_screen_background_decision_response("{\"hex\":\"#7FB3FF\"}", &allowed)
+                .is_none()
+        );
+    }
+
+    #[test]
+    fn decision_invalid_response_failure_audit_is_success_response_parse() {
+        use platform_llm::{LlmConfig, LlmProvider};
+
+        let client = LlmClient::new(
+            LlmConfig::new(
+                LlmProvider::OpenAiCompatible,
+                "https://vector.example/v1".to_string(),
+                "test-key".to_string(),
+                "fallback-model".to_string(),
+                20_000,
+                0,
+                1,
+            )
+            .expect("test LLM config should build"),
+        )
+        .expect("test LLM client should build");
+        let audit = build_editor_screen_background_decision_failure_draft(
+            &client,
+            EditorScreenBackgroundDecisionKind::Character,
+            Some("gpt-5-mini"),
+            true,
+            3,
+            "response_parse",
+            Some(200),
+            false,
+            false,
+            "LLM 返回了无法识别的背景色",
+            None,
+            Some("{\"hex\":\"#123456\"}"),
+            456,
+            0,
+            &ExternalApiAuditContext {
+                user_id: Some("user-1".to_string()),
+                profile_id: Some("project-1".to_string()),
+                request_id: Some("request-1".to_string()),
+            },
+        );
+        let tracking =
+            crate::external_api_audit::build_external_api_failure_tracking_draft(&audit);
+
+        assert_eq!(audit.provider, "vector-engine");
+        assert_eq!(audit.endpoint, "https://vector.example/v1/responses");
+        assert_eq!(
+            audit.operation,
+            "editor_screen_background_decision:character:gpt-5-mini"
+        );
+        assert_eq!(audit.failure_stage, "response_parse");
+        assert_eq!(audit.status_code, Some(200));
+        assert!(!audit.retryable);
+        assert_eq!(tracking.metadata["statusClass"], "2xx");
+        assert_eq!(tracking.metadata["promptChars"], 456);
+        assert_eq!(tracking.metadata["referenceImageCount"], 0);
+        assert_eq!(tracking.metadata["rawExcerpt"], "{\"hex\":\"#123456\"}");
+        assert_eq!(tracking.metadata["userId"], "user-1");
+        assert_eq!(tracking.metadata["profileId"], "project-1");
+        assert_eq!(tracking.metadata["requestId"], "request-1");
+    }
+
+    #[test]
+    fn decision_timeout_failure_audit_keeps_transport_semantics() {
+        use platform_llm::{LlmConfig, LlmProvider};
+
+        let client = LlmClient::new(
+            LlmConfig::new(
+                LlmProvider::OpenAiCompatible,
+                "https://vector.example/v1".to_string(),
+                "test-key".to_string(),
+                "fallback-model".to_string(),
+                20_000,
+                0,
+                1,
+            )
+            .expect("test LLM config should build"),
+        )
+        .expect("test LLM client should build");
+        let audit = build_editor_screen_background_decision_failure_draft(
+            &client,
+            EditorScreenBackgroundDecisionKind::CharacterAnimation,
+            Some("gpt-5-mini"),
+            true,
+            3,
+            "request_timeout",
+            None,
+            true,
+            true,
+            "LLM 请求超时，累计尝试 2 次",
+            None,
+            None,
+            789,
+            1,
+            &ExternalApiAuditContext::default(),
+        );
+        let tracking =
+            crate::external_api_audit::build_external_api_failure_tracking_draft(&audit);
+
+        assert_eq!(audit.failure_stage, "request_timeout");
+        assert_eq!(audit.status_code, None);
+        assert!(audit.timeout);
+        assert!(audit.retryable);
+        assert_eq!(tracking.metadata["statusClass"], "transport");
+        assert_eq!(tracking.metadata["promptChars"], 789);
+        assert_eq!(tracking.metadata["referenceImageCount"], 1);
+    }
+
+    #[tokio::test]
+    async fn auto_decision_fallback_avoids_colliding_default_color() {
+        use base64::Engine as _;
+        use image::{Rgba, RgbaImage};
+
+        // 前景是与默认兜底色（浅雾蓝 #CFEFFF）同色的实心块：
+        // 无 LLM 时兜底不能再落在被硬过滤剔除的默认色上。
+        let mut image = RgbaImage::from_pixel(64, 64, Rgba([0, 0, 0, 0]));
+        for y in 16..48 {
+            for x in 16..48 {
+                image.put_pixel(x, y, Rgba([207, 239, 255, 255]));
+            }
+        }
+        let mut bytes = Vec::new();
+        image::DynamicImage::ImageRgba8(image)
+            .write_to(
+                &mut std::io::Cursor::new(&mut bytes),
+                image::ImageFormat::Png,
+            )
+            .expect("test image should encode");
+        let data_url = format!(
+            "data:image/png;base64,{}",
+            base64::engine::general_purpose::STANDARD.encode(&bytes)
+        );
+
+        let decision = resolve_editor_screen_background_color(
+            None,
+            None,
+            EditorScreenBackgroundDecisionInput {
+                kind: EditorScreenBackgroundDecisionKind::CharacterAnimation,
+                screen_color: Some("auto".to_string()),
+                prompt: "起跳动作".to_string(),
+                icon_descriptions: Vec::new(),
+                reference_count: 1,
+                source_image_data_url: Some(data_url),
+            },
+            None,
+        )
+        .await
+        .expect("decision should fall back");
+
+        assert!(decision.fallback);
+        assert_ne!(
+            decision.color.hex, "#CFEFFF",
+            "默认兜底色与前景撞色时应改用危险度最小的候选"
+        );
+    }
+
+    // 真机联调：按 build_creative_agent_gpt5_client 的方式组 VectorEngine 客户端，直接跑
+    // resolve_editor_screen_background_color 的完整代码路径（无图文本档 + 有图视觉档），
+    // 验证决策请求真的打到 VectorEngine 并被解析成候选色（decision.fallback == false）。
+    // 凭证从仓库根 .env.local / .env.secrets.local 读，需要真实 VECTOR_ENGINE_* 才有意义。
+    // 运行：cargo test -p api-server --manifest-path server-rs/Cargo.toml \
+    //         editor_screen_background_decision::tests::live -- --ignored --nocapture
+    fn read_live_env(key: &str) -> Option<String> {
+        use std::collections::BTreeMap;
+        use std::path::PathBuf;
+
+        let repo_root = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+            .join("..")
+            .join("..")
+            .join("..");
+        let mut map: BTreeMap<String, String> = BTreeMap::new();
+        for name in [".env.local", ".env.secrets.local", ".env"] {
+            let path = repo_root.join(name);
+            let Ok(content) = std::fs::read_to_string(&path) else {
+                continue;
+            };
+            for line in content.lines() {
+                let trimmed = line.trim();
+                if trimmed.is_empty() || trimmed.starts_with('#') || !trimmed.contains('=') {
+                    continue;
+                }
+                let (k, v) = trimmed.split_once('=').unwrap();
+                let v = v.trim().trim_matches('"').trim_matches('\'');
+                // 先出现的文件优先（.env.local > .env.secrets.local > .env），与服务端 dotenv 顺序一致。
+                map.entry(k.trim().to_string()).or_insert_with(|| v.to_string());
+            }
+        }
+        std::env::var(key).ok().or_else(|| map.get(key).cloned())
+    }
+
+    fn build_live_vector_engine_client() -> Option<LlmClient> {
+        use platform_llm::{LlmConfig, LlmProvider};
+
+        let base_url = read_live_env("VECTOR_ENGINE_BASE_URL")?;
+        let api_key = read_live_env("VECTOR_ENGINE_API_KEY")?;
+        // 与 state.rs build_creative_agent_gpt5_client 一致：规整到以 /v1 结尾。
+        let base_url = if base_url.trim_end_matches('/').ends_with("/v1") {
+            base_url.trim_end_matches('/').to_string()
+        } else {
+            format!("{}/v1", base_url.trim_end_matches('/'))
+        };
+        let config = LlmConfig::new(
+            LlmProvider::OpenAiCompatible,
+            base_url,
+            api_key,
+            crate::llm_model_routing::EDITOR_SCREEN_BACKGROUND_TEXT_LLM_MODEL.to_string(),
+            60_000,
+            0,
+            500,
+        )
+        .expect("live VectorEngine LlmConfig should build");
+        Some(LlmClient::new(config).expect("live VectorEngine LlmClient should build"))
+    }
+
+    fn solid_source_image_data_url() -> String {
+        use base64::Engine as _;
+        use image::{Rgba, RgbaImage};
+
+        let image = RgbaImage::from_pixel(64, 64, Rgba([120, 180, 120, 255]));
+        let mut bytes = Vec::new();
+        image::DynamicImage::ImageRgba8(image)
+            .write_to(&mut std::io::Cursor::new(&mut bytes), image::ImageFormat::Png)
+            .expect("test image should encode");
+        format!(
+            "data:image/png;base64,{}",
+            base64::engine::general_purpose::STANDARD.encode(&bytes)
+        )
+    }
+
+    #[tokio::test]
+    #[ignore = "真机联调：需要 .env.local / .env.secrets.local 中真实 VECTOR_ENGINE_* 凭证"]
+    async fn live_screen_background_decision_hits_vector_engine_without_image() {
+        let Some(client) = build_live_vector_engine_client() else {
+            panic!("缺少 VECTOR_ENGINE_BASE_URL / VECTOR_ENGINE_API_KEY，无法真机联调");
+        };
+        let decision = resolve_editor_screen_background_color(
+            None,
+            Some(&client),
+            EditorScreenBackgroundDecisionInput {
+                kind: EditorScreenBackgroundDecisionKind::Character,
+                screen_color: Some("auto".to_string()),
+                prompt: "赛博朋克风格的机械猫，霓虹蓝紫主体".to_string(),
+                icon_descriptions: Vec::new(),
+                reference_count: 1,
+                source_image_data_url: None,
+            },
+            None,
+        )
+        .await
+        .expect("live 无图决策应成功");
+
+        eprintln!(
+            "[live 无图] mode={:?} hex={} label={} attempts={} fallback={}",
+            decision.mode, decision.color.hex, decision.color.label, decision.attempts, decision.fallback
+        );
+        assert_eq!(decision.mode, EditorScreenBackgroundDecisionMode::Auto);
+        assert!(
+            !decision.fallback,
+            "若走到兜底说明 LLM 没答复（VectorEngine 未被成功调用或响应解析失败）"
+        );
+        assert!(decision.attempts >= 1);
+    }
+
+    #[tokio::test]
+    #[ignore = "真机联调：需要 .env.local / .env.secrets.local 中真实 VECTOR_ENGINE_* 凭证"]
+    async fn live_screen_background_decision_hits_vector_engine_with_image() {
+        let Some(client) = build_live_vector_engine_client() else {
+            panic!("缺少 VECTOR_ENGINE_BASE_URL / VECTOR_ENGINE_API_KEY，无法真机联调");
+        };
+        let decision = resolve_editor_screen_background_color(
+            None,
+            Some(&client),
+            EditorScreenBackgroundDecisionInput {
+                kind: EditorScreenBackgroundDecisionKind::CharacterAnimation,
+                screen_color: Some("auto".to_string()),
+                prompt: "角色起跳动作".to_string(),
+                icon_descriptions: Vec::new(),
+                reference_count: 1,
+                source_image_data_url: Some(solid_source_image_data_url()),
+            },
+            None,
+        )
+        .await
+        .expect("live 有图决策应成功");
+
+        eprintln!(
+            "[live 有图] mode={:?} hex={} label={} attempts={} fallback={}",
+            decision.mode, decision.color.hex, decision.color.label, decision.attempts, decision.fallback
+        );
+        assert_eq!(decision.mode, EditorScreenBackgroundDecisionMode::Auto);
+        assert!(
+            !decision.fallback,
+            "若走到兜底说明视觉 LLM 没答复（VectorEngine 未被成功调用或响应解析失败）"
+        );
+        assert!(decision.attempts >= 1);
+    }
 }
diff --git a/server-rs/crates/api-server/src/editor_screen_background_filter.rs b/server-rs/crates/api-server/src/editor_screen_background_filter.rs
new file mode 100644
index 000000000..59c70a521
--- /dev/null
+++ b/server-rs/crates/api-server/src/editor_screen_background_filter.rs
@@ -0,0 +1,632 @@
+//! 背景色候选硬过滤：统计参考图前景配色，剔除会与前景（尤其皮肤）撞色的候选背景色。
+//!
+//! 抠图管线对像素的判定由 ΔE（Lab 距离）和色调投影（像素色度在背景色调方向上的投影）
+//! 两个量决定：ΔE ≤ 6.7 的前景近乎必被抹除；ΔE ≤ 28 且投影 ≥ 4（同色调壳层）时命运交给
+//! 后端 matting，同色调恰是其最不可靠的区间。经验上危险质量占前景 0.5% 以上就会出现
+//! 可见破损，故以此为剔除阈值。
+//!
+//! 角色/动作类另加皮肤专属硬否决（三判据取并集）：动漫皮肤恒暖且恒在，是约束最紧的前景。
+//! Rule 1 由危险质量的 ΔE 门（28）承载；Rule 2 皮肤色度在候选色调方向投影 < 4（同色调否决，
+//! 覆盖 trimap hue-split 与 cross-check 削薄）；Rule 3 候选与最亮皮肤的 RGB 合成距离 ≥ 52
+//! （两个都很浅的暖色在 RGB 天然接近，Lab ΔE 防不住，是第二条判死路径）。
+//! 三条的净效果是把角色候选压进冷区（蓝/青/紫），LLM 只在安全候选里做审美选择。
+
+use std::collections::HashMap;
+
+use base64::Engine as _;
+use image::GenericImageView;
+use serde_json::json;
+
+use crate::editor_green_screen::{EDITOR_SCREEN_BACKGROUND_COLORS, EditorScreenBackgroundColor};
+
+/// 危险格 ΔE 上限：超过它的前景像素被管线稳定判为前景。实测第 13 帧损伤发生在 ΔE 22–30
+/// （前景最近分位 p0.5≈28），故取 28 覆盖真实杀伤半径；proj 门保证异色调 bin 不被误伤。
+const DANGER_DELTA_E: f64 = 28.0;
+/// 无条件危险 ΔE 上限：低于它的前景像素不看色调也近乎必被抹除。
+const SURE_LOSS_DELTA_E: f64 = 6.7;
+/// 色调投影阈值：投影低于它（色度与背景色调近正交）的像素会被规则救回。
+const DANGER_HUE_PROJECTION: f64 = 4.0;
+/// 危险质量占比达到该值即剔除候选色。
+const DANGER_MASS_EXCLUSION_RATIO: f64 = 0.005;
+/// 单个颜色桶低于该质量占比视为噪声（残留背景、孤立杂色），不参与危险统计。
+const BIN_MASS_FLOOR_RATIO: f64 = 0.001;
+/// 分析用缩略图最长边。
+const ANALYSIS_MAX_EDGE: u32 = 192;
+/// 参考图解码边长上限：源图直接来自请求体 data URL，缺省 `image::Limits` 无尺寸上限、
+/// 仅 512MiB alloc 兜底，12MB 请求体即可构造巨幅压缩图（解压炸弹）在缩图前撑爆内存。
+const ANALYSIS_SOURCE_MAX_DIMENSION: u32 = 8192;
+/// 参考图解码分配上限。与 api-server BgFilter 结果解码口径一致（128MiB）。
+const ANALYSIS_SOURCE_MAX_ALLOC_BYTES: u64 = 128 * 1024 * 1024;
+/// 不透明图边框背景估计：主色覆盖率达到该值才认为边框是平坦背景。
+const BORDER_BACKGROUND_MIN_COVERAGE: f64 = 0.5;
+/// 不透明图中与边框背景色 ΔE 不超过该值的像素按背景剔除。
+const BORDER_BACKGROUND_DELTA_E: f64 = 12.0;
+
+// 皮肤 bin 判定：高 L*、a*/b* 双正的暖色，且质量足够。
+const SKIN_MIN_LIGHTNESS: f64 = 55.0;
+const SKIN_MIN_A: f64 = 3.0;
+const SKIN_MIN_B: f64 = 8.0;
+/// 皮肤 bin 质量下限：低到能保护小脸（远景角色脸可能只占前景零点几个百分点）。
+const SKIN_BIN_MASS_FLOOR_RATIO: f64 = 0.001;
+/// Rule 2：皮肤色度在候选色调方向的投影达到该值即同色调撞色，否决。
+const SKIN_HUE_PROJECTION_LIMIT: f64 = 4.0;
+/// Rule 3：候选与最亮皮肤的 RGB 合成距离（0–255）低于该值即过近，否决。取 52 是管线 RGB 通路
+/// bg_conf 冲到 0.5 的反解并留余量；不取完全沉默半径 68，否则会误杀已验证安全的 #CFEFFF（L2≈66）。
+const SKIN_MIN_RGB_DISTANCE: f64 = 52.0;
+
+#[derive(Clone, Debug)]
+pub(crate) struct ScreenBackgroundColorSafetyReport {
+    /// 过滤后仍可用的候选色（保持调色板顺序），保证非空。
+    pub(crate) allowed: Vec<EditorScreenBackgroundColor>,
+    /// 被剔除的候选色及其危险质量占比。
+    pub(crate) excluded: Vec<(EditorScreenBackgroundColor, f64)>,
+    /// 兜底色：皮肤安全候选里危险质量最小者（无皮肤安全候选时退回全局最小）。
+    pub(crate) safest: EditorScreenBackgroundColor,
+}
+
+impl ScreenBackgroundColorSafetyReport {
+    pub(crate) fn contains(&self, hex: &str) -> bool {
+        self.allowed.iter().any(|color| color.hex == hex)
+    }
+
+    #[cfg(test)]
+    pub(crate) fn excluded_summary(&self) -> String {
+        self.excluded
+            .iter()
+            .map(|(color, ratio)| format!("{} {}({:.1}‰)", color.label, color.hex, ratio * 1000.0))
+            .collect::<Vec<_>>()
+            .join(", ")
+    }
+}
+
+/// 从 image data URL 解出图片字节；非图片或无法解码时返回 None。
+pub(crate) fn decode_image_data_url(value: &str) -> Option<Vec<u8>> {
+    let body = value.trim().strip_prefix("data:")?;
+    let (mime_type, data) = body.split_once(";base64,")?;
+    if !mime_type.trim().starts_with("image/") {
+        return None;
+    }
+    base64::engine::general_purpose::STANDARD
+        .decode(data.trim())
+        .ok()
+        .filter(|bytes| !bytes.is_empty())
+}
+
+/// 有界解码参考图：套上尺寸 / 分配上限，防止解压炸弹在缩图前撑爆内存。
+fn decode_analysis_image_within_limits(bytes: &[u8]) -> Result<image::DynamicImage, String> {
+    use std::io::Cursor;
+
+    let mut reader = image::ImageReader::new(Cursor::new(bytes))
+        .with_guessed_format()
+        .map_err(|error| format!("参考图无法识别格式：{error}"))?;
+    let mut limits = image::Limits::default();
+    limits.max_image_width = Some(ANALYSIS_SOURCE_MAX_DIMENSION);
+    limits.max_image_height = Some(ANALYSIS_SOURCE_MAX_DIMENSION);
+    limits.max_alloc = Some(ANALYSIS_SOURCE_MAX_ALLOC_BYTES);
+    reader.limits(limits);
+    reader
+        .decode()
+        .map_err(|error| format!("参考图无法解码：{error}"))
+}
+
+/// 按参考图前景配色过滤候选背景色。`apply_skin_veto` 为 true（角色/动作类）时，检测到皮肤 bin
+/// 还会启用 Rule 2/3 皮肤硬否决。失败（图片不可解码、前景不足）返回原因字符串，
+/// 调用方应降级为不过滤，而不是阻断生成。
+pub(crate) fn filter_editor_screen_background_colors(
+    image_bytes: &[u8],
+    apply_skin_veto: bool,
+) -> Result<ScreenBackgroundColorSafetyReport, String> {
+    let image = decode_analysis_image_within_limits(image_bytes)?;
+    let (width, height) = image.dimensions();
+    if width == 0 || height == 0 {
+        return Err("参考图尺寸为空".to_string());
+    }
+    let image = if width.max(height) > ANALYSIS_MAX_EDGE {
+        // 最近邻缩放不混色：双线性会把前景像素和透明/背景像素调和出不存在的颜色。
+        image.resize(
+            ANALYSIS_MAX_EDGE,
+            ANALYSIS_MAX_EDGE,
+            image::imageops::FilterType::Nearest,
+        )
+    } else {
+        image
+    };
+    let rgba = image.to_rgba8();
+
+    let histogram = build_foreground_histogram(&rgba)?;
+    let total_mass = histogram.total_mass;
+    // 皮肤约束基准：最亮的皮肤 bin（RGB 上最贴近浅色背景，是判据最紧点）。
+    let skin = if apply_skin_veto {
+        histogram.brightest_skin_bin()
+    } else {
+        None
+    };
+
+    let mut allowed = Vec::new();
+    let mut excluded = Vec::new();
+    let mut safest = EDITOR_SCREEN_BACKGROUND_COLORS[0];
+    let mut safest_ratio = f64::INFINITY;
+    for color in EDITOR_SCREEN_BACKGROUND_COLORS {
+        let danger_ratio = danger_mass(&histogram, color) / total_mass;
+        let skin_unsafe = skin
+            .as_ref()
+            .is_some_and(|reference| candidate_collides_with_skin(reference, color));
+        // 兜底只在皮肤安全候选里挑危险质量最小者，避免把撞肤色（可能危险质量很低）兜回来。
+        if !skin_unsafe && danger_ratio < safest_ratio {
+            safest_ratio = danger_ratio;
+            safest = color;
+        }
+        if danger_ratio >= DANGER_MASS_EXCLUSION_RATIO || skin_unsafe {
+            excluded.push((color, danger_ratio));
+        } else {
+            allowed.push(color);
+        }
+    }
+    if safest_ratio.is_infinite() {
+        // 所有候选都皮肤不安全：退回全局危险质量最小者。
+        for color in EDITOR_SCREEN_BACKGROUND_COLORS {
+            let danger_ratio = danger_mass(&histogram, color) / total_mass;
+            if danger_ratio < safest_ratio {
+                safest_ratio = danger_ratio;
+                safest = color;
+            }
+        }
+    }
+    if allowed.is_empty() {
+        allowed.push(safest);
+        excluded.retain(|(color, _)| color != &safest);
+    }
+    Ok(ScreenBackgroundColorSafetyReport {
+        allowed,
+        excluded,
+        safest,
+    })
+}
+
+/// 皮肤约束基准：最亮皮肤 bin 的 Lab 色度与 RGB 均值。
+struct SkinReference {
+    lab: [f64; 3],
+    rgb: [f64; 3],
+}
+
+struct ForegroundHistogram {
+    bins: HashMap<(i32, i32, i32), HistogramBin>,
+    total_mass: f64,
+}
+
+impl ForegroundHistogram {
+    /// 取最亮的皮肤 bin 作为约束基准；没有合格皮肤 bin（纯蓝机器人等）时返回 None。
+    fn brightest_skin_bin(&self) -> Option<SkinReference> {
+        let mass_floor = self.total_mass * SKIN_BIN_MASS_FLOOR_RATIO;
+        self.bins
+            .values()
+            .filter(|bin| bin.mass >= mass_floor)
+            .filter_map(|bin| {
+                let lab = bin.mean();
+                (lab[0] > SKIN_MIN_LIGHTNESS && lab[1] > SKIN_MIN_A && lab[2] > SKIN_MIN_B)
+                    .then(|| SkinReference {
+                        lab,
+                        rgb: bin.mean_rgb(),
+                    })
+            })
+            .max_by(|left, right| {
+                left.lab[0]
+                    .partial_cmp(&right.lab[0])
+                    .unwrap_or(std::cmp::Ordering::Equal)
+            })
+    }
+}
+
+#[derive(Default)]
+struct HistogramBin {
+    mass: f64,
+    sum_l: f64,
+    sum_a: f64,
+    sum_b: f64,
+    sum_red: f64,
+    sum_green: f64,
+    sum_blue: f64,
+}
+
+impl HistogramBin {
+    fn mean(&self) -> [f64; 3] {
+        [
+            self.sum_l / self.mass,
+            self.sum_a / self.mass,
+            self.sum_b / self.mass,
+        ]
+    }
+
+    fn mean_rgb(&self) -> [f64; 3] {
+        [
+            self.sum_red / self.mass,
+            self.sum_green / self.mass,
+            self.sum_blue / self.mass,
+        ]
+    }
+}
+
+const BIN_L_STEP: f64 = 8.0;
+const BIN_AB_STEP: f64 = 6.0;
+
+fn bin_key(lab: [f64; 3]) -> (i32, i32, i32) {
+    (
+        (lab[0] / BIN_L_STEP).floor() as i32,
+        (lab[1] / BIN_AB_STEP).floor() as i32,
+        (lab[2] / BIN_AB_STEP).floor() as i32,
+    )
+}
+
+fn build_foreground_histogram(rgba: &image::RgbaImage) -> Result<ForegroundHistogram, String> {
+    let has_transparency = rgba.pixels().any(|pixel| pixel.0[3] < 250);
+    let mut bins: HashMap<(i32, i32, i32), HistogramBin> = HashMap::new();
+    let mut total_mass = 0.0;
+    let mut add = |lab: [f64; 3], rgb: [f64; 3], weight: f64| {
+        let bin = bins.entry(bin_key(lab)).or_default();
+        bin.mass += weight;
+        bin.sum_l += lab[0] * weight;
+        bin.sum_a += lab[1] * weight;
+        bin.sum_b += lab[2] * weight;
+        bin.sum_red += rgb[0] * weight;
+        bin.sum_green += rgb[1] * weight;
+        bin.sum_blue += rgb[2] * weight;
+        total_mass += weight;
+    };
+
+    if has_transparency {
+        // alpha² 加权：半透明羽化带（残留背景最集中的位置）权重自然趋零，
+        // 实心小区域（如角色的脸）质量不受损。
+        for pixel in rgba.pixels() {
+            let [red, green, blue, alpha] = pixel.0;
+            if alpha == 0 {
+                continue;
+            }
+            let opacity = f64::from(alpha) / 255.0;
+            add(
+                srgb_to_lab(red, green, blue),
+                [f64::from(red), f64::from(green), f64::from(blue)],
+                opacity * opacity,
+            );
+        }
+    } else {
+        // 不透明图：用边框主色估计原背景，剔除与其相近的像素；边框不平坦则全图算前景。
+        let border_background = estimate_border_background(rgba);
+        for pixel in rgba.pixels() {
+            let [red, green, blue, _] = pixel.0;
+            let lab = srgb_to_lab(red, green, blue);
+            if let Some(background_lab) = border_background {
+                if delta_e(lab, background_lab) <= BORDER_BACKGROUND_DELTA_E {
+                    continue;
+                }
+            }
+            add(
+                lab,
+                [f64::from(red), f64::from(green), f64::from(blue)],
+                1.0,
+            );
+        }
+    }
+
+    let pixel_count = f64::from(rgba.width()) * f64::from(rgba.height());
+    if total_mass < pixel_count * 0.01 {
+        return Err("参考图前景像素不足，无法做背景色安全分析".to_string());
+    }
+    Ok(ForegroundHistogram { bins, total_mass })
+}
+
+/// 估计不透明图的边框背景色：边框环里主导颜色桶覆盖率足够高才认为存在平坦背景。
+fn estimate_border_background(rgba: &image::RgbaImage) -> Option<[f64; 3]> {
+    let (width, height) = rgba.dimensions();
+    let ring = (width.min(height) / 32).max(1);
+    let mut bins: HashMap<(i32, i32, i32), HistogramBin> = HashMap::new();
+    let mut total = 0.0;
+    for (x, y, pixel) in rgba.enumerate_pixels() {
+        let on_border = x < ring
+            || y < ring
+            || x >= width.saturating_sub(ring)
+            || y >= height.saturating_sub(ring);
+        if !on_border {
+            continue;
+        }
+        let [red, green, blue, _] = pixel.0;
+        let lab = srgb_to_lab(red, green, blue);
+        let bin = bins.entry(bin_key(lab)).or_default();
+        bin.mass += 1.0;
+        bin.sum_l += lab[0];
+        bin.sum_a += lab[1];
+        bin.sum_b += lab[2];
+        total += 1.0;
+    }
+    let dominant = bins.values().max_by(|left, right| {
+        left.mass
+            .partial_cmp(&right.mass)
+            .unwrap_or(std::cmp::Ordering::Equal)
+    })?;
+    (dominant.mass / total >= BORDER_BACKGROUND_MIN_COVERAGE).then(|| dominant.mean())
+}
+
+/// 候选背景色的危险质量：落入「ΔE ≤ 6.7 无条件」或「ΔE ≤ 28 且同色调（投影 ≥ 4）」的前景质量之和。
+fn danger_mass(histogram: &ForegroundHistogram, color: EditorScreenBackgroundColor) -> f64 {
+    let background_lab = srgb_to_lab(color.red, color.green, color.blue);
+    let chroma_norm = background_lab[1].hypot(background_lab[2]);
+    let mass_floor = histogram.total_mass * BIN_MASS_FLOOR_RATIO;
+    let mut danger = 0.0;
+    for bin in histogram.bins.values() {
+        if bin.mass < mass_floor {
+            continue;
+        }
+        let mean = bin.mean();
+        let distance = delta_e(mean, background_lab);
+        if distance > DANGER_DELTA_E {
+            continue;
+        }
+        let projection = if chroma_norm > 1e-6 {
+            (mean[1] * background_lab[1] + mean[2] * background_lab[2]) / chroma_norm
+        } else {
+            mean[1].hypot(mean[2])
+        };
+        if distance <= SURE_LOSS_DELTA_E || projection >= DANGER_HUE_PROJECTION {
+            danger += bin.mass;
+        }
+    }
+    danger
+}
+
+/// 皮肤专属硬否决（Rule 2 + Rule 3）：皮肤色度在候选色调方向投影 ≥ 4（同色调），
+/// 或候选与最亮皮肤的 RGB 合成距离 < 52（两个浅暖色天然接近）。任一命中即否决。
+fn candidate_collides_with_skin(skin: &SkinReference, color: EditorScreenBackgroundColor) -> bool {
+    let background_lab = srgb_to_lab(color.red, color.green, color.blue);
+    let chroma_norm = background_lab[1].hypot(background_lab[2]);
+    // Rule 2：近中性灰候选无色调可撞（chroma≈0），投影记 0，交给 Rule 3 的亮度分离判定。
+    let projection = if chroma_norm > 1e-6 {
+        (skin.lab[1] * background_lab[1] + skin.lab[2] * background_lab[2]) / chroma_norm
+    } else {
+        0.0
+    };
+    if projection >= SKIN_HUE_PROJECTION_LIMIT {
+        return true;
+    }
+    let delta_red = f64::from(color.red) - skin.rgb[0];
+    let delta_green = f64::from(color.green) - skin.rgb[1];
+    let delta_blue = f64::from(color.blue) - skin.rgb[2];
+    let rgb_distance =
+        (delta_red * delta_red + delta_green * delta_green + delta_blue * delta_blue).sqrt();
+    rgb_distance < SKIN_MIN_RGB_DISTANCE
+}
+
+fn delta_e(left: [f64; 3], right: [f64; 3]) -> f64 {
+    let dl = left[0] - right[0];
+    let da = left[1] - right[1];
+    let db = left[2] - right[2];
+    (dl * dl + da * da + db * db).sqrt()
+}
+
+fn srgb_to_lab(red: u8, green: u8, blue: u8) -> [f64; 3] {
+    fn linearize(channel: u8) -> f64 {
+        let value = f64::from(channel) / 255.0;
+        if value <= 0.04045 {
+            value / 12.92
+        } else {
+            ((value + 0.055) / 1.055).powf(2.4)
+        }
+    }
+    let (r, g, b) = (linearize(red), linearize(green), linearize(blue));
+    let x = r * 0.4124564 + g * 0.3575761 + b * 0.1804375;
+    let y = r * 0.2126729 + g * 0.7151522 + b * 0.0721750;
+    let z = r * 0.0193339 + g * 0.1191920 + b * 0.9503041;
+    fn transfer(t: f64) -> f64 {
+        if t > 0.008856 {
+            t.cbrt()
+        } else {
+            7.787 * t + 16.0 / 116.0
+        }
+    }
+    let (fx, fy, fz) = (
+        transfer(x / 0.95047),
+        transfer(y / 1.0),
+        transfer(z / 1.08883),
+    );
+    [116.0 * fy - 16.0, 500.0 * (fx - fy), 200.0 * (fy - fz)]
+}
+
+/// 供日志使用的过滤结果 JSON。
+pub(crate) fn safety_report_log_json(
+    report: &ScreenBackgroundColorSafetyReport,
+) -> serde_json::Value {
+    json!({
+        "allowed": report.allowed.iter().map(|color| color.hex).collect::<Vec<_>>(),
+        "excluded": report
+            .excluded
+            .iter()
+            .map(|(color, ratio)| json!({ "hex": color.hex, "dangerPermille": (ratio * 1000.0 * 10.0).round() / 10.0 }))
+            .collect::<Vec<_>>(),
+        "safest": report.safest.hex,
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use image::{Rgba, RgbaImage};
+
+    fn encode_png(image: &RgbaImage) -> Vec<u8> {
+        let mut bytes = Vec::new();
+        image::DynamicImage::ImageRgba8(image.clone())
+            .write_to(
+                &mut std::io::Cursor::new(&mut bytes),
+                image::ImageFormat::Png,
+            )
+            .expect("test image should encode");
+        bytes
+    }
+
+    fn transparent_image_with_center_block(color: [u8; 3]) -> RgbaImage {
+        let mut image = RgbaImage::from_pixel(64, 64, Rgba([0, 0, 0, 0]));
+        for y in 16..48 {
+            for x in 16..48 {
+                image.put_pixel(x, y, Rgba([color[0], color[1], color[2], 255]));
+            }
+        }
+        image
+    }
+
+    fn report_for(image: &RgbaImage, apply_skin_veto: bool) -> ScreenBackgroundColorSafetyReport {
+        filter_editor_screen_background_colors(&encode_png(image), apply_skin_veto)
+            .expect("filter should analyze the test image")
+    }
+
+    #[test]
+    fn skin_bearing_character_excludes_warm_keeps_cool() {
+        // 亮暖肤块：Rule 2/3 应同时剔除暖桃与淡黄（两次真实事故的撞色），保留冷色。
+        let report = report_for(&transparent_image_with_center_block([250, 224, 200]), true);
+
+        assert!(
+            report.excluded.iter().any(|(color, _)| color.hex == "#FFD6C2"),
+            "肤色前景应剔除暖浅桃色，excluded: {}",
+            report.excluded_summary()
+        );
+        assert!(
+            report.excluded.iter().any(|(color, _)| color.hex == "#FFF2A8"),
+            "肤色前景应剔除淡黄（Rule 2/3 关键新覆盖），excluded: {}",
+            report.excluded_summary()
+        );
+        assert!(report.contains("#CFEFFF"), "冷色浅雾蓝应保留");
+        assert_ne!(report.safest.hex, "#FFD6C2");
+        assert_ne!(report.safest.hex, "#FFF2A8");
+    }
+
+    #[test]
+    fn skin_veto_gating_only_matters_for_minority_skin() {
+        // 大面积暗中性前景 + 极小肤块（占前景 ~0.3%，低于危险质量阈值 0.5%）：
+        // 关闭皮肤否决时统计过滤抓不到淡黄；开启时皮肤规则应抓到。这正是「小脸」场景。
+        let mut image = RgbaImage::from_pixel(64, 64, Rgba([0, 0, 0, 0]));
+        for y in 0..56 {
+            for x in 0..54 {
+                image.put_pixel(x, y, Rgba([40, 40, 40, 255])); // 3024 px 暗中性，不撞任何浅候选
+            }
+        }
+        for y in 60..63 {
+            for x in 60..63 {
+                image.put_pixel(x, y, Rgba([250, 224, 200, 255])); // 9 px 肤块 ≈ 0.3% 前景
+            }
+        }
+
+        let disabled = report_for(&image, false);
+        assert!(
+            disabled.contains("#FFF2A8"),
+            "关闭皮肤否决时小肤块不足以统计剔除淡黄，excluded: {}",
+            disabled.excluded_summary()
+        );
+
+        let enabled = report_for(&image, true);
+        assert!(
+            enabled.excluded.iter().any(|(color, _)| color.hex == "#FFF2A8"),
+            "开启皮肤否决时淡黄应被剔除，excluded: {}",
+            enabled.excluded_summary()
+        );
+    }
+
+    #[test]
+    fn no_skin_detected_skips_skin_veto() {
+        // 无皮肤 bin（纯青前景）即使 apply_skin_veto=true 也不否决暖色。
+        let report = report_for(&transparent_image_with_center_block([0, 180, 180]), true);
+        assert!(
+            report.contains("#FFD6C2"),
+            "无皮肤时暖桃不应被皮肤规则剔除，excluded: {}",
+            report.excluded_summary()
+        );
+    }
+
+    #[test]
+    fn blue_foreground_excludes_blue_candidate() {
+        let report = report_for(&transparent_image_with_center_block([127, 179, 255]), false);
+
+        assert!(
+            report.excluded.iter().any(|(color, _)| color.hex == "#7FB3FF"),
+            "蓝色前景应剔除中度天蓝，excluded: {}",
+            report.excluded_summary()
+        );
+        assert!(report.contains("#FFD6C2"), "暖浅桃色应保留");
+    }
+
+    #[test]
+    fn semi_transparent_fringe_does_not_exclude_candidates() {
+        // 前景是红色实心块，另有 100 个 alpha=32 的中度天蓝残留像素（模拟没滤净的旧背景羽化带）。
+        let mut image = transparent_image_with_center_block([200, 30, 30]);
+        let mut placed = 0u32;
+        'outer: for y in 0..16u32 {
+            for x in 0..64u32 {
+                if placed >= 100 {
+                    break 'outer;
+                }
+                image.put_pixel(x, y, Rgba([127, 179, 255, 32]));
+                placed += 1;
+            }
+        }
+
+        let report = report_for(&image, false);
+        assert!(
+            report.contains("#7FB3FF"),
+            "半透明残留不应剔除候选色，excluded: {}",
+            report.excluded_summary()
+        );
+    }
+
+    #[test]
+    fn opaque_flat_background_is_not_counted_as_foreground() {
+        // 不透明图：浅雾蓝底 + 深红主体。若边框背景估计失效，浅雾蓝会被误判撞色。
+        let mut image = RgbaImage::from_pixel(64, 64, Rgba([207, 239, 255, 255]));
+        for y in 24..40 {
+            for x in 24..40 {
+                image.put_pixel(x, y, Rgba([139, 0, 0, 255]));
+            }
+        }
+
+        let report = report_for(&image, false);
+        assert!(
+            report.contains("#CFEFFF"),
+            "平坦背景应被剔除出前景统计，excluded: {}",
+            report.excluded_summary()
+        );
+    }
+
+    #[test]
+    fn all_candidates_dangerous_keeps_safest_only() {
+        // 前景铺满全部候选色，任何候选都撞色 → 只保留危险度最小的一个。
+        let stripe = 6u32;
+        let width = EDITOR_SCREEN_BACKGROUND_COLORS.len() as u32 * stripe;
+        let mut image = RgbaImage::from_pixel(width, 64, Rgba([0, 0, 0, 0]));
+        for (index, color) in EDITOR_SCREEN_BACKGROUND_COLORS.iter().enumerate() {
+            let x_start = index as u32 * stripe;
+            for y in 0..64 {
+                for x in x_start..x_start + stripe {
+                    image.put_pixel(x, y, Rgba([color.red, color.green, color.blue, 255]));
+                }
+            }
+        }
+
+        let report = report_for(&image, false);
+        assert_eq!(report.allowed.len(), 1);
+        assert_eq!(report.allowed[0].hex, report.safest.hex);
+    }
+
+    #[test]
+    fn fully_transparent_image_fails_analysis() {
+        let image = RgbaImage::from_pixel(32, 32, Rgba([0, 0, 0, 0]));
+        assert!(filter_editor_screen_background_colors(&encode_png(&image), true).is_err());
+    }
+
+    #[test]
+    fn decodes_image_data_url() {
+        let image = transparent_image_with_center_block([10, 20, 30]);
+        let bytes = encode_png(&image);
+        let data_url = format!(
+            "data:image/png;base64,{}",
+            base64::engine::general_purpose::STANDARD.encode(&bytes)
+        );
+
+        assert_eq!(decode_image_data_url(&data_url), Some(bytes));
+        assert_eq!(decode_image_data_url("data:video/mp4;base64,AAAA"), None);
+        assert_eq!(decode_image_data_url("not a data url"), None);
+    }
+}
diff --git a/server-rs/crates/api-server/src/external_api_audit.rs b/server-rs/crates/api-server/src/external_api_audit.rs
index 11a104d57..e62d3a0fb 100644
--- a/server-rs/crates/api-server/src/external_api_audit.rs
+++ b/server-rs/crates/api-server/src/external_api_audit.rs
@@ -6,7 +6,7 @@ use serde_json::{Value, json};
 use time::OffsetDateTime;
 use uuid::Uuid;
 
-use crate::{state::AppState, tracking::TrackingEventDraft};
+use crate::{http_error::AppError, state::AppState, tracking::TrackingEventDraft};
 
 pub(crate) const EXTERNAL_API_FAILURE_EVENT_KEY: &str = "external_api_call_failure";
 pub(crate) const EXTERNAL_API_AUDIT_MODULE_KEY: &str = "external-api";
@@ -130,6 +130,144 @@ impl ExternalApiFailureDraft {
         self.request_id = request_id;
         self
     }
+
+    pub(crate) fn with_audit_context(mut self, context: &ExternalApiAuditContext) -> Self {
+        self.user_id = context.user_id.clone();
+        self.profile_id = context.profile_id.clone();
+        self.request_id = context.request_id.clone();
+        self
+    }
+}
+
+/// 外部 API 失败审计的调用方上下文（用户 / 档案 / 请求 id）。
+#[derive(Clone, Debug, Default)]
+pub(crate) struct ExternalApiAuditContext {
+    pub(crate) user_id: Option<String>,
+    pub(crate) profile_id: Option<String>,
+    pub(crate) request_id: Option<String>,
+}
+
+/// 抠图供应商（BgFilter / 阿里云通用抠图）调用失败的统一失败审计入口。
+/// 即使随后兜底成功，供应商故障也必须进入 OTLP + tracking_event，不能只 warn! 后静默。
+#[allow(clippy::too_many_arguments)]
+pub(crate) async fn record_matting_external_api_failure(
+    state: &AppState,
+    context: &ExternalApiAuditContext,
+    provider: &'static str,
+    endpoint: String,
+    operation: &'static str,
+    failure_stage: &'static str,
+    status_code: Option<u16>,
+    timeout: bool,
+    latency_ms: Option<u64>,
+    error_message: String,
+    raw_excerpt: Option<String>,
+) {
+    let draft = build_matting_external_api_failure_draft(
+        provider,
+        endpoint,
+        operation,
+        failure_stage,
+        status_code,
+        timeout,
+        latency_ms,
+        error_message,
+        raw_excerpt,
+        context,
+    );
+    record_external_api_failure(state, draft).await;
+}
+
+#[allow(clippy::too_many_arguments)]
+fn build_matting_external_api_failure_draft(
+    provider: &'static str,
+    endpoint: String,
+    operation: &'static str,
+    failure_stage: &'static str,
+    status_code: Option<u16>,
+    timeout: bool,
+    latency_ms: Option<u64>,
+    error_message: String,
+    raw_excerpt: Option<String>,
+    context: &ExternalApiAuditContext,
+) -> ExternalApiFailureDraft {
+    // status_code=None ⟺ statusClass=transport（见 status_class）：DNS / 连接重置 / 读体中断 / 超时
+    // 这类传输层失败没有上游 HTTP 状态。它们必须与 "transport failures actionable" 语义一致，
+    // 记为 retryable=true，否则 statusClass=transport 却 retryable=false 会误导告警 / 重试分析。
+    let has_transport_error = status_code.is_none();
+    ExternalApiFailureDraft::new(provider, endpoint, operation, failure_stage, error_message)
+        .with_status_code(status_code)
+        .with_optional_status_class(Some(status_class(status_code)))
+        .with_timeout(timeout)
+        .with_retryable(is_retryable_external_api_failure(
+            status_code,
+            timeout,
+            has_transport_error,
+        ))
+        .with_latency_ms(latency_ms)
+        .with_raw_excerpt(raw_excerpt)
+        .with_audit_context(context)
+}
+
+pub(crate) fn matting_failure_audit_status_code(error: &AppError) -> Option<u16> {
+    error
+        .details()
+        .and_then(|details| details.get("upstreamStatus"))
+        .and_then(Value::as_u64)
+        .and_then(|value| u16::try_from(value).ok())
+        .or_else(|| {
+            if matting_failure_audit_is_transport(error) {
+                None
+            } else {
+                Some(error.status_code().as_u16())
+            }
+        })
+}
+
+fn matting_failure_audit_is_transport(error: &AppError) -> bool {
+    matting_failure_audit_timeout(error)
+        || error
+            .details()
+            .and_then(|details| details.get("transport"))
+            .and_then(Value::as_bool)
+            .unwrap_or(false)
+}
+
+pub(crate) fn matting_failure_audit_timeout(error: &AppError) -> bool {
+    error
+        .details()
+        .and_then(|details| details.get("timeout"))
+        .and_then(Value::as_bool)
+        .unwrap_or(false)
+}
+
+pub(crate) fn matting_failure_audit_latency_ms(error: &AppError) -> Option<u64> {
+    error
+        .details()
+        .and_then(|details| details.get("latencyMs"))
+        .and_then(Value::as_u64)
+}
+
+pub(crate) fn matting_failure_external_call_attempted(error: &AppError) -> bool {
+    error
+        .details()
+        .and_then(|details| details.get("externalCallAttempted"))
+        .and_then(Value::as_bool)
+        .unwrap_or(true)
+}
+
+pub(crate) fn matting_failure_audit_raw_excerpt(error: &AppError) -> Option<String> {
+    error
+        .details()
+        .and_then(|details| {
+            details
+                .get("upstreamMessage")
+                .or_else(|| details.get("rawExcerpt"))
+        })
+        .and_then(Value::as_str)
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .map(|value| value.chars().take(800).collect())
 }
 
 pub(crate) fn build_external_api_failure_draft_from_platform_image_audit(
@@ -306,19 +444,15 @@ fn build_external_api_failure_metadata(failure: &ExternalApiFailureDraft) -> Val
     metadata
 }
 
-#[cfg(test)]
 pub(crate) fn is_retryable_external_api_failure(
     status_code: Option<u16>,
     timeout: bool,
     connect: bool,
 ) -> bool {
+    // 429 Too Many Requests / 408 Request Timeout / 5xx 视为可重试。
     timeout
         || connect
-        || status_code.is_some_and(|status| {
-            status == StatusCode::TOO_MANY_REQUESTS.as_u16()
-                || status == StatusCode::REQUEST_TIMEOUT.as_u16()
-                || status >= 500
-        })
+        || status_code.is_some_and(|status| status == 429 || status == 408 || status >= 500)
 }
 
 fn record_external_api_failure_otlp(failure: &ExternalApiFailureDraft) {
@@ -439,6 +573,53 @@ mod tests {
         assert!(!is_retryable_external_api_failure(Some(400), false, false));
     }
 
+    #[test]
+    fn matting_failure_draft_marks_non_timeout_transport_retryable() {
+        // status_code=None、timeout=false 的非超时 transport 失败（DNS / 连接重置 / 读体中断）：
+        // statusClass 必须是 transport 且 retryable=true，否则与 "transport failures actionable" 冲突。
+        let draft = build_matting_external_api_failure_draft(
+            "bgfilter",
+            "https://bgfilter.example/remove-background".to_string(),
+            "editor-screen-background-removal",
+            "bgfilter_segment",
+            None,
+            false,
+            Some(67),
+            "请求 BgFilter 服务失败：dns error".to_string(),
+            Some("dns error".to_string()),
+            &ExternalApiAuditContext::default(),
+        );
+
+        assert_eq!(draft.status_code, None);
+        assert_eq!(draft.status_class, Some("transport"));
+        assert!(!draft.timeout);
+        assert!(
+            draft.retryable,
+            "非超时 transport 失败应当 retryable=true，与 statusClass=transport 保持一致"
+        );
+    }
+
+    #[test]
+    fn matting_failure_draft_keeps_client_error_non_retryable() {
+        // 真实上游 4xx（非 429 / 408）不是传输故障，仍应 retryable=false，不能被误判为可重试。
+        let draft = build_matting_external_api_failure_draft(
+            "aliyun-matting",
+            "imageseg.example".to_string(),
+            "editor-screen-background-removal",
+            "aliyun_segment",
+            Some(400),
+            false,
+            Some(12),
+            "通用抠图接口返回失败（HTTP 400，Code=InvalidImage）：bad image".to_string(),
+            None,
+            &ExternalApiAuditContext::default(),
+        );
+
+        assert_eq!(draft.status_code, Some(400));
+        assert_eq!(draft.status_class, Some("4xx"));
+        assert!(!draft.retryable);
+    }
+
     #[test]
     fn app_error_status_class_can_override_successful_upstream_status() {
         let draft = build_external_api_failure_tracking_draft(
@@ -456,4 +637,132 @@ mod tests {
         assert_eq!(draft.metadata["statusCode"], 200);
         assert_eq!(draft.metadata["statusClass"], "5xx");
     }
+
+    #[test]
+    fn matting_failure_audit_uses_upstream_status_instead_of_wrapped_status() {
+        let error = AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+            "provider": "bgfilter",
+            "message": "BgFilter 服务返回非成功状态",
+            "upstreamStatus": 429,
+            "upstreamMessage": "too many requests",
+            "latencyMs": 345,
+        }));
+
+        let status_code = matting_failure_audit_status_code(&error);
+        let timeout = matting_failure_audit_timeout(&error);
+        let tracking = build_external_api_failure_tracking_draft(
+            &ExternalApiFailureDraft::new(
+                "bgfilter",
+                "https://bgfilter.example/remove-background",
+                "editor-screen-background-removal",
+                "bgfilter_segment",
+                error.message(),
+            )
+            .with_status_code(status_code)
+            .with_optional_status_class(Some(status_class(status_code)))
+            .with_timeout(timeout)
+            .with_latency_ms(matting_failure_audit_latency_ms(&error))
+            .with_retryable(is_retryable_external_api_failure(
+                status_code,
+                timeout,
+                false,
+            ))
+            .with_raw_excerpt(matting_failure_audit_raw_excerpt(&error)),
+        );
+
+        assert_eq!(tracking.metadata["statusCode"], 429);
+        assert_eq!(tracking.metadata["statusClass"], "4xx");
+        assert_eq!(tracking.metadata["timeout"], false);
+        assert_eq!(tracking.metadata["retryable"], true);
+        assert_eq!(tracking.metadata["latencyMs"], 345);
+        assert_eq!(tracking.metadata["rawExcerpt"], "too many requests");
+    }
+
+    #[test]
+    fn matting_failure_audit_keeps_transport_timeout_classification() {
+        let error = AppError::from_status(StatusCode::GATEWAY_TIMEOUT).with_details(json!({
+            "provider": "bgfilter",
+            "message": "请求 BgFilter 服务失败：operation timed out",
+            "timeout": true,
+        }));
+
+        let status_code = matting_failure_audit_status_code(&error);
+        let timeout = matting_failure_audit_timeout(&error);
+        let tracking = build_external_api_failure_tracking_draft(
+            &ExternalApiFailureDraft::new(
+                "bgfilter",
+                "https://bgfilter.example/remove-background",
+                "editor-screen-background-removal",
+                "bgfilter_segment",
+                error.message(),
+            )
+            .with_status_code(status_code)
+            .with_optional_status_class(Some(status_class(status_code)))
+            .with_timeout(timeout)
+            .with_retryable(is_retryable_external_api_failure(
+                status_code,
+                timeout,
+                false,
+            )),
+        );
+
+        assert_eq!(tracking.metadata["statusCode"], Value::Null);
+        assert_eq!(tracking.metadata["statusClass"], "transport");
+        assert_eq!(tracking.metadata["timeout"], true);
+        assert_eq!(tracking.metadata["retryable"], true);
+    }
+
+    #[test]
+    fn matting_failure_audit_keeps_non_timeout_transport_classification() {
+        let error = AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+            "provider": "bgfilter",
+            "message": "请求 BgFilter 服务失败：dns error",
+            "timeout": false,
+            "transport": true,
+            "latencyMs": 67,
+        }));
+
+        let status_code = matting_failure_audit_status_code(&error);
+        let timeout = matting_failure_audit_timeout(&error);
+        let tracking = build_external_api_failure_tracking_draft(
+            &ExternalApiFailureDraft::new(
+                "bgfilter",
+                "https://bgfilter.example/remove-background",
+                "editor-screen-background-removal",
+                "bgfilter_segment",
+                error.message(),
+            )
+            .with_status_code(status_code)
+            .with_optional_status_class(Some(status_class(status_code)))
+            .with_timeout(timeout)
+            .with_latency_ms(matting_failure_audit_latency_ms(&error))
+            .with_retryable(is_retryable_external_api_failure(
+                status_code,
+                timeout,
+                false,
+            )),
+        );
+
+        assert_eq!(tracking.metadata["statusCode"], Value::Null);
+        assert_eq!(tracking.metadata["statusClass"], "transport");
+        assert_eq!(tracking.metadata["timeout"], false);
+        assert_eq!(tracking.metadata["retryable"], false);
+        assert_eq!(tracking.metadata["latencyMs"], 67);
+    }
+
+    #[test]
+    fn matting_failure_external_call_attempted_defaults_to_true() {
+        let attempted = AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+            "provider": "aliyun-matting",
+            "message": "真实上游失败",
+        }));
+        let skipped = AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_details(json!({
+            "provider": "aliyun-matting",
+            "message": "阿里云抠图客户端未配置或未启用。",
+            "externalCallAttempted": false,
+        }));
+
+        assert!(matting_failure_external_call_attempted(&attempted));
+        assert!(!matting_failure_external_call_attempted(&skipped));
+    }
 }
diff --git a/server-rs/crates/api-server/src/llm_model_routing.rs b/server-rs/crates/api-server/src/llm_model_routing.rs
index 4fd986fde..e3485fe09 100644
--- a/server-rs/crates/api-server/src/llm_model_routing.rs
+++ b/server-rs/crates/api-server/src/llm_model_routing.rs
@@ -1,3 +1,9 @@
 pub(crate) const RPG_STORY_LLM_MODEL: &str = "doubao-seed-character-251128";
 pub(crate) const CREATION_TEMPLATE_LLM_MODEL: &str = "deepseek-v3-2-251201";
 pub(crate) const PUZZLE_LEVEL_NAME_VISION_LLM_MODEL: &str = "gpt-4o-mini";
+// 抠图背景色决策的视觉模型（有源图）。gpt-5-mini 是推理模型，会先花若干 token 做推理，
+// 故决策请求的 max_tokens 需留足推理开销（见 editor_screen_background_decision）。
+pub(crate) const EDITOR_SCREEN_BACKGROUND_VISION_LLM_MODEL: &str = "gpt-5-mini";
+// 抠图背景色决策的文本模型（无源图）。独立于视觉档，便于两条路径分别调参；
+// 硬编码而非继承 Ark 默认文本模型（豆包，选色能力弱）。同为 gpt-5-mini 推理模型，同样留足推理预算。
+pub(crate) const EDITOR_SCREEN_BACKGROUND_TEXT_LLM_MODEL: &str = "gpt-5-mini";
diff --git a/server-rs/crates/api-server/src/main.rs b/server-rs/crates/api-server/src/main.rs
index 1921ab94c..0dce97af0 100644
--- a/server-rs/crates/api-server/src/main.rs
+++ b/server-rs/crates/api-server/src/main.rs
@@ -2,6 +2,7 @@
 
 mod admin;
 mod ai_generation_drafts;
+mod aliyun_matting;
 mod ai_tasks;
 mod api_response;
 mod app;
@@ -42,6 +43,7 @@ mod editor_generation_queue;
 mod editor_green_screen;
 mod editor_project;
 mod editor_screen_background_decision;
+mod editor_screen_background_filter;
 mod edutainment_baby_drawing;
 mod edutainment_baby_object;
 mod error_middleware;
diff --git a/server-rs/crates/api-server/src/state.rs b/server-rs/crates/api-server/src/state.rs
index 243133fe5..7d8bbe2cd 100644
--- a/server-rs/crates/api-server/src/state.rs
+++ b/server-rs/crates/api-server/src/state.rs
@@ -24,6 +24,7 @@ use platform_auth::{
     SmsAuthProviderKind, SmsProviderError, WechatProvider, sign_access_token, verify_access_token,
 };
 use platform_llm::{LlmClient, LlmConfig, LlmError, LlmProvider};
+use platform_matting::{MattingClient, MattingConfig};
 use platform_oss::{OssClient, OssConfig, OssError};
 use platform_wechat::{WechatClient, WechatConfig, pay::WechatPayClient};
 use serde_json::Value;
@@ -271,6 +272,7 @@ pub struct AppStateInner {
     editor_generation_pricing_store: EditorGenerationPricingStore,
     llm_client: Option<LlmClient>,
     creative_agent_gpt5_client: Option<LlmClient>,
+    matting_client: Option<MattingClient>,
     creative_agent_executor: Arc<MockLangChainRustAgentExecutor>,
     // Phase 1 任务 E 的 creative session facade 暂存在 api-server。
     // creative_agent_* 表由任务 D 收口后，这里只保留读写 facade。
@@ -414,6 +416,7 @@ impl AppState {
         .map_err(|error| AppStateInitError::DependencyUnavailable(error.to_string()))?;
         let llm_client = build_llm_client(&config)?;
         let creative_agent_gpt5_client = build_creative_agent_gpt5_client(&config)?;
+        let matting_client = build_matting_client(&config)?;
         let http_request_permit_pools = HttpRequestPermitPools::from_config(&config);
         let (profile_recharge_order_updates, _) = broadcast::channel(128);
 
@@ -453,6 +456,7 @@ impl AppState {
             editor_generation_pricing_store,
             llm_client,
             creative_agent_gpt5_client,
+            matting_client,
             creative_agent_executor: Arc::new(MockLangChainRustAgentExecutor),
             creative_agent_sessions: Arc::new(Mutex::new(HashMap::new())),
             profile_recharge_order_updates,
@@ -1065,6 +1069,10 @@ impl AppState {
         self.creative_agent_gpt5_client.as_ref()
     }
 
+    pub fn matting_client(&self) -> Option<&MattingClient> {
+        self.matting_client.as_ref()
+    }
+
     pub fn creative_agent_executor(&self) -> Arc<MockLangChainRustAgentExecutor> {
         self.creative_agent_executor.clone()
     }
@@ -1660,6 +1668,38 @@ fn build_oss_client(config: &AppConfig) -> Result<Option<OssClient>, AppStateIni
     Ok(Some(OssClient::new(oss_config)))
 }
 
+fn build_matting_client(config: &AppConfig) -> Result<Option<MattingClient>, AppStateInitError> {
+    if !config.aliyun_matting_enabled {
+        return Ok(None);
+    }
+    let (Some(access_key_id), Some(access_key_secret)) = (
+        config
+            .aliyun_matting_access_key_id
+            .as_deref()
+            .map(str::trim)
+            .filter(|value| !value.is_empty()),
+        config
+            .aliyun_matting_access_key_secret
+            .as_deref()
+            .map(str::trim)
+            .filter(|value| !value.is_empty()),
+    ) else {
+        warn!("阿里云抠图 AccessKey 未配置，跳过抠图客户端初始化");
+        return Ok(None);
+    };
+
+    let matting_config = MattingConfig::with_timeout(
+        config.aliyun_matting_endpoint.clone(),
+        access_key_id.to_string(),
+        access_key_secret.to_string(),
+        config.aliyun_matting_request_timeout_ms,
+    )
+    .map_err(|error| AppStateInitError::DependencyUnavailable(error.to_string()))?;
+    MattingClient::new(matting_config)
+        .map(Some)
+        .map_err(|error| AppStateInitError::DependencyUnavailable(error.to_string()))
+}
+
 fn build_wechat_client(config: &AppConfig) -> WechatClient {
     WechatClient::new(WechatConfig {
         app_id: config.wechat_mini_program_app_id.clone(),
diff --git a/server-rs/crates/platform-matting/Cargo.toml b/server-rs/crates/platform-matting/Cargo.toml
new file mode 100644
index 000000000..87a387af0
--- /dev/null
+++ b/server-rs/crates/platform-matting/Cargo.toml
@@ -0,0 +1,26 @@
+[package]
+name = "platform-matting"
+edition.workspace = true
+version.workspace = true
+license.workspace = true
+
+[dependencies]
+base64 = { workspace = true }
+hmac = { workspace = true }
+hex = { workspace = true }
+httpdate = { workspace = true }
+image = { workspace = true, features = ["png", "jpeg", "webp"] }
+sha1 = { workspace = true }
+reqwest = { workspace = true, features = ["json", "rustls-tls"] }
+serde = { workspace = true }
+serde_json = { workspace = true }
+serde_urlencoded = { workspace = true }
+sha2 = { workspace = true }
+time = { workspace = true, features = ["std"] }
+tracing = { workspace = true }
+uuid = { workspace = true, features = ["v4"] }
+
+[dev-dependencies]
+dotenvy = { workspace = true }
+platform-oss = { workspace = true }
+tokio = { workspace = true, features = ["macros", "rt-multi-thread"] }
diff --git a/server-rs/crates/platform-matting/examples/segment_smoke.rs b/server-rs/crates/platform-matting/examples/segment_smoke.rs
new file mode 100644
index 000000000..c778b5f02
--- /dev/null
+++ b/server-rs/crates/platform-matting/examples/segment_smoke.rs
@@ -0,0 +1,159 @@
+//! 通用抠图冒烟验证：本地图片 → OSS → SegmentCommonImage → 下载结果。
+//!
+//! 运行（在 server-rs 目录下）：
+//! cargo run -p platform-matting --example segment_smoke -- "C:\path\to\input.png"
+//!
+//! 依赖仓库根目录 .env.local（OSS bucket/endpoint）与 .env.secrets.local（AK/SK）。
+
+use std::path::{Path, PathBuf};
+
+use platform_matting::{
+    DEFAULT_IMAGESEG_ENDPOINT, MattingClient, MattingConfig, SegmentCommonImageRequest,
+    SegmentReturnForm,
+};
+
+fn load_env_files() {
+    // example 的工作目录通常是 server-rs，.env 都在仓库根目录。
+    for candidate in [
+        ".env",
+        ".env.local",
+        ".env.secrets.local",
+        "../.env",
+        "../.env.local",
+        "../.env.secrets.local",
+    ] {
+        if Path::new(candidate).exists() {
+            let _ = dotenvy::from_path_override(candidate);
+        }
+    }
+}
+
+#[tokio::main]
+async fn main() {
+    load_env_files();
+
+    let input_path = std::env::args().nth(1).unwrap_or_else(|| {
+        eprintln!("用法：cargo run -p platform-matting --example segment_smoke -- <图片路径>");
+        std::process::exit(1);
+    });
+    let input_bytes = std::fs::read(&input_path)
+        .unwrap_or_else(|error| panic!("读取测试图片失败（{input_path}）：{error}"));
+    println!("[1/5] 已读取测试图片：{input_path}（{} 字节）", input_bytes.len());
+
+    // SegmentCommonImage 要求分辨率低于 2000x2000，超限先等比缩小。
+    const MAX_EDGE: u32 = 1999;
+    let decoded = image::load_from_memory(&input_bytes).expect("测试图片应可解码");
+    let input_bytes = if decoded.width() > MAX_EDGE || decoded.height() > MAX_EDGE {
+        let resized = decoded.resize(
+            MAX_EDGE,
+            MAX_EDGE,
+            image::imageops::FilterType::CatmullRom,
+        );
+        let mut buffer = std::io::Cursor::new(Vec::new());
+        resized
+            .write_to(&mut buffer, image::ImageFormat::Png)
+            .expect("缩放后的图片应可编码为 PNG");
+        println!(
+            "      分辨率 {}x{} 超限，已缩放到 {}x{}",
+            decoded.width(),
+            decoded.height(),
+            resized.width(),
+            resized.height()
+        );
+        buffer.into_inner()
+    } else {
+        input_bytes
+    };
+
+    let http_client = reqwest::Client::new();
+
+    // --- 调用通用抠图 ---
+    // key 优先级：VIAPI 专用 → 官方 SDK 标准命名（#IMAGE_CALL）→ 短信 key 兜底。
+    let (matting_key_id, matting_key_secret) = [
+        ("ALIYUN_IMAGESEG_ACCESS_KEY_ID", "ALIYUN_IMAGESEG_ACCESS_KEY_SECRET"),
+        ("ALIBABA_CLOUD_ACCESS_KEY_ID", "ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
+        ("ALIYUN_SMS_ACCESS_KEY_ID", "ALIYUN_SMS_ACCESS_KEY_SECRET"),
+    ]
+    .iter()
+    .find_map(|(id_name, secret_name)| {
+        let id = std::env::var(id_name).ok()?;
+        let secret = std::env::var(secret_name).ok()?;
+        if id.trim().is_empty() || secret.trim().is_empty() {
+            return None;
+        }
+        println!("      使用 {id_name} 调用抠图服务");
+        Some((id, secret))
+    })
+    .expect("未找到可用的抠图 AccessKey 环境变量");
+    let matting_config = MattingConfig::new(
+        std::env::var("ALIYUN_IMAGESEG_ENDPOINT")
+            .unwrap_or_else(|_| DEFAULT_IMAGESEG_ENDPOINT.to_string()),
+        matting_key_id,
+        matting_key_secret,
+    )
+    .expect("抠图配置应有效");
+    let matting_client = MattingClient::new(matting_config).expect("抠图客户端应可构建");
+
+    // 本地 OSS 在北京地域，抠图服务要求上海地域，走 VIAPI 官方临时桶上传。
+    let temp_url = matting_client
+        .upload_temp_image(input_bytes, "segment-input.png", "image/png")
+        .await
+        .expect("上传 VIAPI 临时桶应成功");
+    println!("[2/5] 已上传 VIAPI 临时桶");
+    println!("[3/5] 输入图 URL host：{}", host_of(&temp_url));
+
+    let result = matting_client
+        .segment_common_image(SegmentCommonImageRequest {
+            image_url: temp_url,
+            return_form: Some(SegmentReturnForm::Crop),
+        })
+        .await;
+    let result = match result {
+        Ok(result) => result,
+        Err(error) => {
+            eprintln!("[4/5] 通用抠图调用失败：{error}");
+            std::process::exit(1);
+        }
+    };
+    println!(
+        "[4/5] 通用抠图成功，RequestId={}",
+        result.request_id.as_deref().unwrap_or("unknown")
+    );
+
+    // --- 下载结果 ---
+    let output_bytes = http_client
+        .get(&result.image_url)
+        .send()
+        .await
+        .expect("下载抠图结果应成功")
+        .error_for_status()
+        .expect("抠图结果 URL 应返回 200")
+        .bytes()
+        .await
+        .expect("读取抠图结果字节应成功");
+
+    let output_path = build_output_path(&input_path);
+    std::fs::write(&output_path, &output_bytes).expect("写出抠图结果应成功");
+    println!(
+        "[5/5] 抠图结果已保存：{}（{} 字节）",
+        output_path.display(),
+        output_bytes.len()
+    );
+}
+
+fn build_output_path(input_path: &str) -> PathBuf {
+    let input = Path::new(input_path);
+    let stem = input
+        .file_stem()
+        .and_then(|value| value.to_str())
+        .unwrap_or("segment-output");
+    input.with_file_name(format!("{stem}-matting.png"))
+}
+
+fn host_of(url: &str) -> String {
+    url.split("//")
+        .nth(1)
+        .and_then(|rest| rest.split('/').next())
+        .unwrap_or("unknown")
+        .to_string()
+}
diff --git a/server-rs/crates/platform-matting/src/lib.rs b/server-rs/crates/platform-matting/src/lib.rs
new file mode 100644
index 000000000..0df252889
--- /dev/null
+++ b/server-rs/crates/platform-matting/src/lib.rs
@@ -0,0 +1,1204 @@
+//! 阿里云 VIAPI 通用抠图（SegmentCommonImage）客户端。
+//!
+//! 官方没有 Rust SDK，这里按 ACS3-HMAC-SHA256 签名协议手搓 HTTP 调用，
+//! 签名实现与 platform-auth 的阿里云短信调用保持一致。
+//! 文档：https://help.aliyun.com/zh/viapi/use-cases/general-image-segmentation
+
+use std::collections::BTreeMap;
+
+use hmac::{Hmac, Mac};
+use reqwest::{Client, StatusCode};
+use sha2::{Digest, Sha256};
+use time::OffsetDateTime;
+use tracing::{info, warn};
+
+type HmacSha256 = Hmac<Sha256>;
+
+pub const DEFAULT_IMAGESEG_ENDPOINT: &str = "imageseg.cn-shanghai.aliyuncs.com";
+const IMAGESEG_API_VERSION: &str = "2019-12-30";
+const SEGMENT_COMMON_IMAGE_ACTION: &str = "SegmentCommonImage";
+
+// VIAPI 官方临时上传通道：抠图输入统一先传官方临时桶（1 天自动过期，无需清理；
+// 全用户共享 QPS）。抠图服务只认上海地域 OSS URL，而我们没有上海地域自有 OSS。
+// 文档：https://help.aliyun.com/document_detail/155645.html
+const VIAPI_UTILS_ENDPOINT: &str = "viapiutils.cn-shanghai.aliyuncs.com";
+const VIAPI_UTILS_VERSION: &str = "2020-04-01";
+const GET_OSS_STS_TOKEN_ACTION: &str = "GetOssStsToken";
+const VIAPI_TEMP_BUCKET: &str = "viapi-customer-temp";
+const VIAPI_TEMP_OSS_HOST: &str = "viapi-customer-temp.oss-cn-shanghai.aliyuncs.com";
+
+pub const DEFAULT_MATTING_REQUEST_TIMEOUT_MS: u64 = 30_000;
+
+/// SegmentCommonImage 要求每条边小于 2000。
+const MAX_INPUT_EDGE: u32 = 1_999;
+
+/// SegmentCommonImage 要求输入体积不超过 3 MB。
+const MAX_INPUT_BYTES: usize = 3 * 1024 * 1024;
+
+/// SegmentCommonImage 要求每条边大于 32 像素。
+const MIN_INPUT_EDGE: u32 = 32;
+
+/// 抠图结果下载的最大字节数。上游是阿里云返回的原尺寸 RGBA PNG，正常远小于此值；
+/// 设上限是为了防止异常 / 恶意上游用超大响应撑爆 API 进程内存（逐帧动画可并发多次调用）。
+/// 与 api-server BgFilter 降级路径的 `EDITOR_BACKGROUND_REMOVAL_MAX_RESPONSE_BYTES` 对齐。
+const MAX_RESULT_RESPONSE_BYTES: usize = 32 * 1024 * 1024;
+
+/// 图片解码的最大边长像素（源图与抠图结果共用）。防止解码阶段按声明的巨幅尺寸分配
+/// 像素缓冲。与 api-server BgFilter 路径的 `EDITOR_BACKGROUND_REMOVAL_MAX_IMAGE_DIMENSION` 对齐。
+const MAX_DECODE_IMAGE_DIMENSION: u32 = 8192;
+
+#[derive(Clone, Debug)]
+pub struct MattingConfig {
+    pub endpoint: String,
+    pub access_key_id: String,
+    pub access_key_secret: String,
+    pub request_timeout_ms: u64,
+}
+
+impl MattingConfig {
+    pub fn new(
+        endpoint: String,
+        access_key_id: String,
+        access_key_secret: String,
+    ) -> Result<Self, MattingError> {
+        Self::with_timeout(
+            endpoint,
+            access_key_id,
+            access_key_secret,
+            DEFAULT_MATTING_REQUEST_TIMEOUT_MS,
+        )
+    }
+
+    pub fn with_timeout(
+        endpoint: String,
+        access_key_id: String,
+        access_key_secret: String,
+        request_timeout_ms: u64,
+    ) -> Result<Self, MattingError> {
+        let endpoint = endpoint
+            .trim()
+            .trim_start_matches("https://")
+            .trim_start_matches("http://")
+            .trim_matches('/')
+            .to_string();
+        if endpoint.is_empty() {
+            return Err(MattingError::InvalidConfig(
+                "抠图服务 endpoint 不能为空".to_string(),
+            ));
+        }
+        let access_key_id = access_key_id.trim().to_string();
+        let access_key_secret = access_key_secret.trim().to_string();
+        if access_key_id.is_empty() || access_key_secret.is_empty() {
+            return Err(MattingError::InvalidConfig(
+                "抠图服务 AccessKeyId/AccessKeySecret 不能为空".to_string(),
+            ));
+        }
+        Ok(Self {
+            endpoint,
+            access_key_id,
+            access_key_secret,
+            request_timeout_ms: request_timeout_ms.max(1),
+        })
+    }
+}
+
+/// SegmentCommonImage 的 ReturnForm 取值。
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum SegmentReturnForm {
+    /// 透明背景 PNG（默认，抠像主用途）。
+    Crop,
+    /// 黑白 mask 图。
+    Mask,
+    /// 白底图。
+    WhiteBackground,
+}
+
+impl SegmentReturnForm {
+    fn as_str(&self) -> &'static str {
+        match self {
+            Self::Crop => "crop",
+            Self::Mask => "mask",
+            Self::WhiteBackground => "whiteBK",
+        }
+    }
+}
+
+#[derive(Clone, Debug)]
+pub struct SegmentCommonImageRequest {
+    /// 待抠图图片的公网可访问 URL（推荐上海地域 OSS 签名 URL）。
+    pub image_url: String,
+    /// None 表示不传 ReturnForm，使用服务端默认行为。
+    pub return_form: Option<SegmentReturnForm>,
+}
+
+#[derive(Clone, Debug)]
+pub struct SegmentCommonImageResult {
+    /// 抠图结果图片 URL（阿里云临时地址，30 分钟内有效，需及时转存）。
+    pub image_url: String,
+    pub request_id: Option<String>,
+}
+
+#[derive(Debug)]
+pub enum MattingError {
+    InvalidConfig(String),
+    InvalidRequest(String),
+    Sign(String),
+    Upstream(UpstreamFailure),
+}
+
+/// 结构化的上游调用失败分类。协议层归属（是否传输层故障、是否超时、上游 HTTP 状态）由
+/// platform-matting 在错误发生处直接捕获，调用方（api-server BFF）不再从中文 message 反推。
+#[derive(Debug)]
+pub struct UpstreamFailure {
+    message: String,
+    /// 传输层超时（reqwest `is_timeout`）。
+    timeout: bool,
+    /// 传输层故障：请求已发出但未拿到有效 HTTP 响应（连接失败、读体中断、超时）。
+    transport: bool,
+    /// 上游返回的 HTTP 状态码；`None` 表示没拿到状态（传输层故障或响应体不可用）。
+    upstream_status: Option<u16>,
+}
+
+impl MattingError {
+    pub fn message(&self) -> &str {
+        match self {
+            Self::InvalidConfig(message)
+            | Self::InvalidRequest(message)
+            | Self::Sign(message) => message,
+            Self::Upstream(failure) => &failure.message,
+        }
+    }
+
+    /// 是否真正向阿里云发起过外部调用。`InvalidConfig` / `InvalidRequest` / `Sign` 都是发请求前的
+    /// 本地预检失败，未触达上游。
+    pub fn external_call_attempted(&self) -> bool {
+        matches!(self, Self::Upstream(_))
+    }
+
+    /// 上游调用是否为传输层超时。
+    pub fn is_timeout(&self) -> bool {
+        matches!(self, Self::Upstream(failure) if failure.timeout)
+    }
+
+    /// 上游调用是否为传输层故障（未拿到有效 HTTP 响应）。
+    pub fn is_transport(&self) -> bool {
+        matches!(self, Self::Upstream(failure) if failure.transport)
+    }
+
+    /// 上游返回的 HTTP 状态码（若有）。
+    pub fn upstream_status(&self) -> Option<u16> {
+        match self {
+            Self::Upstream(failure) => failure.upstream_status,
+            _ => None,
+        }
+    }
+
+    /// 传输层故障构造器：请求已发出但没拿到有效 HTTP 响应（连接、读体、超时）。
+    pub fn upstream_transport_error(message: String, timeout: bool) -> Self {
+        Self::Upstream(UpstreamFailure {
+            message,
+            timeout,
+            transport: true,
+            upstream_status: None,
+        })
+    }
+
+    /// 上游返回了 HTTP 响应但状态非成功。
+    pub fn upstream_http_error(message: String, status: u16) -> Self {
+        Self::Upstream(UpstreamFailure {
+            message,
+            timeout: false,
+            transport: false,
+            upstream_status: Some(status),
+        })
+    }
+
+    /// 已拿到 HTTP 响应，但响应体 / 结果不可用（JSON 非法、缺字段、结果图不可解码 / 尺寸不符、
+    /// 结果编码失败等）。不是传输层故障，也不归因某个错误状态码。
+    pub fn upstream_response_error(message: String, upstream_status: Option<u16>) -> Self {
+        Self::Upstream(UpstreamFailure {
+            message,
+            timeout: false,
+            transport: false,
+            upstream_status,
+        })
+    }
+}
+
+impl std::fmt::Display for MattingError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(self.message())
+    }
+}
+
+impl std::error::Error for MattingError {}
+
+#[derive(Clone)]
+pub struct MattingClient {
+    config: MattingConfig,
+    client: Client,
+}
+
+impl std::fmt::Debug for MattingClient {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("MattingClient")
+            .field("endpoint", &self.config.endpoint)
+            .finish_non_exhaustive()
+    }
+}
+
+impl MattingClient {
+    pub fn new(config: MattingConfig) -> Result<Self, MattingError> {
+        let client = Client::builder()
+            .timeout(std::time::Duration::from_millis(config.request_timeout_ms))
+            .build()
+            .map_err(|error| {
+                MattingError::InvalidConfig(format!("构建 reqwest client 失败：{error}"))
+            })?;
+        Ok(Self { config, client })
+    }
+
+    pub async fn segment_common_image(
+        &self,
+        request: SegmentCommonImageRequest,
+    ) -> Result<SegmentCommonImageResult, MattingError> {
+        let image_url = request.image_url.trim().to_string();
+        if image_url.is_empty() {
+            return Err(MattingError::InvalidRequest(
+                "imageUrl 不能为空".to_string(),
+            ));
+        }
+
+        let mut form = BTreeMap::new();
+        form.insert("Action".to_string(), SEGMENT_COMMON_IMAGE_ACTION.to_string());
+        form.insert("Format".to_string(), "json".to_string());
+        form.insert("Version".to_string(), IMAGESEG_API_VERSION.to_string());
+        form.insert("ImageURL".to_string(), image_url);
+        if let Some(return_form) = request.return_form {
+            form.insert("ReturnForm".to_string(), return_form.as_str().to_string());
+        }
+
+        let payload = build_aliyun_form_body(&form);
+        let headers = self.build_signature_headers(SEGMENT_COMMON_IMAGE_ACTION, &payload)?;
+
+        info!(
+            provider = "aliyun-imageseg",
+            endpoint = self.config.endpoint.as_str(),
+            action = SEGMENT_COMMON_IMAGE_ACTION,
+            return_form = request
+                .return_form
+                .map_or("default", |return_form| return_form.as_str()),
+            "准备调用阿里云通用抠图接口"
+        );
+
+        let response = self
+            .client
+            .post(format!("https://{}/", self.config.endpoint))
+            .headers(headers)
+            .header(
+                reqwest::header::CONTENT_TYPE,
+                "application/x-www-form-urlencoded",
+            )
+            .body(payload)
+            .send()
+            .await
+            .map_err(|error| {
+                MattingError::upstream_transport_error(
+                    format!("通用抠图请求失败：{error}"),
+                    error.is_timeout(),
+                )
+            })?;
+
+        let http_status = response.status();
+        let body_text = response.text().await.map_err(|error| {
+            MattingError::upstream_transport_error(
+                format!("通用抠图响应读取失败：{error}"),
+                error.is_timeout(),
+            )
+        })?;
+        let body: serde_json::Value = serde_json::from_str(&body_text).map_err(|error| {
+            MattingError::upstream_response_error(
+                format!(
+                    "通用抠图响应不是合法 JSON：{error}；原始响应：{}",
+                    truncate_for_log(&body_text)
+                ),
+                Some(http_status.as_u16()),
+            )
+        })?;
+
+        let request_id = body
+            .get("RequestId")
+            .and_then(|value| value.as_str())
+            .map(|value| value.to_string());
+
+        if http_status != StatusCode::OK {
+            let code = body.get("Code").and_then(|value| value.as_str());
+            let message = body.get("Message").and_then(|value| value.as_str());
+            warn!(
+                provider = "aliyun-imageseg",
+                http_status = http_status.as_u16(),
+                provider_code = code.unwrap_or("unknown"),
+                provider_message = message.unwrap_or("unknown"),
+                provider_request_id = request_id.as_deref().unwrap_or("unknown"),
+                "阿里云通用抠图接口返回失败"
+            );
+            return Err(MattingError::upstream_http_error(
+                format!(
+                    "通用抠图接口返回失败（HTTP {}，Code={}）：{}",
+                    http_status.as_u16(),
+                    code.unwrap_or("unknown"),
+                    message.unwrap_or("unknown")
+                ),
+                http_status.as_u16(),
+            ));
+        }
+
+        let result_image_url = body
+            .get("Data")
+            .and_then(|data| data.get("ImageURL"))
+            .and_then(|value| value.as_str())
+            .map(|value| value.to_string())
+            .ok_or_else(|| {
+                MattingError::upstream_response_error(
+                    format!(
+                        "通用抠图响应缺少 Data.ImageURL；原始响应：{}",
+                        truncate_for_log(&body_text)
+                    ),
+                    Some(http_status.as_u16()),
+                )
+            })?;
+
+        info!(
+            provider = "aliyun-imageseg",
+            provider_request_id = request_id.as_deref().unwrap_or("unknown"),
+            "阿里云通用抠图接口调用成功"
+        );
+
+        Ok(SegmentCommonImageResult {
+            image_url: result_image_url,
+            request_id,
+        })
+    }
+
+    /// 图片字节 → 通用抠图 → 原尺寸透明 PNG 字节。
+    ///
+    /// - 输入统一上传 VIAPI 官方临时桶（1 天自动过期，无需清理）后作为 ImageURL 送抠。
+    /// - 分辨率守卫：任一边 >= 2000 时先等比缩小送抠，抠完只取结果 alpha 上采样回贴
+    ///   原图 RGB，保证输出与输入同尺寸、画质无损。
+    pub async fn segment_image_to_transparent_png(
+        &self,
+        bytes: &[u8],
+        file_name: &str,
+    ) -> Result<Vec<u8>, MattingError> {
+        let source = decode_source_image(bytes)?;
+        let source_rgba = source.to_rgba8();
+        let (source_width, source_height) = source_rgba.dimensions();
+
+        // 阿里云要求每条边 > 32px；过小的图直接拒绝，让调用方走本地兜底，省一次注定 4xx 的往返。
+        if source_width <= MIN_INPUT_EDGE || source_height <= MIN_INPUT_EDGE {
+            return Err(MattingError::InvalidRequest(format!(
+                "待抠图图片尺寸 {source_width}x{source_height} 过小，阿里云通用抠图要求每条边大于 {MIN_INPUT_EDGE} 像素"
+            )));
+        }
+
+        // 归一化成阿里云 SegmentCommonImage 接受的输入：统一 8 位 RGBA PNG（消除 MIME 名不副实
+        // 与不支持位深/格式的问题）、最长边 ≤1999、体积 ≤3MB。返回实际上传尺寸，用于判断结果
+        // 是否需要 alpha 上采样回原尺寸。
+        let (upload_bytes, upload_dims) = normalize_matting_input_png(&source)?;
+        let downscaled = upload_dims != (source_width, source_height);
+        let image_url = self
+            .upload_temp_image(upload_bytes, file_name, "image/png")
+            .await?;
+
+        let result = self
+            .segment_common_image(SegmentCommonImageRequest {
+                image_url,
+                // 默认 ReturnForm：原尺寸 + 透明背景，无需本地合成。
+                return_form: None,
+            })
+            .await?;
+        let result_bytes = self.download_result_image(&result.image_url).await?;
+        let result_image = decode_result_image(&result_bytes)?.to_rgba8();
+
+        if !downscaled {
+            if result_image.dimensions() != (source_width, source_height) {
+                return Err(MattingError::upstream_response_error(
+                    format!(
+                        "抠图结果尺寸 {}x{} 与输入 {}x{} 不一致",
+                        result_image.width(),
+                        result_image.height(),
+                        source_width,
+                        source_height
+                    ),
+                    None,
+                ));
+            }
+            return encode_rgba_png(&result_image);
+        }
+
+        // 缩图送抠的场景：只取结果 alpha，上采样回原尺寸后贴回原图 RGB。
+        let alpha_mask = image::DynamicImage::ImageRgba8(result_image).resize_exact(
+            source_width,
+            source_height,
+            image::imageops::FilterType::Triangle,
+        );
+        let alpha_mask = alpha_mask.to_rgba8();
+        let mut output = source_rgba;
+        for (target, mask) in output.pixels_mut().zip(alpha_mask.pixels()) {
+            target.0[3] = target.0[3].min(mask.0[3]);
+        }
+        encode_rgba_png(&output)
+    }
+
+    async fn download_result_image(&self, url: &str) -> Result<Vec<u8>, MattingError> {
+        let mut response = self
+            .client
+            .get(url)
+            .send()
+            .await
+            .map_err(|error| {
+                MattingError::upstream_transport_error(
+                    describe_result_download_transport_error(&error),
+                    error.is_timeout(),
+                )
+            })?;
+        let status = response.status();
+        if !status.is_success() {
+            return Err(MattingError::upstream_http_error(
+                format!("下载抠图结果失败（HTTP {}）", status.as_u16()),
+                status.as_u16(),
+            ));
+        }
+        // 先按 Content-Length 快速拒绝，再流式累加做兜底：不信任上游声明的长度，
+        // 逐块累计超阈值立即中断，避免 response.bytes() 一次性分配任意大小响应撑爆内存。
+        if response
+            .content_length()
+            .is_some_and(|length| length > MAX_RESULT_RESPONSE_BYTES as u64)
+        {
+            return Err(result_response_too_large_error());
+        }
+        let mut bytes = Vec::new();
+        while let Some(chunk) = response.chunk().await.map_err(|error| {
+            MattingError::upstream_transport_error(
+                describe_result_download_body_error(&error),
+                error.is_timeout(),
+            )
+        })? {
+            if bytes.len().saturating_add(chunk.len()) > MAX_RESULT_RESPONSE_BYTES {
+                return Err(result_response_too_large_error());
+            }
+            bytes.extend_from_slice(chunk.as_ref());
+        }
+        Ok(bytes)
+    }
+
+    /// 把本地图片字节上传到 VIAPI 官方临时桶，返回可直接作为 ImageURL 的公网地址。
+    /// 抠图输入的统一上传通道（我们没有上海地域自有 OSS，临时桶 1 天自动过期无需清理）。
+    pub async fn upload_temp_image(
+        &self,
+        bytes: Vec<u8>,
+        file_name: &str,
+        content_type: &str,
+    ) -> Result<String, MattingError> {
+        if bytes.is_empty() {
+            return Err(MattingError::InvalidRequest(
+                "上传内容不能为空".to_string(),
+            ));
+        }
+        let sts = self.get_oss_sts_token().await?;
+        let file_name = file_name.trim().trim_matches('/');
+        if file_name.is_empty() {
+            return Err(MattingError::InvalidRequest(
+                "file_name 不能为空".to_string(),
+            ));
+        }
+        // 阿里云要求 ImageURL 不含中文/非 ASCII 字符；object 叶子名只保留 URL 安全的 ASCII 字符，
+        // 唯一性由前缀 uuid 保证。
+        let safe_file_name: String = file_name
+            .chars()
+            .map(|c| {
+                if c.is_ascii_alphanumeric() || matches!(c, '.' | '_' | '-') {
+                    c
+                } else {
+                    '_'
+                }
+            })
+            .collect();
+        let object_key = format!(
+            "{}/{}/{}",
+            self.config.access_key_id,
+            uuid::Uuid::new_v4().simple(),
+            safe_file_name
+        );
+        let date = httpdate::fmt_http_date(std::time::SystemTime::now());
+        // OSS V1 头签名（带 STS security token）。
+        let string_to_sign = format!(
+            "PUT\n\n{content_type}\n{date}\nx-oss-security-token:{}\n/{VIAPI_TEMP_BUCKET}/{object_key}",
+            sts.security_token
+        );
+        let signature = hmac_sha1_base64(sts.access_key_secret.as_bytes(), string_to_sign.as_bytes())?;
+        let authorization = format!("OSS {}:{}", sts.access_key_id, signature);
+
+        let target_url = format!("https://{VIAPI_TEMP_OSS_HOST}/{object_key}");
+        let response = self
+            .client
+            .put(&target_url)
+            .header(reqwest::header::CONTENT_TYPE, content_type)
+            .header(reqwest::header::DATE, &date)
+            .header("x-oss-security-token", &sts.security_token)
+            .header(reqwest::header::AUTHORIZATION, &authorization)
+            .body(bytes)
+            .send()
+            .await
+            .map_err(|error| {
+                MattingError::upstream_transport_error(
+                    format!("上传 VIAPI 临时桶请求失败：{error}"),
+                    error.is_timeout(),
+                )
+            })?;
+        let status = response.status();
+        if !status.is_success() {
+            let body = response.text().await.unwrap_or_default();
+            // OSS 签名类错误体会回显 StringToSign（含 x-oss-security-token 明文）、StringToSignBytes
+            // 和 SignatureProvided；脱敏后再记录，避免 STS 临时凭证进审计元数据与日志。
+            return Err(MattingError::upstream_http_error(
+                format!(
+                    "上传 VIAPI 临时桶失败（HTTP {}）：{}",
+                    status.as_u16(),
+                    sanitize_oss_upload_error_body(&body, &sts.security_token)
+                ),
+                status.as_u16(),
+            ));
+        }
+
+        Ok(target_url)
+    }
+
+    async fn get_oss_sts_token(&self) -> Result<ViapiStsToken, MattingError> {
+        let mut form = BTreeMap::new();
+        form.insert("Action".to_string(), GET_OSS_STS_TOKEN_ACTION.to_string());
+        form.insert("Format".to_string(), "json".to_string());
+        form.insert("Version".to_string(), VIAPI_UTILS_VERSION.to_string());
+        let payload = build_aliyun_form_body(&form);
+        let headers = self.build_acs3_headers(
+            VIAPI_UTILS_ENDPOINT,
+            GET_OSS_STS_TOKEN_ACTION,
+            VIAPI_UTILS_VERSION,
+            &payload,
+        )?;
+
+        let response = self
+            .client
+            .post(format!("https://{VIAPI_UTILS_ENDPOINT}/"))
+            .headers(headers)
+            .header(
+                reqwest::header::CONTENT_TYPE,
+                "application/x-www-form-urlencoded",
+            )
+            .body(payload)
+            .send()
+            .await
+            .map_err(|error| {
+                MattingError::upstream_transport_error(
+                    format!("GetOssStsToken 请求失败：{error}"),
+                    error.is_timeout(),
+                )
+            })?;
+        let http_status = response.status();
+        let body_text = response.text().await.map_err(|error| {
+            MattingError::upstream_transport_error(
+                format!("GetOssStsToken 响应读取失败：{error}"),
+                error.is_timeout(),
+            )
+        })?;
+        let body: serde_json::Value = serde_json::from_str(&body_text).map_err(|error| {
+            MattingError::upstream_response_error(
+                format!(
+                    "GetOssStsToken 响应不是合法 JSON：{error}；原始响应：{}",
+                    truncate_for_log(&body_text)
+                ),
+                Some(http_status.as_u16()),
+            )
+        })?;
+        if http_status != StatusCode::OK {
+            return Err(MattingError::upstream_http_error(
+                format!(
+                    "GetOssStsToken 返回失败（HTTP {}，Code={}）：{}",
+                    http_status.as_u16(),
+                    body.get("Code").and_then(|value| value.as_str()).unwrap_or("unknown"),
+                    body.get("Message")
+                        .and_then(|value| value.as_str())
+                        .unwrap_or("unknown")
+                ),
+                http_status.as_u16(),
+            ));
+        }
+        let data = body.get("Data").ok_or_else(|| {
+            MattingError::upstream_response_error(
+                format!(
+                    "GetOssStsToken 响应缺少 Data；原始响应：{}",
+                    truncate_for_log(&body_text)
+                ),
+                Some(http_status.as_u16()),
+            )
+        })?;
+        let read_field = |name: &str| -> Result<String, MattingError> {
+            data.get(name)
+                .and_then(|value| value.as_str())
+                .map(|value| value.to_string())
+                .ok_or_else(|| {
+                    MattingError::upstream_response_error(
+                        format!("GetOssStsToken 响应缺少 Data.{name}"),
+                        Some(http_status.as_u16()),
+                    )
+                })
+        };
+        Ok(ViapiStsToken {
+            access_key_id: read_field("AccessKeyId")?,
+            access_key_secret: read_field("AccessKeySecret")?,
+            security_token: read_field("SecurityToken")?,
+        })
+    }
+
+    fn build_signature_headers(
+        &self,
+        action: &str,
+        payload: &str,
+    ) -> Result<reqwest::header::HeaderMap, MattingError> {
+        self.build_acs3_headers(&self.config.endpoint, action, IMAGESEG_API_VERSION, payload)
+    }
+
+    fn build_acs3_headers(
+        &self,
+        endpoint: &str,
+        action: &str,
+        version: &str,
+        payload: &str,
+    ) -> Result<reqwest::header::HeaderMap, MattingError> {
+        let date = current_aliyun_timestamp();
+        let nonce = uuid::Uuid::new_v4().simple().to_string();
+        let payload_hash = sha256_hex(payload.as_bytes());
+        let canonical_headers = format!(
+            "host:{}\nx-acs-action:{}\nx-acs-content-sha256:{}\nx-acs-date:{}\nx-acs-signature-nonce:{}\nx-acs-version:{}\n",
+            endpoint, action, payload_hash, date, nonce, version
+        );
+        let signed_headers =
+            "host;x-acs-action;x-acs-content-sha256;x-acs-date;x-acs-signature-nonce;x-acs-version";
+        let canonical_request = format!(
+            "POST\n/\n\n{}\n{}\n{}",
+            canonical_headers, signed_headers, payload_hash
+        );
+        let string_to_sign = format!(
+            "ACS3-HMAC-SHA256\n{}",
+            sha256_hex(canonical_request.as_bytes())
+        );
+        let signature = hmac_sha256_hex(
+            self.config.access_key_secret.as_bytes(),
+            string_to_sign.as_bytes(),
+        )?;
+        let authorization = format!(
+            "ACS3-HMAC-SHA256 Credential={},SignedHeaders={signed_headers},Signature={signature}",
+            self.config.access_key_id
+        );
+        let mut headers = reqwest::header::HeaderMap::new();
+        insert_header(&mut headers, "x-acs-action", action)?;
+        insert_header(&mut headers, "x-acs-version", version)?;
+        insert_header(&mut headers, "x-acs-date", &date)?;
+        insert_header(&mut headers, "x-acs-signature-nonce", &nonce)?;
+        insert_header(&mut headers, "x-acs-content-sha256", &payload_hash)?;
+        insert_header(&mut headers, "authorization", &authorization)?;
+
+        Ok(headers)
+    }
+}
+
+/// 把源图归一化成阿里云 SegmentCommonImage 接受的输入：统一 8 位 RGBA PNG、最长边 ≤1999、体积 ≤3MB。
+/// 返回编码后的 PNG 字节及其实际尺寸；尺寸若与源图不同说明发生了缩放，调用方需 alpha 上采样回原尺寸。
+fn normalize_matting_input_png(
+    source: &image::DynamicImage,
+) -> Result<(Vec<u8>, (u32, u32)), MattingError> {
+    normalize_matting_input_png_within(source, MAX_INPUT_BYTES)
+}
+
+/// `normalize_matting_input_png` 的可注入体积上限版本，便于单测用小阈值触发降尺寸循环。
+fn normalize_matting_input_png_within(
+    source: &image::DynamicImage,
+    max_bytes: usize,
+) -> Result<(Vec<u8>, (u32, u32)), MattingError> {
+    let mut max_edge = MAX_INPUT_EDGE;
+    loop {
+        // to_rgba8 统一成 8 位/通道 RGBA（32 位 PNG），规避阿里云不支持的 8/16/64 位 PNG 与非 PNG 格式。
+        let rgba = if source.width() > max_edge || source.height() > max_edge {
+            source
+                .resize(max_edge, max_edge, image::imageops::FilterType::CatmullRom)
+                .to_rgba8()
+        } else {
+            source.to_rgba8()
+        };
+        let encoded = encode_rgba_png(&rgba)?;
+        let (width, height) = rgba.dimensions();
+        if encoded.len() <= max_bytes {
+            return Ok((encoded, (width, height)));
+        }
+        // 仍超体积：等比缩到约 0.8 再试；一旦再缩会让边跌破阿里云 >32 下限就尽力返回当前
+        // （体积仍超限的图交给上游 4xx → 本地兜底，现实内容不会走到这一步）。
+        let longest = width.max(height);
+        let next = (longest as f32 * 0.8) as u32;
+        if next <= MIN_INPUT_EDGE || next >= longest {
+            return Ok((encoded, (width, height)));
+        }
+        max_edge = next;
+    }
+}
+
+fn encode_rgba_png(image: &image::RgbaImage) -> Result<Vec<u8>, MattingError> {
+    use image::ImageEncoder as _;
+    let mut encoded = Vec::new();
+    image::codecs::png::PngEncoder::new(&mut encoded)
+        .write_image(
+            image.as_raw(),
+            image.width(),
+            image.height(),
+            image::ExtendedColorType::Rgba8,
+        )
+        .map_err(|error| {
+            MattingError::upstream_response_error(
+                format!("编码抠图结果 PNG 失败：{error}"),
+                None,
+            )
+        })?;
+    Ok(encoded)
+}
+
+fn result_response_too_large_error() -> MattingError {
+    MattingError::upstream_response_error(
+        format!("抠图结果响应过大，超过 {MAX_RESULT_RESPONSE_BYTES} 字节上限"),
+        None,
+    )
+}
+
+/// 解码待抠图源图时套上尺寸 / 分配上限。源图直接来自请求体 / 生成产物，缺省
+/// `image::Limits` 无尺寸上限、仅 512MiB alloc 兜底，12MB 请求体即可构造巨幅压缩图
+/// （解压炸弹）在缩图前撑爆内存；逐帧动画并发调用时风险叠加。
+fn decode_source_image(bytes: &[u8]) -> Result<image::DynamicImage, MattingError> {
+    decode_image_within_limits(bytes)
+        .map_err(|error| MattingError::InvalidRequest(format!("解析待抠图图片失败：{error}")))
+}
+
+/// 解码抠图结果时套上尺寸 / 分配上限，防止上游用巨幅尺寸声明在解码阶段撑爆内存。
+fn decode_result_image(bytes: &[u8]) -> Result<image::DynamicImage, MattingError> {
+    decode_image_within_limits(bytes).map_err(|error| {
+        MattingError::upstream_response_error(format!("解析抠图结果图片失败：{error}"), None)
+    })
+}
+
+/// 统一的有界解码：尺寸上限 `MAX_DECODE_IMAGE_DIMENSION`、分配上限
+/// `MAX_RESULT_RESPONSE_BYTES * 4`，覆盖源图与抠图结果两条解码路径。
+fn decode_image_within_limits(bytes: &[u8]) -> Result<image::DynamicImage, String> {
+    use std::io::Cursor;
+
+    let mut reader = image::ImageReader::new(Cursor::new(bytes))
+        .with_guessed_format()
+        .map_err(|error| format!("识别图片格式失败：{error}"))?;
+    let mut limits = image::Limits::default();
+    limits.max_image_width = Some(MAX_DECODE_IMAGE_DIMENSION);
+    limits.max_image_height = Some(MAX_DECODE_IMAGE_DIMENSION);
+    limits.max_alloc = Some(MAX_RESULT_RESPONSE_BYTES as u64 * 4);
+    reader.limits(limits);
+    reader.decode().map_err(|error| error.to_string())
+}
+
+struct ViapiStsToken {
+    access_key_id: String,
+    access_key_secret: String,
+    security_token: String,
+}
+
+fn hmac_sha1_base64(key: &[u8], content: &[u8]) -> Result<String, MattingError> {
+    use base64::Engine as _;
+    let mut signer = Hmac::<sha1::Sha1>::new_from_slice(key)
+        .map_err(|error| MattingError::Sign(format!("初始化 OSS V1 签名器失败：{error}")))?;
+    signer.update(content);
+    Ok(base64::engine::general_purpose::STANDARD.encode(signer.finalize().into_bytes()))
+}
+
+fn describe_result_download_transport_error(error: &reqwest::Error) -> String {
+    sanitize_result_download_error_message(format!(
+        "下载抠图结果失败（transport={}, timeout={}, connect={}）",
+        classify_reqwest_error(error),
+        error.is_timeout(),
+        error.is_connect()
+    ))
+}
+
+fn describe_result_download_body_error(error: &reqwest::Error) -> String {
+    sanitize_result_download_error_message(format!(
+        "读取抠图结果字节失败（transport={}, timeout={}, connect={}）",
+        classify_reqwest_error(error),
+        error.is_timeout(),
+        error.is_connect()
+    ))
+}
+
+fn classify_reqwest_error(error: &reqwest::Error) -> &'static str {
+    if error.is_timeout() {
+        "timeout"
+    } else if error.is_connect() {
+        "connect"
+    } else if error.is_body() || error.is_decode() {
+        "body"
+    } else if error.is_request() {
+        "request"
+    } else {
+        "unknown"
+    }
+}
+
+fn sanitize_result_download_error_message(message: String) -> String {
+    if message.contains("OSSAccessKeyId=")
+        || message.contains("Signature=")
+        || message.contains("Expires=")
+    {
+        return "下载抠图结果失败（临时签名 URL 已脱敏）".to_string();
+    }
+    message
+}
+
+/// 脱敏 OSS 上传错误体：OSS 签名类错误会回显 StringToSign（含 `x-oss-security-token` 明文）、
+/// StringToSignBytes（其十六进制）和 SignatureProvided（签名串）。剥掉这三个元素，并把已知的
+/// STS 临时凭证在正文任何位置的出现替换为 `***`，保留 `<Code>` 等可诊断信息后再记录。
+fn sanitize_oss_upload_error_body(body: &str, security_token: &str) -> String {
+    let mut sanitized = body.to_string();
+    for tag in ["StringToSign", "StringToSignBytes", "SignatureProvided"] {
+        sanitized = redact_xml_element(&sanitized, tag);
+    }
+    let security_token = security_token.trim();
+    if !security_token.is_empty() {
+        sanitized = sanitized.replace(security_token, "***");
+    }
+    truncate_for_log(&sanitized)
+}
+
+/// 把 `<tag>…</tag>` 的内容替换成 `[redacted]`（tag 内容可跨行）；只有开标签无闭标签时丢弃其后全部内容。
+fn redact_xml_element(text: &str, tag: &str) -> String {
+    let open = format!("<{tag}>");
+    let close = format!("</{tag}>");
+    let mut result = String::with_capacity(text.len());
+    let mut rest = text;
+    while let Some(start) = rest.find(&open) {
+        result.push_str(&rest[..start]);
+        result.push_str(&open);
+        result.push_str("[redacted]");
+        let after_open = start + open.len();
+        match rest[after_open..].find(&close) {
+            Some(rel_end) => {
+                result.push_str(&close);
+                rest = &rest[after_open + rel_end + close.len()..];
+            }
+            None => {
+                rest = "";
+                break;
+            }
+        }
+    }
+    result.push_str(rest);
+    result
+}
+
+fn insert_header(
+    headers: &mut reqwest::header::HeaderMap,
+    name: &'static str,
+    value: &str,
+) -> Result<(), MattingError> {
+    let value = reqwest::header::HeaderValue::from_str(value)
+        .map_err(|error| MattingError::Sign(format!("构造请求头 {name} 失败：{error}")))?;
+    headers.insert(name, value);
+    Ok(())
+}
+
+fn current_aliyun_timestamp() -> String {
+    // 阿里云 OpenAPI ACS3 签名头 x-acs-date 要求不带小数秒的 UTC ISO 8601 格式
+    // （yyyy-MM-dd'T'HH:mm:ss'Z'），Rfc3339 默认会保留纳秒，网关会判定时间格式非法。
+    let now = OffsetDateTime::now_utc();
+    format!(
+        "{:04}-{:02}-{:02}T{:02}:{:02}:{:02}Z",
+        now.year(),
+        u8::from(now.month()),
+        now.day(),
+        now.hour(),
+        now.minute(),
+        now.second()
+    )
+}
+
+fn canonicalize_aliyun_form_params(params: &BTreeMap<String, String>) -> String {
+    params
+        .iter()
+        .map(|(key, value)| {
+            format!(
+                "{}={}",
+                urlencoding_encode(key),
+                urlencoding_encode(value)
+            )
+        })
+        .collect::<Vec<_>>()
+        .join("&")
+}
+
+fn urlencoding_encode(value: &str) -> String {
+    serde_urlencoded::to_string([("k", value)])
+        .map(|encoded| encoded.trim_start_matches("k=").to_string())
+        .unwrap_or_else(|_| value.to_string())
+}
+
+fn build_aliyun_form_body(params: &BTreeMap<String, String>) -> String {
+    serde_urlencoded::to_string(params).unwrap_or_else(|_| canonicalize_aliyun_form_params(params))
+}
+
+fn hmac_sha256_hex(key: &[u8], content: &[u8]) -> Result<String, MattingError> {
+    let mut signer = HmacSha256::new_from_slice(key)
+        .map_err(|error| MattingError::Sign(format!("初始化抠图签名器失败：{error}")))?;
+    signer.update(content);
+    Ok(hex::encode(signer.finalize().into_bytes()))
+}
+
+fn sha256_hex(content: &[u8]) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(content);
+    hex::encode(hasher.finalize())
+}
+
+fn truncate_for_log(text: &str) -> String {
+    const LIMIT: usize = 512;
+    if text.len() <= LIMIT {
+        text.to_string()
+    } else {
+        let mut end = LIMIT;
+        while !text.is_char_boundary(end) {
+            end -= 1;
+        }
+        format!("{}...(截断)", &text[..end])
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn local_preflight_variants_report_no_external_call() {
+        for error in [
+            MattingError::InvalidConfig("endpoint 为空".to_string()),
+            MattingError::InvalidRequest("待抠图图片尺寸过小".to_string()),
+            MattingError::Sign("初始化签名器失败".to_string()),
+        ] {
+            assert!(!error.external_call_attempted(), "{}", error.message());
+            assert!(!error.is_timeout());
+            assert!(!error.is_transport());
+            assert_eq!(error.upstream_status(), None);
+        }
+    }
+
+    #[test]
+    fn upstream_transport_error_classifies_as_transport() {
+        let error =
+            MattingError::upstream_transport_error("通用抠图请求失败：dns error".to_string(), false);
+        assert!(error.external_call_attempted());
+        assert!(error.is_transport());
+        assert!(!error.is_timeout());
+        assert_eq!(error.upstream_status(), None);
+    }
+
+    #[test]
+    fn upstream_transport_error_preserves_timeout_flag() {
+        let error =
+            MattingError::upstream_transport_error("通用抠图请求失败：timed out".to_string(), true);
+        assert!(error.external_call_attempted());
+        assert!(error.is_transport());
+        assert!(error.is_timeout());
+    }
+
+    #[test]
+    fn upstream_http_error_carries_status_and_is_not_transport() {
+        let error = MattingError::upstream_http_error(
+            "通用抠图接口返回失败（HTTP 429，Code=Throttled）".to_string(),
+            429,
+        );
+        assert!(error.external_call_attempted());
+        assert!(!error.is_transport());
+        assert!(!error.is_timeout());
+        assert_eq!(error.upstream_status(), Some(429));
+    }
+
+    #[test]
+    fn upstream_response_error_is_external_but_not_transport() {
+        let error = MattingError::upstream_response_error(
+            "抠图结果尺寸不一致".to_string(),
+            None,
+        );
+        assert!(error.external_call_attempted());
+        assert!(!error.is_transport());
+        assert!(!error.is_timeout());
+        assert_eq!(error.upstream_status(), None);
+    }
+
+    #[test]
+    fn form_body_is_sorted_and_url_encoded() {
+        let mut params = BTreeMap::new();
+        params.insert("ReturnForm".to_string(), "crop".to_string());
+        params.insert(
+            "ImageURL".to_string(),
+            "https://example.com/a.png?x=1&y=2".to_string(),
+        );
+        params.insert("Action".to_string(), "SegmentCommonImage".to_string());
+
+        let body = build_aliyun_form_body(&params);
+        assert_eq!(
+            body,
+            "Action=SegmentCommonImage&ImageURL=https%3A%2F%2Fexample.com%2Fa.png%3Fx%3D1%26y%3D2&ReturnForm=crop"
+        );
+    }
+
+    #[test]
+    fn signature_headers_use_acs3_sha256() {
+        let config = MattingConfig::new(
+            DEFAULT_IMAGESEG_ENDPOINT.to_string(),
+            "test-key-id".to_string(),
+            "test-key-secret".to_string(),
+        )
+        .expect("config should build");
+        let client = MattingClient::new(config).expect("client should build");
+        let headers = client
+            .build_signature_headers("SegmentCommonImage", "ImageURL=x")
+            .expect("headers should build");
+
+        let authorization = headers
+            .get("authorization")
+            .expect("authorization header should exist")
+            .to_str()
+            .expect("authorization header should be ascii");
+        assert!(authorization.starts_with("ACS3-HMAC-SHA256 Credential=test-key-id,"));
+        assert!(authorization.contains("SignedHeaders=host;x-acs-action;x-acs-content-sha256;"));
+        assert_eq!(
+            headers
+                .get("x-acs-version")
+                .and_then(|value| value.to_str().ok()),
+            Some("2019-12-30")
+        );
+        let date = headers
+            .get("x-acs-date")
+            .and_then(|value| value.to_str().ok())
+            .expect("x-acs-date should exist");
+        assert!(!date.contains('.'), "x-acs-date 不能带小数秒：{date}");
+    }
+
+    #[test]
+    fn result_download_error_message_redacts_signed_oss_url() {
+        let message = sanitize_result_download_error_message(
+            "下载抠图结果失败：error sending request for url (https://viapi-customer-temp.oss-cn-shanghai.aliyuncs.com/a.png?OSSAccessKeyId=ak&Expires=123&Signature=secret)".to_string(),
+        );
+
+        assert!(!message.contains("OSSAccessKeyId"));
+        assert!(!message.contains("Signature"));
+        assert!(!message.contains("Expires=123"));
+        assert_eq!(message, "下载抠图结果失败（临时签名 URL 已脱敏）");
+    }
+
+    #[test]
+    fn result_download_error_message_keeps_safe_text() {
+        let message = sanitize_result_download_error_message(
+            "下载抠图结果失败（transport=connect, timeout=false, connect=true）".to_string(),
+        );
+
+        assert_eq!(
+            message,
+            "下载抠图结果失败（transport=connect, timeout=false, connect=true）"
+        );
+    }
+
+    #[test]
+    fn oss_upload_error_body_redacts_signature_material_and_token() {
+        let token = "CAISabcSECRETtoken123";
+        let body = format!(
+            "<Error><Code>SignatureDoesNotMatch</Code>\
+             <Message>mismatch for {token}</Message>\
+             <SignatureProvided>sigSECRET==</SignatureProvided>\
+             <StringToSignBytes>50 55 54 0a</StringToSignBytes>\
+             <StringToSign>PUT\nx-oss-security-token:{token}\n/bucket/key</StringToSign></Error>"
+        );
+
+        let sanitized = sanitize_oss_upload_error_body(&body, token);
+
+        // 敏感串全部消失：StringToSign 明文、其中的 token、十六进制、签名串、以及 Message 里的 token 明文。
+        assert!(!sanitized.contains(token), "STS token 不能残留（含元素外的明文）");
+        assert!(!sanitized.contains("x-oss-security-token:CAIS"), "StringToSign 明文不能残留");
+        assert!(!sanitized.contains("sigSECRET"), "SignatureProvided 不能残留");
+        assert!(!sanitized.contains("50 55 54 0a"), "StringToSignBytes 不能残留");
+        // 可诊断信息保留。
+        assert!(sanitized.contains("SignatureDoesNotMatch"), "OSS Code 应保留供诊断");
+        assert!(sanitized.contains("[redacted]"), "签名材料元素应被脱敏为 [redacted]");
+    }
+
+    fn noise_image(width: u32, height: u32) -> image::DynamicImage {
+        // 不易压缩的伪随机噪声，保证 PNG 体积随像素数量增长，可触发降尺寸循环。
+        let mut img = image::RgbaImage::new(width, height);
+        for (x, y, px) in img.enumerate_pixels_mut() {
+            let v = ((x * 71 + y * 131 + x * y) % 256) as u8;
+            *px = image::Rgba([v, v.wrapping_mul(3), v.wrapping_add(97), 255]);
+        }
+        image::DynamicImage::ImageRgba8(img)
+    }
+
+    #[test]
+    fn normalize_keeps_small_image_and_outputs_png() {
+        let source =
+            image::DynamicImage::ImageRgba8(image::RgbaImage::from_pixel(200, 150, image::Rgba([10, 20, 30, 255])));
+        let (bytes, dims) =
+            normalize_matting_input_png(&source).expect("normalize should succeed");
+
+        assert_eq!(dims, (200, 150), "小图不缩放，尺寸原样");
+        assert_eq!(
+            image::guess_format(&bytes).expect("guess format"),
+            image::ImageFormat::Png,
+            "输出必须是 PNG"
+        );
+        let decoded = image::load_from_memory(&bytes).expect("output should decode");
+        assert_eq!((decoded.width(), decoded.height()), (200, 150));
+    }
+
+    #[test]
+    fn normalize_caps_oversized_edge_to_1999() {
+        let source =
+            image::DynamicImage::ImageRgba8(image::RgbaImage::from_pixel(2400, 1200, image::Rgba([0, 0, 0, 255])));
+        let (_bytes, (width, height)) =
+            normalize_matting_input_png(&source).expect("normalize should succeed");
+
+        assert!(width <= MAX_INPUT_EDGE && height <= MAX_INPUT_EDGE, "两边都 ≤1999，实得 {width}x{height}");
+        assert_eq!(width.max(height), MAX_INPUT_EDGE, "最长边压到 1999");
+    }
+
+    #[test]
+    fn normalize_downscales_until_under_byte_limit() {
+        let source = noise_image(300, 300);
+        let full = normalize_matting_input_png(&source)
+            .expect("full-size normalize should succeed")
+            .0;
+        // 阈值取全尺寸 PNG 的一半，必须触发降尺寸。
+        let limit = full.len() / 2;
+
+        let (bytes, (width, height)) = normalize_matting_input_png_within(&source, limit)
+            .expect("limited normalize should succeed");
+
+        assert!(width < 300 && height < 300, "应从 300x300 降尺寸，实得 {width}x{height}");
+        assert!(
+            bytes.len() <= limit || width.min(height) <= MIN_INPUT_EDGE + 1,
+            "编码 {} 字节应落在 {limit} 内（或已触最小边下限）",
+            bytes.len()
+        );
+        assert_eq!(
+            image::guess_format(&bytes).expect("guess format"),
+            image::ImageFormat::Png,
+            "降尺寸后仍是 PNG"
+        );
+    }
+}
diff --git a/server-rs/crates/shared-contracts/src/assets.rs b/server-rs/crates/shared-contracts/src/assets.rs
index 90a03a889..c30598dc1 100644
--- a/server-rs/crates/shared-contracts/src/assets.rs
+++ b/server-rs/crates/shared-contracts/src/assets.rs
@@ -314,6 +314,9 @@ pub struct EditorCharacterAnimationGenerateRequest {
     pub source_width: u32,
     pub source_height: u32,
     pub prompt_text: String,
+    /// 纯色抠像背景色（hex）。None/auto 走自动决策；通常继承源角色图的背景色。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub screen_color: Option<String>,
     pub resolution: String,
     pub ratio: String,
     pub frame_count: u32,
@@ -1075,6 +1078,7 @@ mod tests {
             source_width: 768,
             source_height: 1024,
             prompt_text: "待机呼吸".to_string(),
+            screen_color: None,
             resolution: "720p".to_string(),
             ratio: "same".to_string(),
             frame_count: 48,
diff --git a/src/components/asset-studio/characterAssetWorkflowModel.ts b/src/components/asset-studio/characterAssetWorkflowModel.ts
index a37239d2c..b9e945bd2 100644
--- a/src/components/asset-studio/characterAssetWorkflowModel.ts
+++ b/src/components/asset-studio/characterAssetWorkflowModel.ts
@@ -1,4 +1,3 @@
-import { removeBackgroundFromRgba } from '../../../packages/shared/src/assets/chromaKey';
 import {
   AnimationState,
   type Character,
@@ -453,19 +452,6 @@ export function loadImageFromSource(source: string) {
   });
 }
 
-function loadVideoFromSource(source: string) {
-  return new Promise<HTMLVideoElement>((resolve, reject) => {
-    const video = document.createElement('video');
-    video.crossOrigin = 'anonymous';
-    video.preload = 'auto';
-    video.muted = true;
-    video.playsInline = true;
-    video.onloadeddata = () => resolve(video);
-    video.onerror = () => reject(new Error(`加载视频失败：${source}`));
-    video.src = source;
-  });
-}
-
 function createCanvas(width: number, height: number) {
   const canvas = document.createElement('canvas');
   canvas.width = width;
@@ -708,200 +694,6 @@ export async function buildAnimationClipFromMaster(
   } satisfies DraftAnimationClip;
 }
 
-function applyGreenScreenAlpha(
-  context: CanvasRenderingContext2D,
-  width: number,
-  height: number,
-) {
-  const imageData = context.getImageData(0, 0, width, height);
-  removeBackgroundFromRgba(imageData.data, width, height);
-
-  context.putImageData(imageData, 0, 0);
-}
-
-async function normalizeFrameSourceToDataUrl(
-  frameSource: string,
-  options: {
-    frameWidth: number;
-    frameHeight: number;
-    applyChromaKey: boolean;
-  },
-) {
-  const image = await loadImageFromSource(frameSource);
-  const { canvas, context } = createCanvas(
-    options.frameWidth,
-    options.frameHeight,
-  );
-  context.clearRect(0, 0, canvas.width, canvas.height);
-  drawContainedImage(context, image, {
-    width: canvas.width,
-    height: canvas.height,
-  });
-
-  if (options.applyChromaKey) {
-    applyGreenScreenAlpha(context, canvas.width, canvas.height);
-  }
-
-  return canvas.toDataURL('image/png');
-}
-
-export async function normalizeMasterVisualSourceToDataUrl(
-  source: string,
-  options: {
-    applyChromaKey?: boolean;
-  } = {},
-) {
-  const image = await loadImageFromSource(source);
-  const { canvas, context } = createCanvas(
-    MASTER_VISUAL_WIDTH,
-    MASTER_VISUAL_HEIGHT,
-  );
-  context.clearRect(0, 0, canvas.width, canvas.height);
-  drawContainedImage(context, image, {
-    width: canvas.width,
-    height: canvas.height,
-  });
-
-  if (options.applyChromaKey !== false) {
-    applyGreenScreenAlpha(context, canvas.width, canvas.height);
-  }
-
-  return {
-    dataUrl: canvas.toDataURL('image/png'),
-    width: canvas.width,
-    height: canvas.height,
-  };
-}
-
-function seekVideo(video: HTMLVideoElement, targetTime: number) {
-  return new Promise<void>((resolve, reject) => {
-    if (Math.abs(video.currentTime - targetTime) < 0.001) {
-      window.requestAnimationFrame(() => resolve());
-      return;
-    }
-
-    const handleSeeked = () => {
-      cleanup();
-      resolve();
-    };
-    const handleError = () => {
-      cleanup();
-      reject(new Error('视频定位失败'));
-    };
-    const cleanup = () => {
-      video.removeEventListener('seeked', handleSeeked);
-      video.removeEventListener('error', handleError);
-    };
-
-    video.addEventListener('seeked', handleSeeked, { once: true });
-    video.addEventListener('error', handleError, { once: true });
-    video.currentTime = Math.max(0, targetTime);
-  });
-}
-
-export async function buildAnimationClipFromImageSources(
-  sources: string[],
-  options: {
-    animation: AnimationState;
-    fps: number;
-    loop: boolean;
-    frameWidth?: number;
-    frameHeight?: number;
-    applyChromaKey?: boolean;
-  },
-) {
-  const frameWidth = options.frameWidth ?? GENERATED_FRAME_WIDTH;
-  const frameHeight = options.frameHeight ?? GENERATED_FRAME_HEIGHT;
-  const frames = await Promise.all(
-    sources.map((source) =>
-      normalizeFrameSourceToDataUrl(source, {
-        frameWidth,
-        frameHeight,
-        applyChromaKey: options.applyChromaKey ?? false,
-      }),
-    ),
-  );
-
-  return {
-    animation: options.animation,
-    frames,
-    fps: Math.max(1, options.fps),
-    loop: options.loop,
-    frameWidth,
-    frameHeight,
-  } satisfies DraftAnimationClip;
-}
-
-export async function buildAnimationClipFromVideoSource(
-  videoSource: string,
-  options: {
-    animation: AnimationState;
-    fps: number;
-    loop: boolean;
-    frameCount?: number;
-    frameWidth?: number;
-    frameHeight?: number;
-    applyChromaKey?: boolean;
-    sampleStartRatio?: number;
-    sampleEndRatio?: number;
-  },
-) {
-  const video = await loadVideoFromSource(videoSource);
-  const frameWidth = options.frameWidth ?? GENERATED_FRAME_WIDTH;
-  const frameHeight = options.frameHeight ?? GENERATED_FRAME_HEIGHT;
-  const duration =
-    Number.isFinite(video.duration) && video.duration > 0 ? video.duration : 1;
-  const derivedFrameCount = Math.max(
-    2,
-    options.frameCount ?? Math.round(duration * Math.max(1, options.fps)),
-  );
-  const sampleStartRatio = Math.min(
-    0.85,
-    Math.max(0, options.sampleStartRatio ?? 0),
-  );
-  const sampleEndRatio = Math.min(
-    1,
-    Math.max(sampleStartRatio + 0.05, options.sampleEndRatio ?? 1),
-  );
-  const sampleWindowDuration = duration * (sampleEndRatio - sampleStartRatio);
-  const { canvas, context } = createCanvas(frameWidth, frameHeight);
-  const frames: string[] = [];
-
-  for (let frameIndex = 0; frameIndex < derivedFrameCount; frameIndex += 1) {
-    const progress = options.loop
-      ? frameIndex / derivedFrameCount
-      : frameIndex / Math.max(1, derivedFrameCount - 1);
-    const targetTime = Math.min(
-      duration - 0.001,
-      duration * sampleStartRatio + sampleWindowDuration * progress,
-    );
-
-    await seekVideo(video, targetTime);
-
-    context.clearRect(0, 0, canvas.width, canvas.height);
-    drawContainedSource(context, video, video.videoWidth, video.videoHeight, {
-      width: canvas.width,
-      height: canvas.height,
-    });
-
-    if (options.applyChromaKey) {
-      applyGreenScreenAlpha(context, canvas.width, canvas.height);
-    }
-
-    frames.push(canvas.toDataURL('image/png'));
-  }
-
-  return {
-    animation: options.animation,
-    frames,
-    fps: Math.max(1, options.fps),
-    loop: options.loop,
-    frameWidth,
-    frameHeight,
-    previewVideoPath: videoSource,
-  } satisfies DraftAnimationClip;
-}
-
 async function buildReferenceVideoFromFrameSources(
   frameSources: string[],
   options: {
diff --git a/src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts b/src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts
index 7abdb2cf7..85c6078e4 100644
--- a/src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts
+++ b/src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts
@@ -726,6 +726,7 @@ describe('ImageCanvasGenerationSubmissionModel', () => {
         sourceWidth: 960,
         sourceHeight: 1280,
         promptText: '循环奔跑动作',
+        screenColor: 'auto',
         resolution: '720p',
         ratio: 'same',
         frameCount: 48,
diff --git a/src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts b/src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts
index 4d57e52e9..6f2d1c139 100644
--- a/src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts
+++ b/src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts
@@ -649,6 +649,8 @@ export function buildCharacterAnimationSubmissionPlan({
       sourceWidth: sourceLayer.originalWidth,
       sourceHeight: sourceLayer.originalHeight,
       promptText,
+      // 与生图入口一致：默认 auto，由后端做背景色自动决策。
+      screenColor: DEFAULT_EDITOR_GENERATION_BACKGROUND_COLOR,
       resolution: panel.resolution,
       ratio: panel.ratio,
       frameCount: panel.frameCount,
diff --git a/src/services/image-editor/editorProjectClient.ts b/src/services/image-editor/editorProjectClient.ts
index bc831182b..5c0ef5c53 100644
--- a/src/services/image-editor/editorProjectClient.ts
+++ b/src/services/image-editor/editorProjectClient.ts
@@ -328,6 +328,8 @@ export type EditorCharacterAnimationGenerationInput = {
   sourceWidth: number;
   sourceHeight: number;
   promptText: string;
+  /** 纯色抠像背景色（hex 或 'auto'），继承生图的背景色选项行为。 */
+  screenColor?: string;
   resolution: EditorCharacterAnimationResolution;
   ratio: EditorCharacterAnimationRatio;
   frameCount: EditorCharacterAnimationFrameCount;