kdletters
1f904d28e9
## 目标 保留现有客户端对话与 Codex app-server 链路，把客户端自身受控业务能力通过 MCP 暴露给 Codex。 ## 范围 - 客户端会话、项目文件、资源、画布、生成、预览等稳定能力 - 审核 Skill 的索引与按需指导资源 - 复用现有账号、项目路径、权限、计费、幂等、锁和恢复边界 ## 明确不做 - 不替换客户端对话入口或 Codex app-server - 不让客户端替 Codex 判断高层意图、完成状态或规划 - 不暴露任意 Tauri command、shell、凭据、内部 URL、数据库和管理能力 当前 PR 先建立独立分支与审查边界，后续提交实现与定向验证。 Reviewed-on: #274
4624 lines
143 KiB
JSON
4624 lines
143 KiB
JSON
{
|
||
"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",
|
||
"deprecated": true,
|
||
"description": "历史兼容字段，新的调用请使用 sliceCount。"
|
||
},
|
||
"sliceCount": {
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"maximum": 100,
|
||
"description": "可选的目标切片数量；省略时按图像内容自动识别。"
|
||
},
|
||
"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”；可通过 sliceCount 指定目标数量。",
|
||
"items": {
|
||
"$ref": "#/components/schemas/EditorIconSpritesheetIconResult"
|
||
}
|
||
},
|
||
"sliceLayout": {
|
||
"type": "string",
|
||
"deprecated": true,
|
||
"description": "历史兼容字段。"
|
||
},
|
||
"sliceCount": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 100,
|
||
"description": "实际生成的切片数量。"
|
||
},
|
||
"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
|
||
}
|
||
}
|
||
}
|
||
}
|