修复 External SFX 轮询契约

新增具名 SFX compact 结果联合与稳定引用约束补强轮询 OpenAPI 以及音效 metadata 结果测试
2026-08-08 05:39:41 +00:00
parent 38e195060b
commit 8a42b23ea4
3 changed files with 283 additions and 5 deletions
@@ -4818,6 +4818,152 @@
          }
        }
      },
+      "ExternalEditorGenerationCompactResourceReference": {
+        "type": "object",
+        "required": [
+          "resourceId"
+        ],
+        "properties": {
+          "resourceId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "projectId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "objectKey": {
+            "type": "string",
+            "minLength": 1
+          },
+          "assetObjectId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "sourceResourceId": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "additionalProperties": true,
+        "description": "完成态 compact result 中的稳定画布资源引用；不是完整 resource 快照。"
+      },
+      "ExternalEditorGenerationCompactAssetReference": {
+        "type": "object",
+        "required": [
+          "assetId"
+        ],
+        "properties": {
+          "assetId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "folderId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "objectKey": {
+            "type": "string",
+            "minLength": 1
+          },
+          "assetObjectId": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "additionalProperties": true,
+        "description": "完成态 compact result 中的稳定素材库引用；不是完整 asset 快照。"
+      },
+      "ExternalEditorSoundEffectCompactResult": {
+        "type": "object",
+        "required": [
+          "audioKind"
+        ],
+        "properties": {
+          "audioKind": {
+            "type": "string",
+            "const": "sound-effect"
+          },
+          "durationSeconds": {
+            "type": "number",
+            "exclusiveMinimum": 0,
+            "maximum": 600,
+            "description": "SFX V2 保存 MP3 后探测得到的实际时长；不是请求时长。历史完成结果可缺少此字段。"
+          },
+          "loop": {
+            "type": "boolean",
+            "description": "SFX V2 冻结并发送给 provider 的 Loop；历史完成结果可缺少此字段。"
+          },
+          "taskId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "objectKey": {
+            "type": "string",
+            "minLength": 1,
+            "description": "持久化音频对象的稳定引用；需要临时下载或预览 URL 时使用 assets/read-url。"
+          },
+          "assetObjectId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "resource": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/ExternalEditorGenerationCompactResourceReference"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "asset": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/ExternalEditorGenerationCompactAssetReference"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          }
+        },
+        "additionalProperties": true,
+        "description": "External SFX 完成态的 compact result。仅包含稳定产物引用和可安全消费的 SFX 元数据；不包含完整 project/canvas/asset 快照或脱敏的 Prompt、模型与 provider 字段。"
+      },
+      "ExternalEditorGenerationGenericCompactResult": {
+        "type": "object",
+        "not": {
+          "type": "object",
+          "required": [
+            "audioKind"
+          ],
+          "properties": {
+            "audioKind": {
+              "const": "sound-effect"
+            }
+          }
+        },
+        "additionalProperties": true,
+        "description": "其它生成类型或历史结果的兼容 compact result。该 fallback 明确排除 audioKind=sound-effect，避免吞掉 SFX 专用分支。"
+      },
+      "ExternalEditorGenerationCompletedResult": {
+        "oneOf": [
+          {
+            "$ref": "#/components/schemas/ExternalEditorSoundEffectCompactResult"
+          },
+          {
+            "$ref": "#/components/schemas/ExternalEditorGenerationGenericCompactResult"
+          }
+        ],
+        "discriminator": {
+          "propertyName": "audioKind",
+          "mapping": {
+            "sound-effect": "#/components/schemas/ExternalEditorSoundEffectCompactResult"
+          }
+        },
+        "description": "External v1 轮询 completed 状态的命名 compact result 联合。"
+      },
      "ExternalEditorGenerationSubmissionResponse": {
        "type": "object",
        "required": [
@@ -4902,9 +5048,8 @@
            "type": "string"
          },
          "result": {
-            "type": "object",
-            "description": "completed 时返回的 compact 稳定结果引用；不包含完整 project/canvas、Data URL、Blob URL 或临时签名 URL。",
-            "additionalProperties": true
+            "$ref": "#/components/schemas/ExternalEditorGenerationCompletedResult",
+            "description": "仅在 completed 时返回的 compact 稳定结果引用；queued、running 和 failed 不返回该字段。为兼容历史完成结果，此字段不作为无版本迁移的必填约束。"
          },
          "pollAfterMs": {
            "type": "integer",