GenarrativeAI/Genarrative
11
0
Fork 0
Code Issues 15 Pull Requests 3 Actions Packages Projects 3 Releases Wiki Activity
Files
9c2f02db25b69887bc1982cfc3d70b136fa96a43
Genarrative/docs/openapi/genarrative-external-v1.openapi.json
T
k88936 a03f13d0a5
Project CI / Repository checks (push) Successful in 1m28s
Details
Project CI / Frontend tests (push) Successful in 3m19s
Details
Project CI / Backend tests (push) Successful in 4m3s
Details
Project CI / Native shell tests (push) Successful in 13m58s
Details
Fix/动作 前端展示下载+后端数据结构+精选 的问题 (#117) 
原问题

```
历史角色动作是一个兼容例外：
后端允许它没有 editor_project_resource 资源行，只要布局自身保存了完整图片序列帧。
```

- 把生成动作的原视频asstetkind改为 video， 只把图片序列作为action
- db asset新增字段image_sequence_frames_json image_seq_duration_ms等， （原来动作的这些数据存在generation-input中，并不合适）
修改了externaljob，把这部分数据正确填写到数据库中。
- 为避免到处fallback,做了数据库迁移, 脚本: `scripts/spacetime-normalize-editor-character-actions.mjs`   手动进行过画布+素材库中动作序列帧+原始视频 迁移的测试

- 移除preview_video_path字段,  reason:
>preview video
    → separate resource/asset with assetKind="video"
  final transparent action
    → assetKind="character-animation"
    → source_resource_id points to the preview-video resource
    → image_sequence_frames_json contains the actual playable result
>
> So preview_video_path on the final action duplicates the source video resource’s image_src.
- 移除每个frame的index字段 原因: 这个只用于后端内部处理时有一个并发请求, 每个赋一个index方便收集, 后续没有再用到,且与数组本身重复

- 清除副产品preview video的generation_input_json,  因为会影响改造功能, 迁移后预览视频不提供改造(参数), 只有序列帧动作有改造

仍存在的共性问题: #134

- 导出:
下载改为完整序列帧, 封面不再作为fallback, 部分帧读取失败时行为:仍生成 ZIP，并记录失败帧, 不变

画布放置:
before:
![shotmd-1785207959-compressed.webp](/attachments/e56454f0-49a3-4a8a-951f-c21960975f99)
after:
![shotmd-1785231365-compressed.webp](/attachments/886f07df-c25b-4ecc-acc9-160e1795a991)
精选模块: 主页展示, 审核部分UI:
![shotmd-1785500046-compressed.webp](/attachments/9ec3b679-0045-494a-9f20-134f7e73fecf)
![shotmd-1785499780-compressed.webp](/attachments/42396e63-5f26-4853-a367-0f3c15111add)
这两处序列帧们的加载设计为惰式的, 只有hover和单独preview才会全部加载

Reviewed-on: http://192.168.35.82/git/GenarrativeAI/Genarrative/pulls/117
Reviewed-by: 段舒康 <kdletters@qq.com>
Co-authored-by: 王德宇 <kvtodev@outlook.com>
Co-committed-by: 王德宇 <kvtodev@outlook.com>
2026-08-06 16:57:38 +08:00

4824 lines
129 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兼容性说明：v1 当前处于无外部存量调用方阶段，正式对外发放 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": []
}
],
"responses": {
"200": {
"description": "项目列表",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExternalEditorProjectListResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"post": {
"tags": [
"Editor Projects"
],
"operationId": "createEditorProject",
"summary": "创建图片画布项目",
"security": [
{
"ExternalApiKey": []
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExternalEditorProjectCreateRequest"
}
}
}
},
"responses": {
"200": {
"description": "已创建项目",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExternalEditorProjectResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/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"
}
],
"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"
}
}
}
},
"/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": []
}
],
"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"
}
}
}
},
"/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": "重绘/调整编辑器图片素材",
"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/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": "^[!-~]+$"
}
}
},
"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"
}
}
}
},
"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"
]
},
"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"
}
}
}
},
"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 为「角色主体为像素风格」）并在回图后执行像素规整。未知字符串或不支持该风格的 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": "省略时生成普通图片；其它值选择对应的专用生成流程。"
},
"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": {
"type": [
"string",
"null"
]
},
"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": "带项目上下文生成时，服务端据此直接写入画布完成态并返回最新项目快照。"
}
},
"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",
"sourceImageSrc"
],
"properties": {
"prompt": {
"type": "string",
"minLength": 1
},
"sourceImageSrc": {
"type": "string",
"description": "待重绘/调整图片的稳定引用：当前账号的 objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。"
},
"projectId": {
"type": [
"string",
"null"
]
},
"assetKind": {
"type": [
"string",
"null"
]
},
"generationInputs": {
"$ref": "#/components/schemas/JsonValue"
},
"assetFolderId": {
"type": [
"string",
"null"
]
},
"assetLabel": {
"type": [
"string",
"null"
]
},
"sourceResourceId": {
"type": [
"string",
"null"
]
},
"targetLayerId": {
"type": [
"string",
"null"
],
"description": "带 projectId 且未提供 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。sourceImageSrc 占用 1 张 provider 容量，因此 gpt-image-2 最多再提交 4 张、nanobanana2 最多再提交 8 张；超限返回 400，不会静默截断。"
},
"maxItems": 8
},
"canvasCompletion": {
"anyOf": [
{
"$ref": "#/components/schemas/EditorCanvasGenerationCompletion"
},
{
"type": "null"
}
],
"description": "带项目上下文生成时，服务端据此直接写入画布完成态并返回最新项目快照。"
}
},
"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
},
"height": {
"type": "integer",
"minimum": 1
},
"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": [
"referenceImageSrc",
"iconDescriptions"
],
"properties": {
"referenceImageSrc": {
"type": "string",
"description": "图标规范的稳定引用：当前账号的 objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。"
},
"referenceImageSrcs": {
"type": "array",
"items": {
"type": "string",
"description": "额外图标素材参考图的稳定引用：objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。referenceImageSrc 占用 1 张 provider 容量，因此 gpt-image-2 最多再提交 4 张、nanobanana2 最多再提交 8 张；超限返回 400，不会静默截断。"
},
"maxItems": 8
},
"iconDescriptions": {
"type": "array",
"description": "图标生成需求文本数组，供 prompt 组装使用；数组长度不控制自动切片数量。画布前端把完整用户提示词作为唯一数组元素提交；其它调用方可继续提交 1 到 100 条非空文本。",
"minItems": 1,
"maxItems": 100,
"items": {
"type": "string"
}
},
"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 会在提示词末尾追加一行「每个图标素材均为像素风格」并启用图标图集像素规整。未知字符串按 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": "带项目上下文生成时，服务端据此直接写入画布完成态并返回最新项目快照。"
}
},
"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": "生成成功但后处理发生非阻断降级时的稳定原因码。"
},
"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
},
"spritesheetHeight": {
"type": "integer",
"minimum": 1
},
"iconImageSrcs": {
"type": "array",
"description": "识别图集中全部有效 alpha 连通域并持久化的独立素材列表，按视觉阅读顺序命名为“素材 N”；数量由图集内容决定，不由 iconDescriptions 数量决定。自动生成与手动拆分图集使用相同识别规则。",
"items": {
"$ref": "#/components/schemas/EditorIconSpritesheetIconResult"
}
},
"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",
"duration"
],
"properties": {
"prompt": {
"type": "string",
"minLength": 1
},
"model": {
"type": [
"string",
"null"
],
"default": "audio1.0"
},
"duration": {
"type": "integer",
"minimum": 2,
"maximum": 10
},
"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"
]
},
"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"
}
]
}
}
},
"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": {
"type": "object",
"description": "completed 时返回的 compact 稳定结果引用；不包含完整 project/canvas、Data URL、Blob URL 或临时签名 URL。",
"additionalProperties": true
},
"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