{ "openapi": "3.0.3", "info": { "title": "素材库 API", "version": "1.0.0", "description": "用户自有 Cloudflare R2 文件与 D1 目录。公开读取；Bearer 密钥管理。ID 为不透明字符串。既有平台前缀 ID 保持稳定，新建记录使用 UUID。" }, "servers": [ { "url": "https://product-film-library-mxtec.pages.dev/api/v1" } ], "paths": { "/health": { "get": { "operationId": "health", "summary": "服务健康状态", "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "api_version": { "type": "string" } } } } } }, "503": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auth": { "get": { "operationId": "verifyWriter", "summary": "验证管理密钥", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "role": { "type": "string" } } } } } } } }, "401": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/assets": { "get": { "operationId": "listAssets", "summary": "搜索和分页读取素材", "parameters": [ { "name": "q", "in": "query", "description": "搜索标题、描述、分类、产品、品牌、平台与标签，空格分隔词同时匹配。", "schema": { "type": "string", "maxLength": 200 } }, { "name": "type", "in": "query", "description": "素材类型", "schema": { "type": "string", "enum": [ "video", "image", "audio", "document" ] } }, { "name": "platform", "in": "query", "description": "来源平台，精确匹配", "schema": { "type": "string" } }, { "name": "category", "in": "query", "description": "产品分类，精确匹配", "schema": { "type": "string" } }, { "name": "tag", "in": "query", "description": "标签，精确匹配", "schema": { "type": "string" } }, { "name": "orientation", "in": "query", "description": "按尺寸判断画幅", "schema": { "type": "string", "enum": [ "landscape", "portrait", "square" ] } }, { "name": "min_duration", "in": "query", "description": "最短秒数", "schema": { "type": "number", "minimum": 0 } }, { "name": "max_duration", "in": "query", "description": "最长秒数", "schema": { "type": "number", "minimum": 0 } }, { "name": "min_width", "in": "query", "description": "最小宽度（像素）", "schema": { "type": "integer", "minimum": 0 } }, { "name": "min_height", "in": "query", "description": "最小高度（像素）", "schema": { "type": "integer", "minimum": 0 } }, { "name": "created_after", "in": "query", "description": "入库时间下限", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "description": "入库时间上限", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_after", "in": "query", "description": "最后修改时间下限（含边界），用于增量同步", "schema": { "type": "string", "format": "date-time" } }, { "name": "sort", "in": "query", "description": "排序字段，缺失指标始终排在末尾", "schema": { "type": "string", "enum": [ "created_at", "updated_at", "title", "duration", "size", "views", "likes", "post_views" ], "default": "created_at" } }, { "name": "order", "in": "query", "description": "排序方向", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "page", "in": "query", "description": "页码", "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1 } }, { "name": "page_size", "in": "query", "description": "每页数量", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 24 } }, { "name": "status", "in": "query", "description": "非 ready 状态需鉴权", "schema": { "type": "string", "enum": [ "ready", "pending", "archived", "all" ], "default": "ready" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetList" } } } }, "400": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createAsset", "summary": "创建上传记录或复用相同 SHA-256 的素材", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAsset" } } } }, "responses": { "200": { "description": "已存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateResponse" } } } }, "201": { "description": "已创建", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateResponse" } } } }, "401": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "507": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/assets/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } } ], "get": { "operationId": "getAsset", "summary": "读取素材详情", "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetResponse" } } }, "headers": { "ETag": { "schema": { "type": "string" }, "description": "并发修改版本" } } }, "304": { "description": "未修改" }, "404": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "head": { "operationId": "headAsset", "summary": "读取素材版本", "responses": { "200": { "description": "素材存在", "headers": { "ETag": { "schema": { "type": "string" } } } }, "404": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updateAsset", "summary": "更新元数据，数组和嵌套对象整体替换", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "If-Match", "in": "header", "required": true, "description": "详情响应的 ETag，例如 \"X11:1\"。", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAsset" } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetResponse" } } } }, "401": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "archiveAsset", "summary": "归档素材，保留原文件并支持恢复", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "If-Match", "in": "header", "required": true, "description": "详情响应的 ETag，例如 \"X11:1\"。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetResponse" } } } }, "401": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/facets": { "get": { "operationId": "getFacets", "summary": "分类、平台、类型和前 100 个标签及数量", "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "integer" } } } } } } } } } } } } }, "/stats": { "get": { "operationId": "getStats", "summary": "已公开素材总数、容量及上传上限", "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "total": { "type": "number" }, "size_bytes": { "type": "number" }, "duration_seconds": { "type": "number" }, "categories": { "type": "number" }, "platforms": { "type": "number" }, "storage_limit_bytes": { "type": "number" }, "max_upload_bytes": { "type": "number" } } } } } } } } } } }, "/export": { "get": { "operationId": "exportAssets", "summary": "导出筛选后的完整目录，最多 10000 条", "parameters": [ { "name": "q", "in": "query", "description": "搜索标题、描述、分类、产品、品牌、平台与标签，空格分隔词同时匹配。", "schema": { "type": "string", "maxLength": 200 } }, { "name": "type", "in": "query", "description": "素材类型", "schema": { "type": "string", "enum": [ "video", "image", "audio", "document" ] } }, { "name": "platform", "in": "query", "description": "来源平台，精确匹配", "schema": { "type": "string" } }, { "name": "category", "in": "query", "description": "产品分类，精确匹配", "schema": { "type": "string" } }, { "name": "tag", "in": "query", "description": "标签，精确匹配", "schema": { "type": "string" } }, { "name": "orientation", "in": "query", "description": "按尺寸判断画幅", "schema": { "type": "string", "enum": [ "landscape", "portrait", "square" ] } }, { "name": "min_duration", "in": "query", "description": "最短秒数", "schema": { "type": "number", "minimum": 0 } }, { "name": "max_duration", "in": "query", "description": "最长秒数", "schema": { "type": "number", "minimum": 0 } }, { "name": "min_width", "in": "query", "description": "最小宽度（像素）", "schema": { "type": "integer", "minimum": 0 } }, { "name": "min_height", "in": "query", "description": "最小高度（像素）", "schema": { "type": "integer", "minimum": 0 } }, { "name": "created_after", "in": "query", "description": "入库时间下限", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "description": "入库时间上限", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_after", "in": "query", "description": "最后修改时间下限（含边界），用于增量同步", "schema": { "type": "string", "format": "date-time" } }, { "name": "sort", "in": "query", "description": "排序字段，缺失指标始终排在末尾", "schema": { "type": "string", "enum": [ "created_at", "updated_at", "title", "duration", "size", "views", "likes", "post_views" ], "default": "created_at" } }, { "name": "order", "in": "query", "description": "排序方向", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "status", "in": "query", "description": "非 ready 状态需鉴权", "schema": { "type": "string", "enum": [ "ready", "pending", "archived", "all" ], "default": "ready" } }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "csv" ], "default": "json" } } ], "responses": { "200": { "description": "目录导出", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema_version": { "type": "string" }, "exported_at": { "type": "string", "format": "date-time" }, "total": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } } } } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/events": { "get": { "operationId": "listEvents", "summary": "读取管理操作记录，可按事件 ID 增量同步", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "after_id", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "大于 0 时按 ID 升序返回后续变更；默认返回最新记录。" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "next_after_id": { "type": "integer" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "asset_id": { "type": "string" }, "action": { "type": "string" }, "revision": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } } } } } } } } }, "401": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/assets/{id}/content": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } } ], "get": { "operationId": "getContent", "summary": "播放或读取原文件", "parameters": [ { "name": "Range", "in": "header", "schema": { "type": "string" }, "description": "单范围 bytes=0-1023 / bytes=-1024" }, { "name": "If-None-Match", "in": "header", "schema": { "type": "string" } }, { "name": "If-Range", "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "完整文件", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "206": { "description": "部分内容", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "304": { "description": "未修改" }, "404": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "416": { "description": "无效范围" } } }, "head": { "operationId": "headContent", "summary": "读取文件头", "responses": { "200": { "description": "文件元信息，Content-Length / ETag / Accept-Ranges" }, "404": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "uploadContent", "summary": "流式上传原文件；R2 校验预先声明的 SHA-256", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "Content-Length", "in": "header", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 94371840 } } ], "requestBody": { "required": true, "content": { "video/mp4": { "schema": { "type": "string", "format": "binary" } }, "video/webm": { "schema": { "type": "string", "format": "binary" } }, "video/quicktime": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } }, "image/gif": { "schema": { "type": "string", "format": "binary" } }, "image/avif": { "schema": { "type": "string", "format": "binary" } }, "audio/mpeg": { "schema": { "type": "string", "format": "binary" } }, "audio/mp4": { "schema": { "type": "string", "format": "binary" } }, "audio/wav": { "schema": { "type": "string", "format": "binary" } }, "audio/ogg": { "schema": { "type": "string", "format": "binary" } }, "audio/flac": { "schema": { "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "text/plain": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetResponse" } } } }, "401": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "411": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/assets/{id}/download": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } } ], "get": { "operationId": "getDownload", "summary": "下载原文件", "parameters": [ { "name": "Range", "in": "header", "schema": { "type": "string" }, "description": "单范围 bytes=0-1023 / bytes=-1024" }, { "name": "If-None-Match", "in": "header", "schema": { "type": "string" } }, { "name": "If-Range", "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "完整文件", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "206": { "description": "部分内容", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "304": { "description": "未修改" }, "404": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "416": { "description": "无效范围" } } }, "head": { "operationId": "headDownload", "summary": "读取文件头", "responses": { "200": { "description": "文件元信息，Content-Length / ETag / Accept-Ranges" }, "404": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/assets/{id}/thumbnail": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } } ], "get": { "operationId": "getThumbnail", "summary": "读取缩略图", "parameters": [ { "name": "Range", "in": "header", "schema": { "type": "string" }, "description": "单范围 bytes=0-1023 / bytes=-1024" }, { "name": "If-None-Match", "in": "header", "schema": { "type": "string" } }, { "name": "If-Range", "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "完整文件", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "206": { "description": "部分内容", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "304": { "description": "未修改" }, "404": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "416": { "description": "无效范围" } } }, "head": { "operationId": "headThumbnail", "summary": "读取文件头", "responses": { "200": { "description": "文件元信息，Content-Length / ETag / Accept-Ranges" }, "404": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "putThumbnail", "summary": "上传不超过 4 MiB 的预览图片", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "If-Match", "in": "header", "required": true, "description": "详情响应的 ETag，例如 \"X11:1\"。", "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, { "name": "Content-Length", "in": "header", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 4194304 } } ], "requestBody": { "required": true, "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetResponse" } } } }, "401": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/assets/{id}/storyboard": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } } ], "get": { "operationId": "getStoryboard", "summary": "读取分镜图", "parameters": [ { "name": "Range", "in": "header", "schema": { "type": "string" }, "description": "单范围 bytes=0-1023 / bytes=-1024" }, { "name": "If-None-Match", "in": "header", "schema": { "type": "string" } }, { "name": "If-Range", "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "完整文件", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "206": { "description": "部分内容", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "304": { "description": "未修改" }, "404": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "416": { "description": "无效范围" } } }, "head": { "operationId": "headStoryboard", "summary": "读取文件头", "responses": { "200": { "description": "文件元信息，Content-Length / ETag / Accept-Ranges" }, "404": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "putStoryboard", "summary": "上传不超过 4 MiB 的预览图片", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "If-Match", "in": "header", "required": true, "description": "详情响应的 ETag，例如 \"X11:1\"。", "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, { "name": "Content-Length", "in": "header", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 4194304 } } ], "requestBody": { "required": true, "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetResponse" } } } }, "401": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/assets/{id}/complete": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } } ], "post": { "operationId": "completeAsset", "summary": "检查已写入文件并完成入库，可用于上传后网络中断恢复", "security": [ { "BearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetResponse" } } } }, "401": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/assets/{id}/restore": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } } ], "post": { "operationId": "restoreAsset", "summary": "恢复已归档素材", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "If-Match", "in": "header", "required": true, "description": "详情响应的 ETag，例如 \"X11:1\"。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetResponse" } } } }, "401": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/assets/{id}/purge": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } } ], "delete": { "operationId": "purgeAsset", "summary": "永久删除已归档记录与 R2 原文件", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "If-Match", "in": "header", "required": true, "description": "详情响应的 ETag，例如 \"X11:1\"。", "schema": { "type": "string" } }, { "name": "X-Confirm-Purge", "in": "header", "required": true, "schema": { "type": "string" }, "description": "必须等于路径中的素材 ID。不可恢复。" } ], "responses": { "204": { "description": "永久删除完成" }, "400": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "错误响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "管理密钥；不是 Cloudflare API Token。" } }, "schemas": { "Source": { "type": "object", "additionalProperties": false, "properties": { "url": { "type": "string", "maxLength": 2048, "description": "原始 HTTP(S) 地址；可为空字符串。" }, "author": { "type": "string", "maxLength": 160 }, "published_at": { "type": "string", "format": "date-time", "nullable": true }, "collected_at": { "type": "string", "format": "date-time", "nullable": true }, "notes": { "type": "string", "maxLength": 4000 } } }, "Metrics": { "type": "object", "additionalProperties": false, "description": "不同来源指标保持独立。缺失值不代表零；视频播放、帖子查看、社区得分和众筹结果不可互换。", "properties": { "video_views": { "type": "integer", "format": "int64", "nullable": true, "minimum": 0 }, "post_views": { "type": "integer", "format": "int64", "nullable": true, "minimum": 0 }, "likes": { "type": "integer", "format": "int64", "nullable": true, "minimum": 0 }, "comments": { "type": "integer", "format": "int64", "nullable": true, "minimum": 0 }, "shares": { "type": "integer", "format": "int64", "nullable": true, "minimum": 0 }, "community_score": { "type": "integer", "format": "int64", "nullable": true }, "backers": { "type": "integer", "format": "int64", "nullable": true, "minimum": 0 }, "raised": { "type": "number", "minimum": 0, "nullable": true }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "nullable": true }, "observed_at": { "type": "string", "format": "date-time", "nullable": true } } }, "FileInput": { "type": "object", "required": [ "name", "mime_type", "size_bytes", "sha256" ], "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 240 }, "mime_type": { "type": "string", "enum": [ "video/mp4", "video/webm", "video/quicktime", "image/jpeg", "image/png", "image/webp", "image/gif", "image/avif", "audio/mpeg", "audio/mp4", "audio/wav", "audio/ogg", "audio/flac", "application/pdf", "text/plain" ] }, "size_bytes": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 94371840 }, "sha256": { "type": "string", "pattern": "^[a-fA-F0-9]{64}$" }, "width": { "type": "integer", "minimum": 1, "nullable": true }, "height": { "type": "integer", "minimum": 1, "nullable": true }, "duration_seconds": { "type": "number", "exclusiveMinimum": true, "minimum": 0, "nullable": true } } }, "CreateAsset": { "type": "object", "required": [ "title", "file" ], "additionalProperties": false, "properties": { "title": { "type": "string", "maxLength": 240, "minLength": 1 }, "description": { "type": "string", "maxLength": 8000 }, "category": { "type": "string", "maxLength": 80 }, "product": { "type": "string", "maxLength": 160 }, "brand": { "type": "string", "maxLength": 100 }, "platform": { "type": "string", "maxLength": 80 }, "tags": { "type": "array", "maxItems": 30, "uniqueItems": true, "items": { "type": "string", "maxLength": 60, "minLength": 1 } }, "source": { "$ref": "#/components/schemas/Source" }, "metrics": { "$ref": "#/components/schemas/Metrics" }, "file": { "$ref": "#/components/schemas/FileInput" } } }, "UpdateAsset": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "title": { "type": "string", "maxLength": 240, "minLength": 1 }, "description": { "type": "string", "maxLength": 8000 }, "category": { "type": "string", "maxLength": 80 }, "product": { "type": "string", "maxLength": 160 }, "brand": { "type": "string", "maxLength": 100 }, "platform": { "type": "string", "maxLength": 80 }, "tags": { "type": "array", "maxItems": 30, "uniqueItems": true, "items": { "type": "string", "maxLength": 60, "minLength": 1 } }, "source": { "$ref": "#/components/schemas/Source" }, "metrics": { "$ref": "#/components/schemas/Metrics" } } }, "Asset": { "type": "object", "required": [ "id", "title", "type", "status", "file", "urls", "revision" ], "properties": { "title": { "type": "string", "maxLength": 240, "minLength": 1 }, "description": { "type": "string", "maxLength": 8000 }, "category": { "type": "string", "maxLength": 80 }, "product": { "type": "string", "maxLength": 160 }, "brand": { "type": "string", "maxLength": 100 }, "platform": { "type": "string", "maxLength": 80 }, "tags": { "type": "array", "maxItems": 30, "uniqueItems": true, "items": { "type": "string", "maxLength": 60, "minLength": 1 } }, "source": { "$ref": "#/components/schemas/Source" }, "metrics": { "$ref": "#/components/schemas/Metrics" }, "id": { "type": "string" }, "type": { "type": "string", "enum": [ "video", "image", "audio", "document" ] }, "status": { "type": "string", "enum": [ "pending", "uploading", "ready", "archived" ] }, "revision": { "type": "integer", "minimum": 1 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "archived_at": { "type": "string", "format": "date-time", "nullable": true }, "file": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 240 }, "mime_type": { "type": "string", "enum": [ "video/mp4", "video/webm", "video/quicktime", "image/jpeg", "image/png", "image/webp", "image/gif", "image/avif", "audio/mpeg", "audio/mp4", "audio/wav", "audio/ogg", "audio/flac", "application/pdf", "text/plain" ] }, "size_bytes": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 94371840 }, "sha256": { "type": "string", "pattern": "^[a-fA-F0-9]{64}$" }, "width": { "type": "integer", "minimum": 1, "nullable": true }, "height": { "type": "integer", "minimum": 1, "nullable": true }, "duration_seconds": { "type": "number", "exclusiveMinimum": true, "minimum": 0, "nullable": true }, "verified_at": { "type": "string", "format": "date-time", "nullable": true } } }, "urls": { "type": "object", "properties": { "self": { "type": "string", "format": "uri", "nullable": false }, "view": { "type": "string", "format": "uri", "nullable": false }, "stream": { "type": "string", "format": "uri", "nullable": false }, "download": { "type": "string", "format": "uri", "nullable": false }, "thumbnail": { "type": "string", "format": "uri", "nullable": true }, "storyboard": { "type": "string", "format": "uri", "nullable": true } } } } }, "AssetResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Asset" } } }, "CreateResponse": { "type": "object", "required": [ "data", "duplicate", "upload" ], "properties": { "data": { "$ref": "#/components/schemas/Asset" }, "duplicate": { "type": "boolean" }, "upload": { "type": "object", "nullable": true, "properties": { "method": { "type": "string", "enum": [ "PUT" ] }, "url": { "type": "string", "format": "uri" }, "complete_url": { "type": "string", "format": "uri" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "size_bytes": { "type": "integer", "format": "int64" }, "sha256": { "type": "string" } } } } }, "AssetList": { "type": "object", "required": [ "data", "pagination", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "page_size": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "links": { "type": "object", "properties": { "self": { "type": "string", "format": "uri" }, "next": { "type": "string", "format": "uri", "nullable": true }, "previous": { "type": "string", "format": "uri", "nullable": true } } } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } } } } } } } }