补充抠图模式调用说明

说明complex语义分割与flat纯色背景抠图明确纯色背景优先使用flat并移除内部实现术语
2026-09-16 21:36:15 +08:00
parent e08b031761
commit 13f56e644d
3 changed files with 7 additions and 7 deletions
@@ -453,12 +453,12 @@ fn direct_tools_mcp_specs_for(controlled_web_search: bool, _cocos_editor_availab
                        "backgroundMode": {
                            "type": "string",
                            "enum": ["complex", "flat"],
-                            "description": "可选抠图模式；省略时使用 complex"
+                            "description": "可选抠图模式：complex 用语义分割识别前景，flat 用纯色背景抠图；确定背景为纯色时优先使用 flat。省略时使用 complex"
                        },
                        "screenColor": {
                            "type": "string",
                            "pattern": "^(auto|#[0-9A-Fa-f]{6})$",
-                            "description": "flat 模式可选背景色；传 auto 或 #RRGGBB，省略由 BgFilter 自动检测"
+                            "description": "flat 模式可选背景色；传 auto 或 #RRGGBB，省略时由服务自动检测"
                        }
                    },
                    "required": ["sourceLocalAssetId", "assetName"],
@@ -1122,7 +1122,7 @@
        "tags": ["Editor Images"],
        "operationId": "removeExternalEditorImageBackground",
        "summary": "去除编辑器图片背景",
-        "description": "提交已有静态图片素材的异步去背景任务。sourceImageSrc 只接受当前账号拥有的稳定 objectKey、项目资源 ID 或素材 ID；禁止 Data URL、Blob URL 和临时 signed URL。assetKind 只能表达静态图片，并且存在权威来源记录时必须与其类型一致；视频、音频、动画和图片序列在入队前返回 400。服务端固定使用 complex 去背景模式，不会在失败时切换到其它 provider。需要写入画布时提供 projectId 与 canvasCompletion；仅需原位替换既有图层时提供 projectId 与 targetLayerId，且来源与目标必须指向同一权威对象。",
+        "description": "提交已有静态图片素材的异步去背景任务。sourceImageSrc 只接受当前账号拥有的稳定 objectKey、项目资源 ID 或素材 ID；禁止 Data URL、Blob URL 和临时 signed URL。assetKind 只能表达静态图片，并且存在权威来源记录时必须与其类型一致；视频、音频、动画和图片序列在入队前返回 400。complex 使用语义分割识别前景，flat 用于纯色背景抠图；确定背景为纯色时优先使用 flat。需要写入画布时提供 projectId 与 canvasCompletion；仅需原位替换既有图层时提供 projectId 与 targetLayerId，且来源与目标必须指向同一权威对象。",
        "security": [
          {
            "ExternalApiKey": []
@@ -3215,12 +3215,12 @@
            "type": ["string", "null"],
            "enum": ["complex", "flat", null],
            "default": "complex",
-            "description": "抠图模式。不填按 complex 处理；flat 使用纯色背景管线。"
+            "description": "抠图模式。不填按 complex 处理；complex 使用语义分割识别前景，flat 用于纯色背景抠图。确定背景为纯色时优先使用 flat。"
          },
          "screenColor": {
            "type": ["string", "null"],
            "pattern": "^(auto|#[0-9A-Fa-f]{6})$",
-            "description": "仅 flat 模式使用。可传 auto、#RRGGBB 或省略；auto 和省略由 BgFilter 自动检测背景色。complex 搭配此字段返回 400。"
+            "description": "仅 flat 模式使用。可传 auto、#RRGGBB 或省略；auto 和省略由服务自动检测背景色。complex 搭配此字段返回 400。"
          },
          "projectId": {
            "type": ["string", "null"],
@@ -2,7 +2,7 @@

 ## 目标

-主站编辑器保持现有前端行为（继续使用 `complex`），同时扩展 External v1 抠图接口和 AGC 客户端，使客户端可以选择 `complex` / `flat`，并把 `screenColor` 原样交给 BgFilter。`auto` 的背景色识别完全由 BgFilter 负责，主站不读取图片、不调用模型决策颜色、不生成颜色兜底值。
+主站编辑器保持现有前端行为（继续使用 `complex`），同时扩展 External v1 抠图接口和 AGC 客户端，使客户端可以选择 `complex` / `flat`，并把 `screenColor` 原样交给 BgFilter。`complex` 用语义分割识别前景，`flat` 用于纯色背景抠图；确定背景为纯色时优先使用 `flat`。`auto` 的背景色识别完全由下游服务负责，主站不读取图片、不调用模型决策颜色、不生成颜色兜底值。

 ## 当前 BgFilter 契约

@@ -16,7 +16,7 @@

 主站向 BgFilter 发送 `#RRGGBB` 时保留 `#`，`auto` 也原样发送，不做所谓的“hex 转换”。

-服务器实现细节：`screen_color` 在 `auto` 或省略时传入内部 pipeline 的 `None`，由边框颜色自动检测；`#RRGGBB` 才会经过颜色解析用于色键。`background_mode` 缺省在 BgFilter 侧为 `flat`，因此主站必须为 External v1 旧请求显式归一化为 `complex`，不能把 BgFilter 的默认值直接当成主站默认值。
+服务器行为：`screen_color` 在 `auto` 或省略时由服务自动检测；`#RRGGBB` 用作指定背景色。`background_mode` 缺省在 BgFilter 侧为 `flat`，因此主站必须为 External v1 旧请求显式归一化为 `complex`，不能把下游服务的默认值直接当成主站默认值。

 ## External v1 请求契约