澄清External像素规整尺寸契约

明确 pixelArt 成功产物使用逻辑分辨率及最终实际尺寸。限定 dimension-restore-fallback 仅描述进入 pixelArt 前的交付尺寸归一结果。同步 External API Skill、OpenAPI 与接入文档的尺寸说明。
2026-08-10 08:08:24 +00:00
parent 07245724ec
commit e333a808fe
4 changed files with 23 additions and 14 deletions
@@ -3273,7 +3273,7 @@
              "none",
              "pixelArt"
            ],
-            "description": "可选生成风格，当前识别 none 与 pixelArt。省略、null、空字符串或 none 按无风格处理，提交给 provider 的提示词与未带该字段时逐字一致；pixelArt 仅支持普通图片（kind 省略）和 character，会在提示词末尾追加一行像素风约束（普通图片为「画面为像素风格」，character 为「角色主体为像素风格」）并在回图后执行像素规整。未知字符串或不支持该风格的 kind 按 none 继续生成并返回 unsupported-image-style 告警；非字符串值返回 400。"
+            "description": "可选生成风格，当前识别 none 与 pixelArt。省略、null、空字符串或 none 按无风格处理，提交给 provider 的提示词与未带该字段时逐字一致；pixelArt 仅支持普通图片（kind 省略）和 character，会在提示词末尾追加一行像素风约束（普通图片为「画面为像素风格」，character 为「角色主体为像素风格」）并在回图后执行像素规整。规整成功时直接持久化一格一像素的逻辑分辨率 PNG，不恢复到 size、imageSize、provider 回图或 canvasCompletion.placeholder 的尺寸；width/height 及关联 resource/asset 尺寸均为最终 PNG 的实际值。未知字符串或不支持该风格的 kind 按 none 继续生成并返回 unsupported-image-style 告警；非字符串值返回 400。"
          },
          "size": {
            "type": "string",
@@ -3385,7 +3385,7 @@
                "type": "null"
              }
            ],
-            "description": "带项目上下文生成时，服务端据此直接写入画布完成态并返回最新项目快照。"
+            "description": "带项目上下文生成时，服务端据此直接写入画布完成态并返回最新项目快照。placeholder 只参与占位与完成落点，不约束最终媒体像素尺寸；pixelArt 规整成功时结果图层使用最终逻辑分辨率 PNG 的实际尺寸。"
          }
        },
        "additionalProperties": false
@@ -3578,11 +3578,13 @@
          },
          "width": {
            "type": "integer",
-            "minimum": 1
+            "minimum": 1,
+            "description": "最终持久化 PNG 的实际像素宽度；pixelArt 规整成功时为逻辑网格宽度，不保证等于 size、imageSize、provider 回图或画布 placeholder 宽度。"
          },
          "height": {
            "type": "integer",
-            "minimum": 1
+            "minimum": 1,
+            "description": "最终持久化 PNG 的实际像素高度；pixelArt 规整成功时为逻辑网格高度，不保证等于 size、imageSize、provider 回图或画布 placeholder 高度。"
          },
          "sourceType": {
            "type": "string",
@@ -3698,7 +3700,7 @@
              "none",
              "pixelArt"
            ],
-            "description": "可选生成风格，当前识别 none 与 pixelArt。省略、null、空字符串或 none 按无风格处理，提交给 provider 的提示词与未带该字段时逐字一致；pixelArt 会在提示词末尾追加一行「每个图标素材均为像素风格」并启用图标图集像素规整。未知字符串按 none 继续生成并返回 unsupported-image-style 告警；非字符串值返回 400。"
+            "description": "可选生成风格，当前识别 none 与 pixelArt。省略、null、空字符串或 none 按无风格处理，提交给 provider 的提示词与未带该字段时逐字一致；pixelArt 会在提示词末尾追加一行「每个图标素材均为像素风格」并启用图标图集像素规整。规整成功时直接持久化一格一像素的逻辑分辨率透明 PNG，不恢复到 imageSize、provider 回图或 canvasCompletion.placeholder 的尺寸；spritesheetWidth/spritesheetHeight 及关联 resource/asset 尺寸均为最终 PNG 的实际值。未知字符串按 none 继续生成并返回 unsupported-image-style 告警；非字符串值返回 400。"
          },
          "model": {
            "type": "string",
@@ -3756,7 +3758,7 @@
                "type": "null"
              }
            ],
-            "description": "带项目上下文生成时，服务端据此直接写入画布完成态并返回最新项目快照。"
+            "description": "带项目上下文生成时，服务端据此直接写入画布完成态并返回最新项目快照。placeholder 只参与占位与完成落点，不约束最终媒体像素尺寸；pixelArt 规整成功时结果图层使用最终逻辑分辨率 PNG 的实际尺寸。"
          }
        },
        "additionalProperties": false
@@ -3919,7 +3921,7 @@
              "unsupported-image-style",
              "multiple-generation-warnings"
            ],
-            "description": "生成成功但后处理发生非阻断降级时的稳定原因码。"
+            "description": "生成成功但后处理发生非阻断降级时的稳定原因码。dimension-restore-fallback 只描述进入可选 pixelArt 处理前的交付尺寸归一结果：无法安全归一时，在该处理边界保留 provider 回图尺寸；它不描述或约束 pixelArt 成功后的最终尺寸，最终产物尺寸仍以逻辑分辨率 PNG 为准。"
          },
          "reason": {
            "type": "string",
@@ -3945,11 +3947,13 @@
          },
          "spritesheetWidth": {
            "type": "integer",
-            "minimum": 1
+            "minimum": 1,
+            "description": "最终持久化 spritesheet PNG 的实际像素宽度；pixelArt 规整成功时为逻辑网格宽度，不保证等于 imageSize、provider 回图或画布 placeholder 宽度。"
          },
          "spritesheetHeight": {
            "type": "integer",
-            "minimum": 1
+            "minimum": 1,
+            "description": "最终持久化 spritesheet PNG 的实际像素高度；pixelArt 规整成功时为逻辑网格高度，不保证等于 imageSize、provider 回图或画布 placeholder 高度。"
          },
          "iconImageSrcs": {
            "type": "array",
@@ -4948,7 +4952,7 @@
          }
        },
        "additionalProperties": true,
-        "description": "其它生成类型或历史结果的兼容 compact result。背景音乐（audioKind=background-music）与不带 audioKind 的图片、视频、图标序列帧、角色动作和 UI 拆解结果都落在这里。该 fallback 明确排除 audioKind=sound-effect，避免吞掉 SFX 专用分支。"
+        "description": "其它生成类型或历史结果的兼容 compact result。背景音乐（audioKind=background-music）与不带 audioKind 的图片、视频、图标序列帧、角色动作和 UI 拆解结果都落在这里。pixelArt 图片的 width/height、图标结果的 spritesheetWidth/spritesheetHeight 及关联 resource/asset 尺寸均表示最终逻辑分辨率 PNG 的实际值，不保证等于请求档位、provider 回图或画布 placeholder。该 fallback 明确排除 audioKind=sound-effect，避免吞掉 SFX 专用分支。"
      },
      "ExternalEditorGenerationCompletedResult": {
        "oneOf": [