{
  "openapi": "3.1.0",
  "info": {
    "title": "陶泥儿外部编辑器 OpenAPI",
    "version": "1.0.0",
    "description": "外部系统调用陶泥儿图片画布项目、画布布局、素材库，以及图片、视频、音效、音乐等编辑器素材生成/编辑能力的 v1 契约。全部生成 POST 都是异步提交：必须携带 Idempotency-Key，收到 202 后使用 operationId 查询统一生成状态。支持远程 MCP 的 Agent 可连接 /api/external/v1/mcp；不支持 MCP 的 Agent 可从 /api/external/v1/skill.zip 下载完整 Skill 包。新建 projectId 使用 proj- 前缀，新建 taskId / operationId 使用 task- 前缀；历史 editor-project-*、aitask_*、extgen-* ID 仍可作为既有资源标识传入。\n\n兼容性说明：截至 2026-08-08，v1 经当前线上 API Key 与调用方状态确认仍无外部存量调用方；正式对外发放 API Key 之前，契约可能依据明确决策在不升 info.version、不设弃用期的情况下发生包含字段移除在内的破坏性变更。生成客户端时请勿假定本文档已冻结。"
  },
  "servers": [
    {
      "url": "/",
      "description": "当前部署环境"
    }
  ],
  "tags": [
    {
      "name": "Editor Projects",
      "description": "图片画布项目"
    },
    {
      "name": "Editor Canvas",
      "description": "图片画布布局"
    },
    {
      "name": "Editor Assets",
      "description": "账号级编辑器素材库"
    },
    {
      "name": "Asset Objects",
      "description": "素材对象上传、确认与签名读取"
    },
    {
      "name": "Editor Images",
      "description": "编辑器美术生图"
    },
    {
      "name": "Editor Videos",
      "description": "编辑器视频与角色动画生成"
    },
    {
      "name": "Editor Audio",
      "description": "编辑器音效与音乐生成"
    },
    {
      "name": "Agent Integration",
      "description": "远程 MCP、OpenAPI 和完整 Skill 包发现"
    }
  ],
  "paths": {
    "/api/external/v1/openapi.json": {
      "get": {
        "tags": ["Editor Projects"],
        "operationId": "getExternalOpenApiJson",
        "summary": "读取外部 API OpenAPI JSON",
        "security": [],
        "responses": {
          "200": {
            "description": "OpenAPI 3.1 JSON",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/external/v1/agent-integration.json": {
      "get": {
        "tags": ["Agent Integration"],
        "operationId": "getExternalAgentIntegrationManifest",
        "summary": "读取 Agent 集成清单",
        "description": "返回远程 MCP、OpenAPI、Skill 入口、完整 Skill ZIP、包内文件列表和归档 SHA-256。",
        "security": [],
        "x-mcp-excluded": true,
        "responses": {
          "200": {
            "description": "Agent 集成清单",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/external/v1/skill/SKILL.md": {
      "get": {
        "tags": ["Agent Integration"],
        "operationId": "getExternalEditorSkillEntry",
        "summary": "读取外部编辑器 Skill 入口",
        "security": [],
        "x-mcp-excluded": true,
        "responses": {
          "200": {
            "description": "SKILL.md",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/external/v1/skill.zip": {
      "get": {
        "tags": ["Agent Integration"],
        "operationId": "downloadExternalEditorSkillArchive",
        "summary": "下载完整外部编辑器 Skill 包",
        "security": [],
        "x-mcp-excluded": true,
        "responses": {
          "200": {
            "description": "包含 SKILL.md、references、scripts 和 agents metadata 的 ZIP",
            "content": {
              "application/zip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          }
        }
      }
    },
    "/api/external/v1/mcp": {
      "post": {
        "tags": ["Agent Integration"],
        "operationId": "callExternalEditorMcp",
        "summary": "调用托管式远程 MCP",
        "description": "MCP 2025-11-25 Streamable HTTP JSON 端点。使用与 REST API 相同的 Bearer API Key；生成工具立即返回异步 operation。resources/list 和 resources/read 提供 usage、OpenAPI、Skill 主入口以及 capability routing、API operations、authentication and safety、requests and outputs 四篇渐进式 reference；本地脚本仍只通过完整 Skill ZIP 提供。",
        "security": [
          {
            "ExternalApiKey": []
          }
        ],
        "x-mcp-excluded": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "MCP JSON-RPC 响应",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "202": {
            "description": "MCP notification 已接受"
          },
          "401": {
            "description": "缺少、格式错误或无法验证 Bearer API Key。返回 WWW-Authenticate 以及机器可读的 MCP 鉴权引导，说明 Header 格式、开发者 API Key 创建位置、凭据安全要求和公开 discovery/Skill/OpenAPI 地址；不暴露 tools、resources、owner 或 Key 是否存在。",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer 鉴权挑战。",
                "schema": {
                  "type": "string",
                  "const": "Bearer realm=\"genarrative-external-editor\""
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpAuthenticationGuideResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/external/v1/assets/direct-upload-tickets": {
      "post": {
        "tags": ["Asset Objects"],
        "operationId": "createExternalDirectUploadTicket",
        "summary": "创建素材直传 OSS 凭证",
        "description": "为外部编辑器素材上传创建一次性 OSS 表单直传参数。上传完成后应调用 objects/confirm 确认 asset object，再创建素材记录。",
        "security": [
          {
            "ExternalApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateDirectUploadTicketRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "直传凭证",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateDirectUploadTicketResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/external/v1/assets/objects/confirm": {
      "post": {
        "tags": ["Asset Objects"],
        "operationId": "confirmExternalAssetObject",
        "summary": "确认素材对象",
        "description": "确认已上传的 OSS 对象并写入 asset_object；ownerUserId 固定使用 API Key 所属账号，请求体中的 ownerUserId 会被忽略。",
        "security": [
          {
            "ExternalApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConfirmAssetObjectRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "素材对象记录",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConfirmAssetObjectResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/external/v1/assets/read-url": {
      "get": {
        "tags": ["Asset Objects"],
        "operationId": "getExternalAssetReadUrl",
        "summary": "获取私有素材读取签名 URL",
        "security": [
          {
            "ExternalApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "objectKey",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "legacyPublicPath",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "expireSeconds",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "签名读取 URL",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetAssetReadUrlResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/external/v1/editor/projects": {
      "get": {
        "tags": ["Editor Projects"],
        "operationId": "listEditorProjects",
        "summary": "列出当前账号图片画布项目",
        "security": [
          {
            "ExternalApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "view",
            "in": "query",
            "required": false,
            "description": "返回视图。full 返回完整项目、画布、图层与资源；summary 只返回项目选择所需元数据和封面稳定引用。MCP 的 list_editor_projects 工具固定使用 summary。",
            "schema": {
              "type": "string",
              "enum": ["full", "summary"],
              "default": "full"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "项目列表。view=full 返回完整项目列表；view=summary 返回紧凑项目摘要列表。",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/ExternalEditorProjectListResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ExternalEditorProjectSummaryListResponse"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "post": {
        "tags": ["Editor Projects"],
        "operationId": "createEditorProject",
        "summary": "创建图片画布项目",
        "security": [
          {
            "ExternalApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotentCreateKey"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExternalEditorProjectCreateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "已创建项目",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalEditorProjectResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/IdempotentCreateConflict"
          }
        }
      }
    },
    "/api/external/v1/editor/projects/recent": {
      "get": {
        "tags": ["Editor Projects"],
        "operationId": "loadRecentEditorProject",
        "summary": "读取当前账号最近图片画布项目",
        "security": [
          {
            "ExternalApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "最近项目；当前账号没有项目时 project 为 null",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalEditorProjectRecentResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/external/v1/editor/projects/{projectId}": {
      "get": {
        "tags": ["Editor Projects"],
        "operationId": "getEditorProject",
        "summary": "读取图片画布项目",
        "security": [
          {
            "ExternalApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ProjectId"
          }
        ],
        "responses": {
          "200": {
            "description": "项目快照",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalEditorProjectResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "tags": ["Editor Projects"],
        "operationId": "deleteEditorProject",
        "summary": "删除图片画布项目",
        "description": "删除项目时级联清理默认画布与项目资源元数据。",
        "security": [
          {
            "ExternalApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ProjectId"
          }
        ],
        "responses": {
          "200": {
            "description": "已删除项目",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalEditorProjectDeleteResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/external/v1/editor/projects/{projectId}/metadata": {
      "patch": {
        "tags": ["Editor Projects"],
        "operationId": "renameEditorProject",
        "summary": "更新图片画布项目标题",
        "security": [
          {
            "ExternalApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ProjectId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExternalEditorProjectRenameRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "更新后的项目快照",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalEditorProjectResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/external/v1/editor/projects/{projectId}/canvas": {
      "patch": {
        "tags": ["Editor Canvas"],
        "operationId": "saveEditorProjectCanvas",
        "summary": "保存默认画布布局",
        "security": [
          {
            "ExternalApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ProjectId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExternalEditorCanvasSaveRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "保存后的项目快照",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalEditorProjectResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/api/external/v1/editor/projects/{projectId}/resources": {
      "post": {
        "tags": ["Editor Assets"],
        "operationId": "createEditorProjectResource",
        "summary": "创建项目画布资源记录",
        "description": "把上传、生成或外部已有图片资源写入指定项目的画布资源表，供画布图层引用。",
        "security": [
          {
            "ExternalApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ProjectId"
          },
          {
            "$ref": "#/components/parameters/IdempotentCreateKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExternalEditorProjectResourceCreateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "已创建项目画布资源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalEditorProjectResourceResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/IdempotentCreateConflict"
          }
        }
      }
    },
    "/api/external/v1/editor/assets/library": {
      "get": {
        "tags": ["Editor Assets"],
        "operationId": "getEditorAssetLibrary",
        "summary": "读取当前账号编辑器素材库",
        "security": [
          {
            "ExternalApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "素材库快照",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalEditorAssetLibraryResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/external/v1/editor/assets/folders": {
      "post": {
        "tags": ["Editor Assets"],
        "operationId": "createEditorAssetFolder",
        "summary": "创建素材文件夹",
        "security": [
          {
            "ExternalApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotentCreateKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExternalEditorAssetFolderCreateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "已创建素材文件夹",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalEditorAssetFolderResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/IdempotentCreateConflict"
          }
        }
      }
    },
    "/api/external/v1/editor/assets/folders/{folderId}": {
      "patch": {
        "tags": ["Editor Assets"],
        "operationId": "updateEditorAssetFolder",
        "summary": "更新素材文件夹",
        "security": [
          {
            "ExternalApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/FolderId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExternalEditorAssetFolderUpdateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "已更新素材文件夹",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalEditorAssetFolderResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "tags": ["Editor Assets"],
        "operationId": "deleteEditorAssetFolder",
        "summary": "删除素材文件夹",
        "security": [
          {
            "ExternalApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/FolderId"
          }
        ],
        "responses": {
          "200": {
            "description": "删除后的素材库快照",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalEditorAssetFolderDeleteResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/external/v1/editor/assets": {
      "post": {
        "tags": ["Editor Assets"],
        "operationId": "createEditorAsset",
        "summary": "创建素材记录",
        "description": "创建账号级编辑器素材记录。图片二进制上传仍应先通过已有资产上传链路完成，随后在这里保存素材元数据。",
        "security": [
          {
            "ExternalApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExternalEditorAssetCreateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "已创建素材",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalEditorAssetResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/external/v1/editor/assets/{assetId}": {
      "patch": {
        "tags": ["Editor Assets"],
        "operationId": "updateEditorAsset",
        "summary": "更新素材名称或所在文件夹",
        "security": [
          {
            "ExternalApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AssetId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExternalEditorAssetUpdateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "已更新素材",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalEditorAssetResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "tags": ["Editor Assets"],
        "operationId": "deleteEditorAsset",
        "summary": "删除素材记录",
        "security": [
          {
            "ExternalApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AssetId"
          }
        ],
        "responses": {
          "200": {
            "description": "已删除素材",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalEditorAssetResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/external/v1/editor/images/generations": {
      "post": {
        "tags": ["Editor Images"],
        "operationId": "generateExternalEditorImage",
        "summary": "生成编辑器图片素材",
        "security": [
          {
            "ExternalApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EditorImageGenerationRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "生成任务已持久化入队",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalEditorGenerationSubmissionResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamError"
          }
        },
        "description": "支持普通生图、规范图、角色图、快速编辑参考图、UI 设计图和宣发素材生成。kind 可取 spec、character、quick-edit、ui-design、publication-material。"
      }
    },
    "/api/external/v1/editor/images/edits": {
      "post": {
        "tags": ["Editor Images"],
        "operationId": "editExternalEditorImage",
        "summary": "重绘/调整编辑器图片素材",
        "description": "主来源只接受当前账号已登记的项目资源 ID 或素材 ID（sourceReferenceId）；objectKey、URL、Data URL 与 Blob URL 即使归属当前账号也返回 400。服务端从命中的业务记录派生 canonical objectKey、assetObjectId 与权威类型；快速编辑的完整有效类型白名单为普通静态图片（类型为 null）、spec、character、icon-spritesheet、icon-spec、publication-material、ui-design 和 scene，其他及未知类型返回 400。提供 targetLayerId 时必须同时提供 projectId，目标图层必须关联有效项目资源；双方都有 assetObjectId 时必须相同，否则回退比较 canonical bucket/objectKey。同一对象的来源默认类型与目标资源默认类型冲突、目标有效类型或媒体类型不允许、来源或目标不存在/越权/缺少对象时均返回 400，任务不会入队。referenceImageSrcs 仍只作为辅助参考图。",
        "x-genarrative-allowed-effective-asset-kinds": [
          null,
          "spec",
          "character",
          "icon-spritesheet",
          "icon-spec",
          "publication-material",
          "ui-design",
          "scene"
        ],
        "security": [
          {
            "ExternalApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EditorImageEditRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "生成任务已持久化入队",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalEditorGenerationSubmissionResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamError"
          }
        }
      }
    },
    "/api/external/v1/editor/images/background-removals": {
      "post": {
        "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，且来源与目标必须指向同一权威对象。",
        "security": [
          {
            "ExternalApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EditorBackgroundRemovalRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "去背景任务已持久化入队",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalEditorGenerationSubmissionResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamError"
          }
        }
      }
    },
    "/api/external/v1/editor/icon-spritesheets/generations": {
      "post": {
        "tags": ["Editor Images"],
        "operationId": "generateExternalEditorIconSpritesheet",
        "summary": "按规范图生成图标 spritesheet 并尝试拆分",
        "security": [
          {
            "ExternalApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EditorIconSpritesheetGenerationRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "生成任务已持久化入队",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalEditorGenerationSubmissionResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamError"
          }
        }
      }
    },
    "/api/external/v1/editor/ui-designs/assets/extractions": {
      "post": {
        "tags": ["Editor Images"],
        "operationId": "extractExternalEditorUiDesignAssets",
        "summary": "从 UI 设计图生成素材 spritesheet 并尝试拆分",
        "security": [
          {
            "ExternalApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EditorUiDesignAssetExtractionRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "生成任务已持久化入队",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalEditorGenerationSubmissionResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamError"
          }
        }
      }
    },
    "/api/external/v1/editor/character-animations/generations": {
      "post": {
        "tags": ["Editor Videos"],
        "operationId": "generateExternalEditorCharacterAnimation",
        "summary": "生成编辑器角色动画帧",
        "security": [
          {
            "ExternalApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EditorCharacterAnimationGenerationRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "生成任务已持久化入队",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalEditorGenerationSubmissionResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamError"
          }
        }
      }
    },
    "/api/external/v1/editor/videos/generations": {
      "post": {
        "tags": ["Editor Videos"],
        "operationId": "generateExternalEditorVideo",
        "summary": "生成编辑器视频素材",
        "security": [
          {
            "ExternalApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EditorVideoGenerationRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "生成任务已持久化入队",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalEditorGenerationSubmissionResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamError"
          }
        }
      }
    },
    "/api/external/v1/editor/audios/sound-effects/generations": {
      "post": {
        "tags": ["Editor Audio"],
        "operationId": "generateExternalEditorSoundEffect",
        "summary": "生成编辑器音效素材",
        "security": [
          {
            "ExternalApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EditorSoundEffectGenerationRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "生成任务已持久化入队",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalEditorGenerationSubmissionResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamError"
          }
        }
      }
    },
    "/api/external/v1/editor/audios/background-music/generations": {
      "post": {
        "tags": ["Editor Audio"],
        "operationId": "generateExternalEditorBackgroundMusic",
        "summary": "生成编辑器背景音乐素材",
        "security": [
          {
            "ExternalApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EditorBackgroundMusicGenerationRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "生成任务已持久化入队",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalEditorGenerationSubmissionResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamError"
          }
        }
      }
    },
    "/api/external/v1/generations/{operationId}": {
      "get": {
        "tags": ["Editor Generations"],
        "operationId": "getExternalEditorGenerationJob",
        "summary": "查询异步生成任务",
        "description": "queued/running 时返回进度，completed 时返回 compact 稳定结果引用，failed 时返回脱敏错误。跨账号任务按不存在处理。",
        "security": [
          {
            "ExternalApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "operationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "生成任务状态及可选结果",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalEditorGenerationJobResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ExternalApiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "tnr_sk"
      }
    },
    "parameters": {
      "ProjectId": {
        "name": "projectId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "FolderId": {
        "name": "folderId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "AssetId": {
        "name": "assetId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "description": "本次逻辑生成请求的稳定幂等键；网络结果不确定时必须复用原值，不得换键重提。",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[!-~]+$"
        }
      },
      "IdempotentCreateKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "description": "可选的稳定创建幂等键。同一账号、接口与键使用相同规范化请求体重试时返回首次结果的当前记录，即使该记录后来已被修改；同键不同请求体返回 409。首次结果已删除时，同键重放同样返回 409 且不会重新创建。网络结果不确定时必须复用原值。",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[!-~]+$"
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "请求参数不合法",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "未授权访问",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Forbidden": {
        "description": "禁止访问",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "NotFound": {
        "description": "资源不存在",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Conflict": {
        "description": "画布 revision 冲突，需重新读取最新快照后合并或重试",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "IdempotentCreateConflict": {
        "description": "稳定创建幂等冲突：同一 Idempotency-Key 携带不同规范化请求体，或首次创建结果已删除 / 缺少耐久回执；服务端不会重新创建或重复首次副作用",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "UpstreamError": {
        "description": "上游生成服务失败",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "schemas": {
      "ExternalEditorProjectCreateRequest": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "maxLength": 80
          }
        },
        "additionalProperties": false
      },
      "CreateDirectUploadTicketRequest": {
        "type": "object",
        "required": ["legacyPrefix", "fileName"],
        "properties": {
          "legacyPrefix": {
            "type": "string",
            "description": "历史资源前缀，例如 generated-character-drafts。"
          },
          "pathSegments": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "fileName": {
            "type": "string"
          },
          "contentType": {
            "type": ["string", "null"]
          },
          "access": {
            "type": ["string", "null"],
            "enum": ["public", "private", null],
            "default": "private"
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "maxSizeBytes": {
            "type": ["integer", "null"],
            "minimum": 1
          },
          "expireSeconds": {
            "type": ["integer", "null"],
            "minimum": 1
          },
          "successActionStatus": {
            "type": ["integer", "null"],
            "enum": [200, 201, 204, null]
          }
        },
        "additionalProperties": false
      },
      "CreateDirectUploadTicketResponse": {
        "type": "object",
        "required": ["upload"],
        "properties": {
          "upload": {
            "$ref": "#/components/schemas/DirectUploadTicket"
          }
        }
      },
      "DirectUploadTicket": {
        "type": "object",
        "required": [
          "signatureVersion",
          "provider",
          "bucket",
          "endpoint",
          "host",
          "objectKey",
          "legacyPublicPath",
          "access",
          "keyPrefix",
          "expiresAt",
          "maxSizeBytes",
          "successActionStatus",
          "formFields"
        ],
        "properties": {
          "signatureVersion": {
            "type": "string"
          },
          "provider": {
            "type": "string"
          },
          "bucket": {
            "type": "string"
          },
          "endpoint": {
            "type": "string"
          },
          "host": {
            "type": "string"
          },
          "objectKey": {
            "type": "string"
          },
          "legacyPublicPath": {
            "type": "string"
          },
          "contentType": {
            "type": ["string", "null"]
          },
          "access": {
            "type": "string",
            "enum": ["public", "private"]
          },
          "keyPrefix": {
            "type": "string"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "maxSizeBytes": {
            "type": "integer",
            "minimum": 1
          },
          "successActionStatus": {
            "type": "integer"
          },
          "formFields": {
            "type": "object",
            "additionalProperties": {
              "type": ["string", "null"]
            }
          }
        }
      },
      "ConfirmAssetObjectRequest": {
        "type": "object",
        "required": ["objectKey", "assetKind"],
        "properties": {
          "bucket": {
            "type": ["string", "null"]
          },
          "objectKey": {
            "type": "string"
          },
          "contentType": {
            "type": ["string", "null"]
          },
          "contentLength": {
            "type": ["integer", "null"],
            "minimum": 0
          },
          "contentHash": {
            "type": ["string", "null"]
          },
          "assetKind": {
            "type": "string"
          },
          "accessPolicy": {
            "type": ["string", "null"],
            "enum": ["private", "public_read", null],
            "default": "private"
          },
          "sourceJobId": {
            "type": ["string", "null"]
          },
          "ownerUserId": {
            "type": ["string", "null"],
            "deprecated": true,
            "description": "外部接口会忽略该字段并使用 API Key 所属账号。"
          },
          "profileId": {
            "type": ["string", "null"]
          },
          "entityId": {
            "type": ["string", "null"]
          }
        },
        "additionalProperties": false
      },
      "ConfirmAssetObjectResponse": {
        "type": "object",
        "required": ["assetObject"],
        "properties": {
          "assetObject": {
            "$ref": "#/components/schemas/AssetObject"
          }
        }
      },
      "AssetObject": {
        "type": "object",
        "required": [
          "assetObjectId",
          "bucket",
          "objectKey",
          "accessPolicy",
          "contentLength",
          "version",
          "assetKind",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "assetObjectId": {
            "type": "string"
          },
          "bucket": {
            "type": "string"
          },
          "objectKey": {
            "type": "string"
          },
          "accessPolicy": {
            "type": "string"
          },
          "contentType": {
            "type": ["string", "null"]
          },
          "contentLength": {
            "type": "integer",
            "minimum": 0
          },
          "contentHash": {
            "type": ["string", "null"]
          },
          "version": {
            "type": "integer",
            "minimum": 1
          },
          "sourceJobId": {
            "type": ["string", "null"]
          },
          "ownerUserId": {
            "type": ["string", "null"]
          },
          "profileId": {
            "type": ["string", "null"]
          },
          "entityId": {
            "type": ["string", "null"]
          },
          "assetKind": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "GetAssetReadUrlResponse": {
        "type": "object",
        "required": ["read"],
        "properties": {
          "read": {
            "$ref": "#/components/schemas/AssetReadUrl"
          }
        }
      },
      "AssetReadUrl": {
        "type": "object",
        "required": [
          "provider",
          "bucket",
          "endpoint",
          "host",
          "objectKey",
          "expiresAt",
          "signedUrl"
        ],
        "properties": {
          "provider": {
            "type": "string"
          },
          "bucket": {
            "type": "string"
          },
          "endpoint": {
            "type": "string"
          },
          "host": {
            "type": "string"
          },
          "objectKey": {
            "type": "string"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "signedUrl": {
            "type": "string"
          }
        }
      },
      "ExternalEditorProjectRenameRequest": {
        "type": "object",
        "required": ["title"],
        "properties": {
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          }
        },
        "additionalProperties": false
      },
      "ExternalEditorCanvasSaveRequest": {
        "type": "object",
        "required": ["viewport", "layers", "expectedRevision"],
        "properties": {
          "viewport": {
            "$ref": "#/components/schemas/EditorCanvasViewport"
          },
          "layers": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            },
            "description": "兼容画布布局 JSON，最大 2 MiB；服务端会拆分为结构化图层与生成对话框行。"
          },
          "expectedRevision": {
            "type": "integer",
            "minimum": 0,
            "description": "必填的画布 revision CAS；不匹配时返回 409。"
          }
        },
        "additionalProperties": false
      },
      "ExternalEditorAssetFolderCreateRequest": {
        "type": "object",
        "required": ["label"],
        "properties": {
          "label": {
            "type": "string"
          },
          "sortOrder": {
            "type": "integer",
            "minimum": 0,
            "default": 100
          }
        },
        "additionalProperties": false
      },
      "ExternalEditorAssetFolderUpdateRequest": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string"
          },
          "collapsed": {
            "type": "boolean"
          }
        },
        "additionalProperties": false
      },
      "ExternalEditorAssetCreateRequest": {
        "type": "object",
        "allOf": [
          {
            "if": {
              "properties": {
                "assetKind": {
                  "const": "character-animation"
                }
              },
              "required": ["assetKind"]
            },
            "then": {
              "required": ["imageSequenceFrames", "imageSequenceDurationMs"],
              "properties": {
                "generationInputs": {
                  "$ref": "#/components/schemas/ExternalCharacterAnimationGenerationInputs"
                }
              }
            },
            "else": {
              "not": {
                "anyOf": [
                  {
                    "required": ["imageSequenceFrames"]
                  },
                  {
                    "required": ["imageSequenceDurationMs"]
                  }
                ]
              }
            }
          }
        ],
        "required": [
          "folderId",
          "label",
          "imageSrc",
          "width",
          "height",
          "sourceType"
        ],
        "properties": {
          "folderId": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "imageSrc": {
            "type": "string"
          },
          "thumbnailSrc": {
            "type": ["string", "null"]
          },
          "objectKey": {
            "type": ["string", "null"]
          },
          "assetObjectId": {
            "type": ["string", "null"]
          },
          "width": {
            "type": "integer",
            "minimum": 1
          },
          "height": {
            "type": "integer",
            "minimum": 1
          },
          "sourceType": {
            "type": "string"
          },
          "prompt": {
            "type": ["string", "null"]
          },
          "actualPrompt": {
            "type": ["string", "null"]
          },
          "model": {
            "type": ["string", "null"]
          },
          "provider": {
            "type": ["string", "null"]
          },
          "taskId": {
            "type": ["string", "null"]
          },
          "assetKind": {
            "type": ["string", "null"],
            "description": "权威媒体类别。character-animation 渲染为序列帧，video 渲染为视频，audio/sound-effect/background-music 渲染为音频，其余渲染为图片。"
          },
          "imageSequenceFrames": {
            "type": "array",
            "minItems": 2,
            "items": {
              "$ref": "#/components/schemas/EditorImageSequenceFrame"
            }
          },
          "imageSequenceDurationMs": {
            "type": "integer",
            "minimum": 1,
            "description": "assetKind=character-animation 时完整图片序列播放一次的毫秒时长；与音频、视频生成参数 durationSeconds 无关。"
          },
          "generationInputs": {
            "$ref": "#/components/schemas/JsonValue",
            "description": "可重放的生成输入。assetKind=character-animation 时不得包含 characterAnimation、frames、previewVideoPath、frameCount、fps 或 durationSeconds 等旧运行字段；正式媒体数据必须写入 imageSequenceFrames 和 imageSequenceDurationMs。服务端会移除 screenColorHex、mattingProvider、mattingModel 等内部处理审计字段。"
          }
        },
        "additionalProperties": false
      },
      "ExternalEditorProjectResourceCreateRequest": {
        "type": "object",
        "allOf": [
          {
            "if": {
              "properties": {
                "assetKind": {
                  "const": "character-animation"
                }
              },
              "required": ["assetKind"]
            },
            "then": {
              "required": ["imageSequenceFrames", "imageSequenceDurationMs"],
              "properties": {
                "generationInputs": {
                  "$ref": "#/components/schemas/ExternalCharacterAnimationGenerationInputs"
                }
              }
            },
            "else": {
              "not": {
                "anyOf": [
                  {
                    "required": ["imageSequenceFrames"]
                  },
                  {
                    "required": ["imageSequenceDurationMs"]
                  }
                ]
              }
            }
          }
        ],
        "required": ["imageSrc", "width", "height", "sourceType"],
        "properties": {
          "imageSrc": {
            "type": "string"
          },
          "objectKey": {
            "type": ["string", "null"]
          },
          "assetObjectId": {
            "type": ["string", "null"]
          },
          "width": {
            "type": "integer",
            "minimum": 1
          },
          "height": {
            "type": "integer",
            "minimum": 1
          },
          "sourceType": {
            "type": "string"
          },
          "prompt": {
            "type": ["string", "null"]
          },
          "actualPrompt": {
            "type": ["string", "null"]
          },
          "model": {
            "type": ["string", "null"]
          },
          "provider": {
            "type": ["string", "null"]
          },
          "taskId": {
            "type": ["string", "null"]
          },
          "sourceResourceId": {
            "type": ["string", "null"],
            "description": "可选的来源项目资源 ID，用于在同一 objectKey 被多个资源以不同权威元数据登记时消歧。sourceImageSrc 已是项目资源 ID 或素材 ID 时按该显式 ID 定点解析；纯 objectKey 无法唯一确定权威来源时必须提供本字段，否则返回 400。原位替换使用纯 objectKey 且省略本字段时，服务端自动绑定 targetLayerId 对应的当前项目资源，并把该绑定写入队列供 Worker 复验。"
          },
          "assetKind": {
            "type": ["string", "null"],
            "description": "权威媒体类别。character-animation 渲染为序列帧，video 渲染为视频，audio/sound-effect/background-music 渲染为音频，其余渲染为图片。"
          },
          "imageSequenceFrames": {
            "type": "array",
            "minItems": 2,
            "items": {
              "$ref": "#/components/schemas/EditorImageSequenceFrame"
            }
          },
          "imageSequenceDurationMs": {
            "type": "integer",
            "minimum": 1,
            "description": "assetKind=character-animation 时完整图片序列播放一次的毫秒时长；与音频、视频生成参数 durationSeconds 无关。"
          },
          "generationInputs": {
            "$ref": "#/components/schemas/JsonValue",
            "description": "可重放的生成输入。assetKind=character-animation 时不得包含 characterAnimation、frames、previewVideoPath、frameCount、fps 或 durationSeconds 等旧运行字段；正式媒体数据必须写入 imageSequenceFrames 和 imageSequenceDurationMs。服务端会移除 screenColorHex、mattingProvider、mattingModel 等内部处理审计字段。"
          }
        },
        "additionalProperties": false
      },
      "ExternalCharacterAnimationGenerationInputs": {
        "not": {
          "anyOf": [
            {
              "type": "object",
              "required": ["characterAnimation"]
            },
            {
              "type": "object",
              "required": ["frames"]
            },
            {
              "type": "object",
              "required": ["previewVideoPath"]
            },
            {
              "type": "object",
              "required": ["frameCount"]
            },
            {
              "type": "object",
              "required": ["fps"]
            },
            {
              "type": "object",
              "required": ["durationSeconds"]
            }
          ]
        },
        "description": "assetKind=character-animation 时 generationInputs 不得包含旧运行字段；正式媒体数据使用 imageSequenceFrames 和 imageSequenceDurationMs。"
      },
      "ExternalEditorAssetUpdateRequest": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string"
          },
          "folderId": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "ExternalEditorProjectResponse": {
        "type": "object",
        "required": ["project"],
        "properties": {
          "project": {
            "$ref": "#/components/schemas/EditorProject"
          }
        }
      },
      "ExternalEditorProjectRecentResponse": {
        "type": "object",
        "required": ["project"],
        "properties": {
          "project": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EditorProject"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "ExternalEditorProjectListResponse": {
        "type": "object",
        "required": ["projects"],
        "properties": {
          "projects": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EditorProject"
            }
          }
        }
      },
      "ExternalEditorProjectSummaryListResponse": {
        "type": "object",
        "required": ["projects"],
        "properties": {
          "projects": {
            "type": "array",
            "description": "用于展示、查找、同名确认和安全选择目标的紧凑项目摘要；不包含 canvas、viewport、layers 或 resources。",
            "items": {
              "$ref": "#/components/schemas/EditorProjectSummary"
            }
          }
        },
        "additionalProperties": false
      },
      "EditorProjectSummary": {
        "type": "object",
        "required": ["projectId", "title", "updatedAt", "cover"],
        "properties": {
          "projectId": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "cover": {
            "description": "项目最新封面快照的稳定引用；项目没有封面时为 null。需要展示时使用 objectKey 调用 /assets/read-url 获取临时签名 URL。",
            "anyOf": [
              {
                "$ref": "#/components/schemas/EditorProjectSummaryCover"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "additionalProperties": false
      },
      "EditorProjectSummaryCover": {
        "type": "object",
        "required": ["resourceId", "objectKey", "width", "height", "updatedAt"],
        "properties": {
          "resourceId": {
            "type": "string"
          },
          "objectKey": {
            "type": "string",
            "description": "封面对象的稳定引用，不是图片正文、Data URL 或临时签名 URL。"
          },
          "width": {
            "type": "integer",
            "minimum": 1
          },
          "height": {
            "type": "integer",
            "minimum": 1
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "ExternalEditorProjectDeleteResponse": {
        "type": "object",
        "required": ["deletedProjectId"],
        "properties": {
          "deletedProjectId": {
            "type": "string"
          }
        }
      },
      "ExternalEditorAssetLibraryResponse": {
        "type": "object",
        "required": ["library"],
        "properties": {
          "library": {
            "$ref": "#/components/schemas/EditorAssetLibrary"
          }
        }
      },
      "ExternalEditorAssetFolderResponse": {
        "type": "object",
        "required": ["folder"],
        "properties": {
          "folder": {
            "$ref": "#/components/schemas/EditorAssetFolder"
          }
        }
      },
      "ExternalEditorAssetFolderDeleteResponse": {
        "type": "object",
        "required": ["library"],
        "properties": {
          "library": {
            "$ref": "#/components/schemas/EditorAssetLibrary"
          }
        }
      },
      "ExternalEditorAssetResponse": {
        "type": "object",
        "required": ["asset"],
        "properties": {
          "asset": {
            "$ref": "#/components/schemas/EditorAsset"
          }
        }
      },
      "ExternalEditorProjectResourceResponse": {
        "type": "object",
        "required": ["resource"],
        "properties": {
          "resource": {
            "$ref": "#/components/schemas/EditorProjectResource"
          }
        }
      },
      "EditorProject": {
        "type": "object",
        "required": [
          "projectId",
          "title",
          "canvas",
          "viewport",
          "layers",
          "resources",
          "updatedAt"
        ],
        "properties": {
          "projectId": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "canvas": {
            "$ref": "#/components/schemas/EditorCanvas"
          },
          "viewport": {
            "$ref": "#/components/schemas/EditorCanvasViewport"
          },
          "layers": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "resources": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EditorProjectResource"
            }
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "EditorCanvas": {
        "type": "object",
        "required": [
          "canvasId",
          "projectId",
          "title",
          "viewport",
          "layers",
          "revision",
          "layoutStorageVersion",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "canvasId": {
            "type": "string"
          },
          "projectId": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "viewport": {
            "$ref": "#/components/schemas/EditorCanvasViewport"
          },
          "layers": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "revision": {
            "type": "integer",
            "minimum": 0
          },
          "layoutStorageVersion": {
            "type": "integer",
            "minimum": 0
          },
          "backgroundColor": {
            "type": ["string", "null"]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "EditorCanvasViewport": {
        "type": "object",
        "required": ["x", "y", "scale"],
        "properties": {
          "x": {
            "type": "number"
          },
          "y": {
            "type": "number"
          },
          "scale": {
            "type": "number",
            "minimum": 0.01,
            "maximum": 8
          }
        },
        "additionalProperties": false
      },
      "EditorProjectResource": {
        "type": "object",
        "required": [
          "resourceId",
          "projectId",
          "imageSrc",
          "width",
          "height",
          "sourceType",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "resourceId": {
            "type": "string"
          },
          "projectId": {
            "type": "string"
          },
          "imageSrc": {
            "type": "string"
          },
          "objectKey": {
            "type": ["string", "null"]
          },
          "assetObjectId": {
            "type": ["string", "null"]
          },
          "width": {
            "type": "integer",
            "minimum": 1
          },
          "height": {
            "type": "integer",
            "minimum": 1
          },
          "sourceType": {
            "type": "string"
          },
          "prompt": {
            "type": ["string", "null"]
          },
          "actualPrompt": {
            "type": ["string", "null"]
          },
          "model": {
            "type": ["string", "null"]
          },
          "taskId": {
            "type": ["string", "null"]
          },
          "sourceResourceId": {
            "type": ["string", "null"]
          },
          "assetKind": {
            "type": ["string", "null"],
            "description": "权威媒体类别。character-animation 渲染为序列帧，video 渲染为视频，audio/sound-effect/background-music 渲染为音频，其余渲染为图片。"
          },
          "imageSequenceFrames": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EditorImageSequenceFrame"
            }
          },
          "imageSequenceDurationMs": {
            "type": "integer",
            "minimum": 1,
            "description": "assetKind=character-animation 时完整图片序列播放一次的毫秒时长；与音频、视频生成参数 durationSeconds 无关。"
          },
          "generationInputs": {
            "$ref": "#/components/schemas/JsonValue"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "ownerUserId": {
            "type": ["string", "null"]
          },
          "authorDisplayName": {
            "type": ["string", "null"]
          },
          "authorPublicUserCode": {
            "type": ["string", "null"]
          },
          "publicShowcaseEnabled": {
            "type": "boolean"
          }
        }
      },
      "EditorAssetLibrary": {
        "type": "object",
        "required": ["folders", "assets"],
        "properties": {
          "folders": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EditorAssetFolder"
            }
          },
          "assets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EditorAsset"
            }
          }
        }
      },
      "EditorAssetFolder": {
        "type": "object",
        "required": [
          "folderId",
          "label",
          "sortOrder",
          "collapsed",
          "systemDefault",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "folderId": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "sortOrder": {
            "type": "integer"
          },
          "collapsed": {
            "type": "boolean"
          },
          "systemDefault": {
            "type": "boolean"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "EditorAsset": {
        "type": "object",
        "required": [
          "assetId",
          "folderId",
          "label",
          "imageSrc",
          "width",
          "height",
          "sourceType",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "assetId": {
            "type": "string"
          },
          "folderId": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "imageSrc": {
            "type": "string"
          },
          "objectKey": {
            "type": ["string", "null"]
          },
          "assetObjectId": {
            "type": ["string", "null"]
          },
          "width": {
            "type": "integer",
            "minimum": 1
          },
          "height": {
            "type": "integer",
            "minimum": 1
          },
          "sourceType": {
            "type": "string"
          },
          "imageSequenceFrames": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EditorImageSequenceFrame"
            },
            "description": "assetKind=character-animation 时的完整可播放帧集合。"
          },
          "imageSequenceDurationMs": {
            "type": "integer",
            "minimum": 1,
            "description": "assetKind=character-animation 时完整图片序列播放一次的毫秒时长；与音频、视频生成参数 durationSeconds 无关。"
          },
          "prompt": {
            "type": ["string", "null"]
          },
          "actualPrompt": {
            "type": ["string", "null"]
          },
          "model": {
            "type": ["string", "null"]
          },
          "taskId": {
            "type": ["string", "null"]
          },
          "assetKind": {
            "type": ["string", "null"],
            "description": "权威媒体类别。character-animation 渲染为序列帧，video 渲染为视频，audio/sound-effect/background-music 渲染为音频，其余渲染为图片。"
          },
          "generationInputs": {
            "$ref": "#/components/schemas/JsonValue"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "thumbnailSrc": {
            "type": ["string", "null"]
          },
          "sourceResourceId": {
            "type": ["string", "null"]
          },
          "publicShowcaseEnabled": {
            "type": ["boolean", "null"]
          }
        }
      },
      "JsonValue": {
        "description": "任意 JSON 值。"
      },
      "McpAuthenticationGuideResponse": {
        "type": "object",
        "required": ["error", "meta"],
        "additionalProperties": false,
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message", "details"],
            "additionalProperties": false,
            "properties": {
              "code": {
                "const": "UNAUTHORIZED"
              },
              "message": {
                "const": "连接陶泥儿托管 MCP 需要开发者 API Key"
              },
              "details": {
                "type": "object",
                "required": ["guide"],
                "additionalProperties": false,
                "properties": {
                  "guide": {
                    "type": "object",
                    "required": [
                      "reason",
                      "action",
                      "authentication",
                      "keyManagement",
                      "retry",
                      "steps",
                      "credentialSafety",
                      "publicDiscovery"
                    ],
                    "additionalProperties": false,
                    "properties": {
                      "reason": {
                        "const": "MCP_AUTHENTICATION_REQUIRED"
                      },
                      "action": {
                        "const": "CONFIGURE_BEARER_API_KEY"
                      },
                      "authentication": {
                        "type": "object",
                        "required": ["scheme", "header", "valueFormat"],
                        "additionalProperties": false,
                        "properties": {
                          "scheme": {
                            "const": "Bearer"
                          },
                          "header": {
                            "const": "Authorization"
                          },
                          "valueFormat": {
                            "const": "Bearer <tnr_sk_...>"
                          }
                        }
                      },
                      "keyManagement": {
                        "type": "object",
                        "required": ["navigationLabel", "rawKeyShownOnce"],
                        "additionalProperties": false,
                        "properties": {
                          "navigationLabel": {
                            "const": "开发者 API Key"
                          },
                          "rawKeyShownOnce": {
                            "const": true
                          }
                        }
                      },
                      "retry": {
                        "type": "object",
                        "required": ["method", "path", "rpcMethod"],
                        "additionalProperties": false,
                        "properties": {
                          "method": {
                            "const": "POST"
                          },
                          "path": {
                            "const": "/api/external/v1/mcp"
                          },
                          "rpcMethod": {
                            "const": "initialize"
                          }
                        }
                      },
                      "steps": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "credentialSafety": {
                        "type": "object",
                        "required": [
                          "rawKeyShownOnce",
                          "neverPasteIntoChat",
                          "neverStoreInRepository"
                        ],
                        "additionalProperties": false,
                        "properties": {
                          "rawKeyShownOnce": {
                            "const": true
                          },
                          "neverPasteIntoChat": {
                            "const": true
                          },
                          "neverStoreInRepository": {
                            "const": true
                          }
                        }
                      },
                      "publicDiscovery": {
                        "type": "object",
                        "required": ["manifest", "skill", "openapi"],
                        "additionalProperties": false,
                        "properties": {
                          "manifest": {
                            "const": "/api/external/v1/agent-integration.json"
                          },
                          "skill": {
                            "const": "/api/external/v1/skill/SKILL.md"
                          },
                          "openapi": {
                            "const": "/api/external/v1/openapi.json"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "meta": {
            "type": "object",
            "required": [
              "apiVersion",
              "routeVersion",
              "latencyMs",
              "timestamp"
            ],
            "additionalProperties": false,
            "properties": {
              "apiVersion": {
                "type": "string"
              },
              "requestId": {
                "type": "string"
              },
              "routeVersion": {
                "type": "string"
              },
              "operation": {
                "type": "string"
              },
              "latencyMs": {
                "type": "integer",
                "minimum": 0
              },
              "timestamp": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "details": {
            "type": ["object", "null"]
          }
        }
      },
      "EditorImageGenerationRequest": {
        "type": "object",
        "required": ["prompt"],
        "properties": {
          "prompt": {
            "type": "string",
            "minLength": 1
          },
          "screenColor": {
            "type": ["string", "null"],
            "description": "纯色抠像背景色。可传画布支持的纯色背景 hex（如 #CFEFFF）指定；传 \"auto\"、null 或省略则由服务端自动决策。"
          },
          "style": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "examples": ["none", "pixelArt"],
            "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",
            "description": "兼容旧 size 入参；未传 aspectRatio/imageSize 时生效。",
            "enum": [
              "1024x1024",
              "1536x1024",
              "1024x1536",
              "2048x1152",
              "2048x2048",
              "2k-16:9",
              "1:1",
              "16:9",
              "9:16"
            ]
          },
          "kind": {
            "type": "string",
            "enum": [
              "spec",
              "character",
              "quick-edit",
              "ui-design",
              "publication-material"
            ],
            "description": "省略时生成普通图片；其它值选择对应的专用生成流程。External v1 当前不开放结构化游戏场景生成，scene 不能通过该通用图片接口提交。"
          },
          "model": {
            "type": "string",
            "description": "支持 gpt-image-2、gemini-3.1-flash-image-preview、nanobanana2、nano-banana。未传时沿用编辑器默认。"
          },
          "aspectRatio": {
            "type": "string",
            "enum": ["1:1", "2:3", "3:2", "9:16", "16:9"],
            "default": "1:1"
          },
          "imageSize": {
            "type": "string",
            "enum": ["0.5K", "1K", "2K"],
            "default": "1K"
          },
          "referenceImageSrcs": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "当前账号的 objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS 再提交。禁止 Data URL / Blob URL。普通生成最多 5 张；kind=quick-edit 时 gpt-image-2 最多 5 张、nanobanana2 最多 9 张。超限返回 400，不会静默截断。"
            },
            "maxItems": 9
          },
          "projectId": {
            "type": ["string", "null"]
          },
          "assetKind": {
            "anyOf": [
              {
                "type": "string",
                "not": {
                  "pattern": "^\\s*scene\\s*$"
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "生成产物分类。External v1 通用图片接口禁止使用 scene；结构化游戏场景必须使用主站场景专用契约。"
          },
          "generationInputs": {
            "$ref": "#/components/schemas/JsonValue"
          },
          "assetFolderId": {
            "type": ["string", "null"],
            "description": "传 project 时写入默认项目素材文件夹；传具体 folderId 时写入该文件夹。"
          },
          "assetLabel": {
            "type": ["string", "null"],
            "description": "写入素材库时使用的素材名称。"
          },
          "sourceResourceId": {
            "type": ["string", "null"]
          },
          "canvasCompletion": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EditorCanvasGenerationCompletion"
              },
              {
                "type": "null"
              }
            ],
            "description": "带项目上下文生成时，服务端据此直接写入画布完成态并返回最新项目快照。placeholder 只参与占位与完成落点，不约束最终媒体像素尺寸；pixelArt 规整成功时结果图层使用最终逻辑分辨率 PNG 的实际尺寸。"
          }
        },
        "additionalProperties": false
      },
      "EditorCanvasGenerationCompletion": {
        "type": "object",
        "required": ["title", "placeholder"],
        "properties": {
          "dialogId": {
            "type": "string",
            "minLength": 1
          },
          "title": {
            "type": "string"
          },
          "placeholder": {
            "$ref": "#/components/schemas/EditorCanvasGenerationPlaceholder"
          }
        },
        "additionalProperties": false
      },
      "EditorCanvasGenerationPlaceholder": {
        "type": "object",
        "required": [
          "x",
          "y",
          "width",
          "height",
          "originalWidth",
          "originalHeight"
        ],
        "properties": {
          "x": {
            "type": "number"
          },
          "y": {
            "type": "number"
          },
          "width": {
            "type": "number",
            "minimum": 1
          },
          "height": {
            "type": "number",
            "minimum": 1
          },
          "originalWidth": {
            "type": "number",
            "minimum": 1
          },
          "originalHeight": {
            "type": "number",
            "minimum": 1
          }
        },
        "additionalProperties": false
      },
      "EditorImageEditRequest": {
        "type": "object",
        "required": ["prompt", "sourceReferenceId"],
        "properties": {
          "prompt": {
            "type": "string",
            "minLength": 1
          },
          "sourceReferenceId": {
            "type": "string",
            "minLength": 1,
            "description": "待编辑主来源的业务 ID，只接受当前账号已登记的项目资源 ID 或素材 ID。objectKey、普通 URL、签名 URL、Data URL、Blob URL 和未登记上传对象均返回 400；上传对象必须先登记为项目资源或素材。服务端从命中记录派生 canonical objectKey、assetObjectId 与权威类型。"
          },
          "projectId": {
            "type": ["string", "null"],
            "description": "项目上下文。提供 targetLayerId 时必须同时提供非空 projectId，否则返回 400。"
          },
          "generationInputs": {
            "$ref": "#/components/schemas/JsonValue"
          },
          "assetFolderId": {
            "type": ["string", "null"]
          },
          "assetLabel": {
            "type": ["string", "null"]
          },
          "targetLayerId": {
            "type": ["string", "null"],
            "description": "目标画布图层。提供时必须同时提供 projectId，且图层必须关联有效项目资源。来源与目标都有 assetObjectId 时按 ID 比较；任一缺失时回退比较 canonical bucket/objectKey。来源记录默认类型必须与目标资源默认类型一致，最终类型取 assetKindOverride 或目标资源类型，且媒体类型必须为图片；违反任一条件返回 400。未提供 canvasCompletion 时，生成结果替换该图层。"
          },
          "size": {
            "type": "string"
          },
          "model": {
            "type": "string",
            "description": "支持 gpt-image-2、gemini-3.1-flash-image-preview、nanobanana2、nano-banana。"
          },
          "aspectRatio": {
            "type": "string",
            "enum": ["1:1", "4:3", "3:2", "2:3", "9:16", "16:9"]
          },
          "imageSize": {
            "type": "string",
            "enum": ["0.5K", "1K", "2K"]
          },
          "referenceImageSrcs": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "当前账号的 objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。sourceReferenceId 对应的主来源原图占用 1 张 provider 容量，因此 gpt-image-2 最多再提交 4 张、nanobanana2 最多再提交 8 张；超限返回 400，不会静默截断。"
            },
            "maxItems": 8
          },
          "canvasCompletion": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EditorCanvasGenerationCompletion"
              },
              {
                "type": "null"
              }
            ],
            "description": "带项目上下文生成时，服务端据此直接写入画布完成态并返回最新项目快照。"
          }
        },
        "additionalProperties": false
      },
      "EditorBackgroundRemovalRequest": {
        "type": "object",
        "required": ["sourceImageSrc"],
        "properties": {
          "sourceImageSrc": {
            "type": "string",
            "minLength": 1,
            "description": "当前账号拥有的稳定 objectKey、项目资源 ID 或素材 ID。禁止 Data URL、Blob URL 和临时 signed URL。"
          },
          "projectId": {
            "type": ["string", "null"],
            "description": "可选项目上下文。提供 targetLayerId 时必须同时提供非空 projectId，否则在入队前返回 400。"
          },
          "targetLayerId": {
            "type": ["string", "null"],
            "description": "提供时必须同时提供 projectId。仅在未提供 canvasCompletion 时用于原位替换既有画布图层，此时目标图层必须存在、关联当前项目静态图片资源；若图层提供 assetKindOverride，则以覆盖后的有效类型参与静态媒体门禁和来源类型比较。来源与目标必须指向同一权威对象：双方都有 assetObjectId 时按 ID 比较，任一缺失时回退 canonical bucket/objectKey；违反任一条件均在入队前返回 400。存在 canvasCompletion 时不参与原位替换。省略 targetLayerId 与 canvasCompletion 时只持久化请求指定的项目资源或素材库记录，不自动写入画布。"
          },
          "sourceResourceId": {
            "type": ["string", "null"],
            "description": "可选的来源项目资源 ID，用于在同一 objectKey 被多个资源以不同权威元数据登记时消歧。sourceImageSrc 已是项目资源 ID 或素材 ID 时按该显式 ID 定点解析；纯 objectKey 无法唯一确定权威来源时必须提供本字段，否则返回 400。原位替换使用纯 objectKey 且省略本字段时，服务端自动绑定 targetLayerId 对应的当前项目资源，并把该绑定写入队列供 Worker 复验。"
          },
          "assetKind": {
            "type": ["string", "null"],
            "description": "可选静态图片语义类型。服务端优先采用来源项目资源或素材库记录的权威语义类型；资产对象存储类型只参与非静态媒体门禁，不覆盖语义类型。请求值与权威来源类型不一致，或任一记录表示 video、audio、animation、image-sequence、sound-effect、background-music 等非静态媒体时，在入队前返回 400。",
            "x-genarrative-media-family": "static-image"
          },
          "generationInputs": {
            "$ref": "#/components/schemas/JsonValue"
          },
          "assetFolderId": {
            "type": ["string", "null"]
          },
          "assetLabel": {
            "type": ["string", "null"]
          },
          "canvasCompletion": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EditorCanvasGenerationCompletion"
              },
              {
                "type": "null"
              }
            ],
            "description": "画布生成占位完成指令。提供时优先按生成完成链路写入结果，targetLayerId 不参与原位替换。"
          }
        },
        "additionalProperties": false
      },
      "EditorImageGenerationResponse": {
        "type": "object",
        "required": [
          "imageSrc",
          "width",
          "height",
          "sourceType",
          "prompt",
          "model",
          "taskId"
        ],
        "properties": {
          "imageSrc": {
            "type": "string"
          },
          "objectKey": {
            "type": ["string", "null"]
          },
          "assetObjectId": {
            "type": ["string", "null"]
          },
          "width": {
            "type": "integer",
            "minimum": 1,
            "description": "最终持久化 PNG 的实际像素宽度；pixelArt 规整成功时为逻辑网格宽度，不保证等于 size、imageSize、provider 回图或画布 placeholder 宽度。"
          },
          "height": {
            "type": "integer",
            "minimum": 1,
            "description": "最终持久化 PNG 的实际像素高度；pixelArt 规整成功时为逻辑网格高度，不保证等于 size、imageSize、provider 回图或画布 placeholder 高度。"
          },
          "sourceType": {
            "type": "string",
            "const": "generated"
          },
          "prompt": {
            "type": "string"
          },
          "actualPrompt": {
            "type": ["string", "null"]
          },
          "model": {
            "type": "string"
          },
          "taskId": {
            "type": "string"
          },
          "resource": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EditorProjectResource"
              },
              {
                "type": "null"
              }
            ]
          },
          "asset": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EditorAsset"
              },
              {
                "type": "null"
              }
            ]
          },
          "project": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EditorProject"
              },
              {
                "type": "null"
              }
            ],
            "description": "当请求携带 canvasCompletion 且服务端成功写入画布布局时返回最新项目快照。"
          },
          "warning": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EditorGenerationWarning"
              },
              {
                "type": "null"
              }
            ],
            "description": "生成成功但后处理降级时返回的非阻断告警。"
          }
        }
      },
      "EditorIconSpritesheetGenerationRequest": {
        "type": "object",
        "required": ["referenceId", "iconDescriptions"],
        "properties": {
          "referenceId": {
            "type": "string",
            "description": "当前账号中已登记为 icon-spec 的项目资源 ID 或素材 ID。只接受 ID，不接受 objectKey、图片 URL、Data URL 或 Blob URL。"
          },
          "referenceImageSrcs": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "额外图标素材参考图的稳定引用：objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。referenceId 占用 1 张 provider 容量，因此 gpt-image-2 最多再提交 4 张、nanobanana2 最多再提交 8 张；超限返回 400，不会静默截断。"
            },
            "maxItems": 8
          },
          "iconDescriptions": {
            "type": "array",
            "description": "图标生成需求文本数组，供 prompt 组装使用；数组长度不控制自动切片数量。画布前端把完整用户提示词作为唯一数组元素提交；其它调用方可继续提交 1 到 100 条非空文本。服务端去空并以换行拼接后，单条最多 200 个 Unicode 字符，合计最多 2000 个 Unicode 字符且不超过 6144 个 UTF-8 字节；超限同步返回 400，不会入队或计费。",
            "minItems": 1,
            "maxItems": 100,
            "x-genarrative-maxTotalCharacters": 2000,
            "x-genarrative-maxTotalUtf8Bytes": 6144,
            "items": {
              "type": "string",
              "maxLength": 200
            }
          },
          "sliceLayout": {
            "type": "string",
            "enum": ["grid-2x2"],
            "description": "可选固定图集切片合同。省略时沿用全图 alpha 连通域自动拆分；传 grid-2x2 时服务端要求生成四个固定象限，并按左上、右上、左下、右下各持久化一个独立切片。该模式适用于需要恰好四类核心运行时素材的游戏，不会猜测等分裁切。"
          },
          "screenColor": {
            "type": ["string", "null"],
            "description": "纯色抠像背景色。可传画布支持的纯色背景 hex（如 #CFEFFF）指定；传 \"auto\"、null 或省略则由服务端自动决策。"
          },
          "style": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "examples": ["none", "pixelArt"],
            "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",
            "default": "gemini-3.1-flash-image-preview"
          },
          "aspectRatio": {
            "type": "string",
            "enum": ["1:1", "2:3", "3:2", "9:16", "16:9"],
            "default": "1:1"
          },
          "imageSize": {
            "type": "string",
            "enum": ["0.5K", "1K", "2K"],
            "default": "1K"
          },
          "projectId": {
            "type": ["string", "null"]
          },
          "generationInputs": {
            "$ref": "#/components/schemas/JsonValue"
          },
          "assetFolderId": {
            "type": ["string", "null"]
          },
          "assetLabel": {
            "type": ["string", "null"],
            "maxLength": 80,
            "description": "写入素材库时使用的图标图集名称；空白或省略时使用自动名称。"
          },
          "canvasCompletion": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EditorCanvasGenerationCompletion"
              },
              {
                "type": "null"
              }
            ],
            "description": "带项目上下文生成时，服务端据此直接写入画布完成态并返回最新项目快照。placeholder 只参与占位与完成落点，不约束最终媒体像素尺寸；pixelArt 规整成功时结果图层使用最终逻辑分辨率 PNG 的实际尺寸。"
          }
        },
        "additionalProperties": false
      },
      "EditorUiDesignAssetExtractionRequest": {
        "type": "object",
        "required": ["sourceImageSrc", "aspectRatio", "imageSize"],
        "properties": {
          "sourceImageSrc": {
            "type": "string",
            "description": "带红框标注的 UI 设计图稳定引用：当前账号的 objectKey、项目资源 ID 或素材 ID；浏览器内合成后必须先上传 OSS 再提交。禁止 Data URL / Blob URL。"
          },
          "screenColor": {
            "type": ["string", "null"],
            "description": "纯色抠像背景色。可传画布支持的纯色背景 hex（如 #CFEFFF）指定；传 \"auto\"、null 或省略则由服务端自动决策。"
          },
          "model": {
            "type": "string",
            "default": "gemini-3.1-flash-image-preview",
            "description": "支持 gpt-image-2、gemini-3.1-flash-image-preview、nanobanana2、nano-banana。未传时默认使用 nanobanana。"
          },
          "referenceImageSrcs": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "额外 UI 素材参考图的稳定引用：objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。sourceImageSrc 占用 1 张 provider 容量，因此 gpt-image-2 最多再提交 4 张、nanobanana2 最多再提交 5 张；超限返回 400，不会静默截断。"
            },
            "maxItems": 5
          },
          "aspectRatio": {
            "type": "string",
            "const": "1:1",
            "description": "UI 素材提取固定使用 1:1。"
          },
          "imageSize": {
            "type": "string",
            "enum": ["1K", "2K"],
            "description": "框选数量少时使用 1K，超过阈值时使用 2K。"
          },
          "projectId": {
            "type": ["string", "null"]
          },
          "generationInputs": {
            "$ref": "#/components/schemas/JsonValue"
          },
          "assetFolderId": {
            "type": ["string", "null"]
          },
          "spritesheetLabel": {
            "type": ["string", "null"]
          },
          "canvasCompletion": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EditorCanvasGenerationCompletion"
              },
              {
                "type": "null"
              }
            ],
            "description": "带项目上下文生成时，服务端据此直接写入画布完成态并返回最新项目快照。"
          }
        },
        "additionalProperties": false
      },
      "EditorIconSpritesheetIconResult": {
        "type": "object",
        "required": ["name", "imageSrc", "width", "height"],
        "properties": {
          "name": {
            "type": "string"
          },
          "imageSrc": {
            "type": "string"
          },
          "width": {
            "type": "integer",
            "minimum": 1
          },
          "height": {
            "type": "integer",
            "minimum": 1
          },
          "resource": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EditorProjectResource"
              },
              {
                "type": "null"
              }
            ]
          },
          "asset": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EditorAsset"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "EditorIconSpritesheetSliceWarning": {
        "type": "object",
        "required": ["code", "reason"],
        "properties": {
          "code": {
            "type": "string",
            "description": "自动拆分未完成的稳定原因码，包括原始连通域超限、局部候选拥挤、输出切片超限、处理超时、未识别到素材或切片持久化失败。"
          },
          "reason": {
            "type": "string",
            "description": "自动拆分未完成的可诊断原因。"
          }
        },
        "additionalProperties": false
      },
      "EditorGenerationWarning": {
        "type": "object",
        "required": ["code", "reason"],
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "postprocess-failed-source-preserved",
              "dimension-restore-fallback",
              "unsupported-image-style",
              "multiple-generation-warnings"
            ],
            "description": "生成成功但后处理发生非阻断降级时的稳定原因码。dimension-restore-fallback 只描述进入可选 pixelArt 处理前的交付尺寸归一结果：无法安全归一时，在该处理边界保留 provider 回图尺寸；它不描述或约束 pixelArt 成功后的最终尺寸，最终产物尺寸仍以逻辑分辨率 PNG 为准。"
          },
          "reason": {
            "type": "string",
            "description": "可直接展示给调用方的非阻断告警原因。"
          }
        },
        "additionalProperties": false
      },
      "EditorIconSpritesheetGenerationResponse": {
        "type": "object",
        "required": [
          "spritesheetImageSrc",
          "spritesheetWidth",
          "spritesheetHeight",
          "prompt",
          "model",
          "taskId",
          "priceMudPoints"
        ],
        "properties": {
          "spritesheetImageSrc": {
            "type": "string"
          },
          "spritesheetWidth": {
            "type": "integer",
            "minimum": 1,
            "description": "最终持久化 spritesheet PNG 的实际像素宽度；pixelArt 规整成功时为逻辑网格宽度，不保证等于 imageSize、provider 回图或画布 placeholder 宽度。"
          },
          "spritesheetHeight": {
            "type": "integer",
            "minimum": 1,
            "description": "最终持久化 spritesheet PNG 的实际像素高度；pixelArt 规整成功时为逻辑网格高度，不保证等于 imageSize、provider 回图或画布 placeholder 高度。"
          },
          "iconImageSrcs": {
            "type": "array",
            "description": "默认模式识别图集中全部有效 alpha 连通域并持久化的独立素材，按视觉阅读顺序命名为“素材 N”；数量由图集内容决定，不由 iconDescriptions 数量决定。sliceLayout=grid-2x2 时固定返回左上、右上、左下、右下四个格子的切片，各格内的零散视觉细节不会被拆成额外素材。",
            "items": {
              "$ref": "#/components/schemas/EditorIconSpritesheetIconResult"
            }
          },
          "sliceLayout": {
            "type": "string",
            "enum": ["grid-2x2"],
            "description": "仅当请求使用固定切片合同且主图完成透明化、切片持久化后返回。调用方可将该字段与 iconImageSrcs=4 共同作为固定四类素材的来源证明。"
          },
          "sliceWarning": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EditorIconSpritesheetSliceWarning"
              },
              {
                "type": "null"
              }
            ],
            "description": "可信透明图集已成功持久化，但全连通域自动拆分未完成时返回；此时 iconImageSrcs 为空，调用方仍应使用整张图集。原始连通域、输出数量或 CPU 预算超限不会产生切片 PUT、资源或画布切片。透明处理、Alpha/尺寸恢复、provider 原图修复性回读或透明图完整解码失败时走 provider 原图 source-only，sliceWarning 为 null。"
          },
          "prompt": {
            "type": "string"
          },
          "actualPrompt": {
            "type": ["string", "null"]
          },
          "model": {
            "type": "string"
          },
          "taskId": {
            "type": "string"
          },
          "priceMudPoints": {
            "type": "integer",
            "minimum": 0
          },
          "spritesheetResource": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EditorProjectResource"
              },
              {
                "type": "null"
              }
            ]
          },
          "spritesheetAsset": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EditorAsset"
              },
              {
                "type": "null"
              }
            ]
          },
          "project": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EditorProject"
              },
              {
                "type": "null"
              }
            ],
            "description": "当请求携带 canvasCompletion 且服务端成功写入画布布局时返回最新项目快照。"
          },
          "warning": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EditorGenerationWarning"
              },
              {
                "type": "null"
              }
            ],
            "description": "生成成功但风格归一化、尺寸恢复、透明背景处理、Alpha 回贴、provider 原图修复性回读、透明图完整解码或像素规整发生非阻断降级时返回。source-only 降级只返回 provider 原图且不会进入拆分；其它通用告警可以与 sliceWarning 并存。"
          }
        }
      },
      "EditorCharacterAnimationGenerationRequest": {
        "type": "object",
        "required": [
          "sourceLayerId",
          "sourceImageSrc",
          "sourceWidth",
          "sourceHeight",
          "promptText",
          "resolution",
          "ratio",
          "frameCount",
          "durationSeconds",
          "model"
        ],
        "properties": {
          "sourceLayerId": {
            "type": "string"
          },
          "sourceImageSrc": {
            "type": "string",
            "description": "角色源图的稳定引用：当前账号的 objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。"
          },
          "sourceWidth": {
            "type": "integer",
            "minimum": 1
          },
          "sourceHeight": {
            "type": "integer",
            "minimum": 1
          },
          "promptText": {
            "type": "string",
            "minLength": 1,
            "maxLength": 4000
          },
          "screenColor": {
            "type": ["string", "null"],
            "description": "纯色抠像背景色。可传画布支持的纯色背景 hex（如 #CFEFFF）指定；传 \"auto\"、null 或省略则由服务端自动决策。"
          },
          "resolution": {
            "type": "string",
            "enum": ["480p", "720p"],
            "default": "480p"
          },
          "ratio": {
            "type": "string",
            "enum": ["same", "1:1", "4:3", "16:9", "9:16", "3:4"],
            "default": "same"
          },
          "frameCount": {
            "type": "integer",
            "enum": [32, 40, 48]
          },
          "durationSeconds": {
            "type": "integer",
            "enum": [4, 5, 6]
          },
          "model": {
            "type": "string",
            "const": "seedance2.0-fast"
          },
          "projectId": {
            "type": ["string", "null"]
          },
          "canvasCompletion": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EditorCanvasGenerationCompletion"
              },
              {
                "type": "null"
              }
            ],
            "description": "带项目上下文生成时，服务端据此直接写入画布完成态并返回最新项目快照。"
          },
          "generationInputs": {
            "$ref": "#/components/schemas/JsonValue"
          },
          "sourceResourceId": {
            "type": ["string", "null"]
          },
          "assetFolderId": {
            "type": ["string", "null"],
            "description": "角色动作预览视频和最终透明序列帧素材写入账号素材库的文件夹；省略时写入默认项目素材文件夹。"
          },
          "assetLabel": {
            "type": ["string", "null"],
            "maxLength": 80,
            "description": "角色动作素材名称；空白或省略时使用自动名称。原始预览视频以该名称追加（原始视频）保存。"
          }
        },
        "additionalProperties": false
      },
      "EditorImageSequenceFrame": {
        "type": "object",
        "required": [
          "imageSrc",
          "objectKey",
          "assetObjectId",
          "width",
          "height"
        ],
        "properties": {
          "imageSrc": {
            "type": "string"
          },
          "objectKey": {
            "type": "string",
            "minLength": 1,
            "description": "帧对应的稳定 OSS Object Key；服务端据此重建持久 imageSrc，不能只提交临时签名 URL。"
          },
          "assetObjectId": {
            "type": "string",
            "minLength": 1,
            "description": "帧对应的稳定资产对象 ID。"
          },
          "width": {
            "type": "integer",
            "minimum": 1
          },
          "height": {
            "type": "integer",
            "minimum": 1
          }
        },
        "additionalProperties": false,
        "description": "图片序列帧。数组位置是唯一播放顺序，不携带额外序号字段；每帧必须同时携带 objectKey 与 assetObjectId，imageSrc 按 objectKey 规范化为持久站内路径。"
      },
      "EditorCharacterAnimationGenerationResponse": {
        "type": "object",
        "required": [
          "ok",
          "taskId",
          "model",
          "prompt",
          "previewVideoPath",
          "frames",
          "frameCount",
          "durationSeconds",
          "frameWidth",
          "frameHeight",
          "fps",
          "priceMudPoints"
        ],
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "taskId": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "prompt": {
            "type": "string"
          },
          "previewVideoPath": {
            "type": "string"
          },
          "frames": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EditorImageSequenceFrame"
            }
          },
          "frameCount": {
            "type": "integer",
            "minimum": 1
          },
          "durationSeconds": {
            "type": "integer",
            "minimum": 1
          },
          "frameWidth": {
            "type": "integer",
            "minimum": 1
          },
          "frameHeight": {
            "type": "integer",
            "minimum": 1
          },
          "fps": {
            "type": "integer",
            "minimum": 1
          },
          "priceMudPoints": {
            "type": "integer",
            "minimum": 0
          },
          "project": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EditorProject"
              },
              {
                "type": "null"
              }
            ],
            "description": "当请求携带 canvasCompletion 且服务端成功写入画布布局时返回最新项目快照。"
          },
          "resource": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EditorProjectResource"
              },
              {
                "type": "null"
              }
            ],
            "description": "最终透明角色动作对应的项目资源。携带 projectId 时，画布图层必须直接引用其 resourceId，不得再次创建重复资源。"
          },
          "asset": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EditorAsset"
              },
              {
                "type": "null"
              }
            ],
            "description": "最终透明角色动作素材。assetKind 为 character-animation，并直接包含序列帧字段。"
          },
          "queueState": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ExternalGenerationJobStatusRecord"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "EditorVideoGenerationRequest": {
        "type": "object",
        "required": [
          "prompt",
          "model",
          "aspectRatio",
          "durationSeconds",
          "resolution",
          "mode",
          "sound"
        ],
        "properties": {
          "prompt": {
            "type": "string",
            "minLength": 1,
            "maxLength": 4000
          },
          "model": {
            "type": "string",
            "enum": [
              "seedance2.0",
              "seedance2.0-fast",
              "kling3.0",
              "kling3.0-omni",
              "veo3.1",
              "veo3.1-fast"
            ]
          },
          "aspectRatio": {
            "type": "string",
            "enum": ["16:9", "9:16", "1:1", "4:3", "3:4", "21:9"]
          },
          "durationSeconds": {
            "type": "integer",
            "minimum": 4,
            "maximum": 15
          },
          "resolution": {
            "type": "string",
            "enum": ["480p", "720p", "1080p"]
          },
          "mode": {
            "type": "string",
            "const": "std"
          },
          "sound": {
            "type": "string",
            "enum": ["on", "off"]
          },
          "referenceImageSrcs": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "公网 URL、asset://、当前账号的 objectKey、项目资源 ID 或素材 ID。本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。仅 Seedance 2.0 系列支持。"
            },
            "maxItems": 9
          },
          "referenceVideoSrcs": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "公网 URL、asset://、当前账号的 objectKey、项目资源 ID 或素材 ID。本地临时视频必须先上传 OSS。禁止 Data URL / Blob URL。仅 Seedance 2.0 系列支持。"
            },
            "maxItems": 3
          },
          "referenceAudioSrcs": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "公网 URL、asset://、当前账号的 objectKey、项目资源 ID 或素材 ID。本地临时音频必须先上传 OSS。禁止 Data URL / Blob URL。仅 Seedance 2.0 系列支持。"
            },
            "maxItems": 3
          },
          "webSearchEnabled": {
            "type": "boolean",
            "default": true,
            "description": "是否允许视频模型联网增强提示；未传时默认开启。"
          },
          "projectId": {
            "type": ["string", "null"]
          },
          "canvasCompletion": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EditorCanvasGenerationCompletion"
              },
              {
                "type": "null"
              }
            ],
            "description": "带项目上下文生成时，服务端据此直接写入画布完成态并返回最新项目快照。"
          },
          "generationInputs": {
            "$ref": "#/components/schemas/JsonValue"
          },
          "sourceResourceId": {
            "type": ["string", "null"]
          },
          "assetKind": {
            "type": ["string", "null"]
          },
          "assetFolderId": {
            "type": ["string", "null"]
          },
          "assetLabel": {
            "type": ["string", "null"],
            "description": "写入素材库时使用的素材名称。"
          }
        },
        "additionalProperties": false
      },
      "EditorVideoGenerationResponse": {
        "type": "object",
        "required": [
          "ok",
          "videoSrc",
          "width",
          "height",
          "sourceType",
          "prompt",
          "model",
          "taskId",
          "durationSeconds",
          "resolution",
          "priceMudPoints"
        ],
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "videoSrc": {
            "type": "string"
          },
          "objectKey": {
            "type": ["string", "null"]
          },
          "assetObjectId": {
            "type": ["string", "null"]
          },
          "width": {
            "type": "integer",
            "minimum": 1
          },
          "height": {
            "type": "integer",
            "minimum": 1
          },
          "sourceType": {
            "type": "string",
            "const": "generated"
          },
          "prompt": {
            "type": "string"
          },
          "actualPrompt": {
            "type": ["string", "null"]
          },
          "model": {
            "type": "string"
          },
          "taskId": {
            "type": "string"
          },
          "durationSeconds": {
            "type": "integer",
            "minimum": 1
          },
          "resolution": {
            "type": "string"
          },
          "priceMudPoints": {
            "type": "integer",
            "minimum": 0
          },
          "thumbnailSrc": {
            "type": ["string", "null"]
          },
          "resource": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EditorProjectResource"
              },
              {
                "type": "null"
              }
            ]
          },
          "asset": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EditorAsset"
              },
              {
                "type": "null"
              }
            ]
          },
          "project": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EditorProject"
              },
              {
                "type": "null"
              }
            ],
            "description": "当请求携带 canvasCompletion 且服务端成功写入画布布局时返回最新项目快照。"
          },
          "queueState": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ExternalGenerationJobStatusRecord"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "EditorSoundEffectGenerationRequest": {
        "type": "object",
        "required": ["prompt"],
        "properties": {
          "prompt": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2048,
            "description": "用户原始语言音效描述。服务端按 ECMAScript String.trim() 语义删除首尾空白和行终止符（包括 U+FEFF，保留首尾 U+0085），再按 Unicode code point 校验 1-2048。"
          },
          "model": {
            "type": ["string", "null"],
            "default": "eleven_text_to_sound_v2",
            "description": "省略、null、空串、纯 Unicode White_Space 或首尾空白包围的 eleven_text_to_sound_v2 均 canonicalize 为 eleven_text_to_sound_v2；audio1.0 和其它非空值返回 400。"
          },
          "duration": {
            "anyOf": [
              {
                "type": "number",
                "minimum": 0.5,
                "maximum": 30
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "null 或省略表示自动时长；有限数值表示手动时长。服务端不按 UI 0.1 秒步进取整。"
          },
          "loop": {
            "type": "boolean",
            "default": false,
            "description": "独立 Loop 参数；服务端不从 Prompt 推断、同步或校验。"
          },
          "projectId": {
            "type": ["string", "null"]
          },
          "canvasCompletion": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EditorCanvasGenerationCompletion"
              },
              {
                "type": "null"
              }
            ],
            "description": "带项目上下文生成时，服务端据此直接写入画布完成态并返回最新项目快照。"
          },
          "generationInputs": {
            "$ref": "#/components/schemas/JsonValue"
          },
          "assetFolderId": {
            "type": ["string", "null"],
            "description": "传 project 时写入默认项目素材文件夹；传具体 folderId 时写入该文件夹。"
          },
          "assetLabel": {
            "type": ["string", "null"],
            "description": "写入素材库时使用的素材名称。"
          }
        },
        "additionalProperties": false
      },
      "EditorBackgroundMusicGenerationRequest": {
        "type": "object",
        "required": ["gptDescriptionPrompt", "makeInstrumental"],
        "properties": {
          "gptDescriptionPrompt": {
            "type": "string",
            "minLength": 1
          },
          "makeInstrumental": {
            "type": "boolean",
            "const": true
          },
          "projectId": {
            "type": ["string", "null"]
          },
          "canvasCompletion": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EditorCanvasGenerationCompletion"
              },
              {
                "type": "null"
              }
            ],
            "description": "带项目上下文生成时，服务端据此直接写入画布完成态并返回最新项目快照。"
          },
          "generationInputs": {
            "$ref": "#/components/schemas/JsonValue"
          },
          "assetFolderId": {
            "type": ["string", "null"],
            "description": "传 project 时写入默认项目素材文件夹；传具体 folderId 时写入该文件夹。"
          },
          "assetLabel": {
            "type": ["string", "null"],
            "description": "写入素材库时使用的素材名称。"
          }
        },
        "additionalProperties": false
      },
      "EditorAudioGenerationResponse": {
        "type": "object",
        "required": [
          "ok",
          "audioSrc",
          "width",
          "height",
          "sourceType",
          "prompt",
          "model",
          "taskId",
          "priceMudPoints",
          "audioKind"
        ],
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "audioSrc": {
            "type": "string"
          },
          "objectKey": {
            "type": ["string", "null"]
          },
          "assetObjectId": {
            "type": ["string", "null"]
          },
          "width": {
            "type": "integer",
            "minimum": 1
          },
          "height": {
            "type": "integer",
            "minimum": 1
          },
          "sourceType": {
            "type": "string",
            "const": "generated"
          },
          "prompt": {
            "type": "string"
          },
          "actualPrompt": {
            "type": ["string", "null"]
          },
          "model": {
            "type": "string"
          },
          "taskId": {
            "type": "string"
          },
          "priceMudPoints": {
            "type": "integer",
            "minimum": 0
          },
          "audioKind": {
            "type": "string",
            "enum": ["sound-effect", "background-music"]
          },
          "durationSeconds": {
            "type": ["number", "null"],
            "exclusiveMinimum": 0,
            "maximum": 600,
            "description": "SFX V2 为 MP3 探测所得实际时长；不是请求时长。BGM 或历史结果可省略。"
          },
          "loop": {
            "type": ["boolean", "null"],
            "description": "SFX V2 返回冻结并发送给 provider 的 Loop；BGM 或历史结果可省略。"
          },
          "project": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EditorProject"
              },
              {
                "type": "null"
              }
            ],
            "description": "当请求携带 canvasCompletion 且服务端成功写入画布布局时返回最新项目快照。"
          },
          "resource": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EditorProjectResource"
              },
              {
                "type": "null"
              }
            ],
            "description": "请求携带 projectId 时返回写入的画布资源快照。"
          },
          "asset": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EditorAsset"
              },
              {
                "type": "null"
              }
            ],
            "description": "请求携带 assetFolderId 时返回写入的账号素材快照。"
          },
          "queueState": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ExternalGenerationJobStatusRecord"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "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。背景音乐（audioKind=background-music）与不带 audioKind 的图片、视频、图标序列帧、角色动作和 UI 拆解结果都落在这里。pixelArt 图片的 width/height、图标结果的 spritesheetWidth/spritesheetHeight 及关联 resource/asset 尺寸均表示最终逻辑分辨率 PNG 的实际值，不保证等于请求档位、provider 回图或画布 placeholder。该 fallback 明确排除 audioKind=sound-effect，避免吞掉 SFX 专用分支。"
      },
      "ExternalEditorGenerationCompletedResult": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/ExternalEditorSoundEffectCompactResult"
          },
          {
            "$ref": "#/components/schemas/ExternalEditorGenerationGenericCompactResult"
          }
        ],
        "description": "External v1 轮询 completed 状态的命名 compact result 联合。两个分支已由 audioKind 的 const 与 not 精确互斥，不使用 discriminator：背景音乐返回 audioKind=background-music，图片、视频、图标序列帧、角色动作、UI 拆解与历史结果根本没有 audioKind，它们都无法映射到具名分支，且 fallback 分支不可能把 audioKind 声明为必填，因此任何 discriminator 映射都不可能覆盖全部合法结果。"
      },
      "ExternalEditorGenerationSubmissionResponse": {
        "type": "object",
        "required": [
          "operationId",
          "kind",
          "status",
          "statusUrl",
          "pollAfterMs",
          "updatedAtMicros"
        ],
        "properties": {
          "operationId": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": ["queued", "running", "completed", "failed"]
          },
          "statusUrl": {
            "type": "string"
          },
          "pollAfterMs": {
            "type": "integer",
            "minimum": 250
          },
          "updatedAtMicros": {
            "type": "integer"
          }
        },
        "additionalProperties": false
      },
      "ExternalEditorGenerationJobResponse": {
        "type": "object",
        "required": [
          "operationId",
          "kind",
          "status",
          "phaseLabel",
          "phaseDetail",
          "progress",
          "updatedAtMicros"
        ],
        "properties": {
          "operationId": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": ["queued", "running", "completed", "failed"]
          },
          "phaseLabel": {
            "type": "string"
          },
          "phaseDetail": {
            "type": "string"
          },
          "progress": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "error": {
            "type": "string"
          },
          "warning": {
            "type": "string"
          },
          "result": {
            "$ref": "#/components/schemas/ExternalEditorGenerationCompletedResult",
            "description": "仅在 completed 时返回的 compact 稳定结果引用；queued、running 和 failed 不返回该字段。为兼容历史完成结果，此字段不作为无版本迁移的必填约束。"
          },
          "pollAfterMs": {
            "type": "integer",
            "minimum": 250
          },
          "updatedAtMicros": {
            "type": "integer"
          }
        },
        "additionalProperties": false
      },
      "ExternalGenerationJobStatusRecord": {
        "type": "object",
        "required": [
          "operationId",
          "status",
          "phaseLabel",
          "phaseDetail",
          "progress",
          "updatedAtMicros"
        ],
        "properties": {
          "operationId": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": ["queued", "running", "completed", "failed"]
          },
          "phaseLabel": {
            "type": "string"
          },
          "phaseDetail": {
            "type": "string"
          },
          "progress": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "error": {
            "type": ["string", "null"]
          },
          "updatedAtMicros": {
            "type": "integer"
          }
        },
        "additionalProperties": false
      }
    }
  }
}