GenarrativeAI/Genarrative
11
0
Fork 0
Code Issues 14 Pull Requests 3 Actions 1 Packages Projects 3 Releases Wiki Activity
Files
c3c572dbace13d7560ab62e4bd2aedf7a1fb5d30
Genarrative/docs/openapi/genarrative-external-v1.openapi.json
T
suzmii aa8e3507d1
Project CI / Repository checks (push) Successful in 4m20s
Details
Project CI / Frontend tests (push) Successful in 4m31s
Details
Project CI / Backend tests (push) Successful in 5m45s
Details
Project CI / Native shell tests (push) Successful in 14m53s
Details
新增 External v1 去背景生成链路 (#184) 
新增外部去背景 API、MCP 工具与异步队列契约

补齐来源归属、媒体类型、幂等重放和画布原子持久化校验

修复 provenance 重建、assetKindOverride 门禁与 revision retry 竞态

同步 Python helper、Skill、OpenAPI 及项目文档

---------

Co-authored-by: kdletters <kdletters@qq.com>
Reviewed-on: http://192.168.35.82/git/GenarrativeAI/Genarrative/pulls/184
Co-authored-by: suzmii <suzmii@foxmail.com>
Co-committed-by: suzmii <suzmii@foxmail.com>
2026-08-24 14:37:32 +08:00

5300 lines
152 KiB
JSON
Raw Blame History

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