{ "openapi": "3.0.3", "info": { "title": "AI视频分镜生成器 API", "description": "用于管理提示词、项目，并通过AI生成视频分镜、首帧图和视频的后端服务API。", "version": "1.0.0" }, "servers": [ { "url": "http://localhost:8000/api/v1", "description": "本地开发服务器" } ], "tags": [ { "name": "Public Services", "description": "公共服务接口，如获取上传Token" }, { "name": "Prompt Management", "description": "管理和维护系统中的各类提示词" }, { "name": "Project Management", "description": "项目的创建、查询以及素材管理" }, { "name": "Asset Management", "description": "素材的生成和管理" }, { "name": "Storyboard Generation", "description": "分镜的生成与处理" } ], "paths": { "/qiniu/upload-token": { "get": { "tags": [ "Public Services" ], "summary": "获取七牛云上传Token", "description": "获取用于客户端直传文件到七牛云存储的临时Token。", "operationId": "get_qiniu_upload_token", "responses": { "200": { "description": "成功获取Token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QiniuTokenResponse" } } } } } } }, "/prompts": { "get": { "tags": [ "Prompt Management" ], "summary": "查询所有提示词", "description": "获取系统中存储的所有可用提示词列表。", "operationId": "get_all_prompts", "responses": { "200": { "description": "成功返回提示词列表", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Prompt" } } } } } } }, "post": { "tags": [ "Prompt Management" ], "summary": "新增或修改提示词", "description": "创建一个新的提示词，或者根据 `step` 和 `name` 更新一个已有的提示词。", "operationId": "create_or_update_prompt", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptCreate" } } } }, "responses": { "200": { "description": "成功创建或更新提示词", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Prompt" } } } } } } }, "/projects": { "get": { "tags": [ "Project Management" ], "summary": "分页获取项目列表", "description": "获取已创建项目的分页列表。", "operationId": "get_projects_paginated", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 }, "description": "页码" }, { "name": "size", "in": "query", "schema": { "type": "integer", "default": 20 }, "description": "每页数量" } ], "responses": { "200": { "description": "成功返回项目分页列表", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedProjects" } } } } } }, "post": { "tags": [ "Project Management" ], "summary": "新建项目", "description": "创建一个新的空项目。", "operationId": "create_project", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectCreate" } } } }, "responses": { "201": { "description": "项目创建成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } } } } }, "/projects/{project_id}": { "get": { "tags": [ "Project Management" ], "summary": "获取项目所有信息", "description": "获取一个项目的完整信息，包括其关联的所有素材和分镜。", "operationId": "get_project_details", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "项目的唯一ID" } ], "responses": { "200": { "description": "成功返回项目详细信息", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FullProjectResponse" } } } }, "404": { "description": "项目未找到" } } }, "delete": { "tags": [ "Project Management" ], "summary": "删除项目", "description": "软删除指定的项目（不会真正删除数据，只是标记为已删除）", "operationId": "delete_project", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "项目ID" } ], "responses": { "200": { "description": "删除成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "项目 1 删除成功" } } } } } }, "404": { "description": "项目不存在" }, "500": { "description": "删除项目失败" } } } }, "/projects/{project_id}/generate-script": { "post": { "tags": [ "Project Management" ], "summary": "生成剧本", "description": "根据创意或剧本生成完整剧本和所需素材信息", "operationId": "generate_script", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "项目ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "script_or_idea": { "type": "string", "description": "剧本或创意内容", "example": "一个关于小猫冒险的故事，小猫在森林里遇到了各种动物朋友" } }, "required": [ "script_or_idea" ] } } } }, "responses": { "200": { "description": "生成成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateScriptResponse" } } } }, "400": { "description": "请求参数错误" }, "500": { "description": "生成剧本失败" } } } }, "/projects/{project_id}/compose-video": { "post": { "tags": [ "Project Management" ], "summary": "合成项目视频", "description": "将项目中所有分镜的视频合并成一个完整的项目视频", "operationId": "compose_project_video", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "项目ID" } ], "responses": { "200": { "description": "合成成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "video_url": { "type": "string", "format": "uri", "description": "合成后的项目视频URL" } } } } } }, "400": { "description": "项目不存在或分镜没有视频" }, "500": { "description": "合成项目视频失败" } } } }, "/projects/{project_id}/generate-asset-images": { "post": { "tags": [ "Asset Management" ], "summary": "创建素材图", "description": "为项目中所有没有图片的素材自动生成图片", "operationId": "generate_asset_images", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "项目ID" } ], "responses": { "200": { "description": "生成成功", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AssetResponse" } } } } }, "400": { "description": "项目不存在" }, "500": { "description": "创建素材图失败" } } } }, "/projects/{project_id}/assets": { "post": { "tags": [ "Project Management" ], "summary": "关联素材", "description": "前端上传素材到七牛云后，调用此接口将URL关联到项目中，后端将对素材进行AI分析。", "operationId": "associate_assets", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "项目的唯一ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "asset_urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "已上传到七牛云的素材URL数组" } }, "required": [ "asset_urls" ] } } } }, "responses": { "200": { "description": "成功关联并分析素材", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } } } } } } } }, "/assets/{asset_id}/image": { "put": { "tags": [ "Asset Management" ], "summary": "更新素材图", "description": "为素材更新图片URL", "operationId": "update_asset_image", "parameters": [ { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "素材ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image_url": { "type": "string", "format": "uri", "description": "素材图片URL", "example": "https://example.com/image.jpg" } }, "required": [ "image_url" ] } } } }, "responses": { "200": { "description": "更新成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "素材图片更新成功" } } } } } }, "404": { "description": "素材不存在" }, "500": { "description": "更新素材图失败" } } } }, "/projects/{project_id}/generate-storyboards": { "post": { "tags": [ "Storyboard Generation" ], "summary": "生成分镜", "description": "为指定项目提交剧本和提示词，生成一系列结构化的分镜描述。", "operationId": "generate_storyboards", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "项目的唯一ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoryboardGenerateRequest" } } } }, "responses": { "200": { "description": "成功生成分镜列表", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Storyboard" } } } } } } } }, "/storyboards/{storyboard_id}/generate-frame": { "post": { "tags": [ "Storyboard Generation" ], "summary": "生成分镜首帧图", "description": "为一个已生成的分镜，生成其首帧静态图。", "operationId": "generate_storyboard_frame", "parameters": [ { "name": "storyboard_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "分镜的唯一ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateFrameRequest" } } } }, "responses": { "200": { "description": "成功生成首帧图", "content": { "application/json": { "schema": { "type": "object", "properties": { "frame_image_url": { "type": "string", "format": "uri" } } } } } } } } }, "/storyboards/{storyboard_id}/guide-frame": { "post": { "tags": [ "Storyboard Generation" ], "summary": "首帧图指导修改", "description": "使用指导图修改分镜的首帧图", "operationId": "guide_frame_image", "parameters": [ { "name": "storyboard_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "分镜ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "guide_image_url": { "type": "string", "format": "uri", "description": "指导图URL（用户在白板上画的动作或位置指导草图）", "example": "https://example.com/guide.jpg" } }, "required": [ "guide_image_url" ] } } } }, "responses": { "200": { "description": "修改成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "frame_image_url": { "type": "string", "format": "uri", "description": "修改后的首帧图URL" } } } } } }, "400": { "description": "分镜不存在或缺少原首帧图" }, "500": { "description": "首帧图指导修改失败" } } } }, "/storyboards/{storyboard_id}/generate-video": { "post": { "tags": [ "Storyboard Generation" ], "summary": "生成分镜视频", "description": "为一个已生成首帧图的分镜，生成其动态视频。", "operationId": "generate_storyboard_video", "parameters": [ { "name": "storyboard_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "分镜的唯一ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shot_prompt": { "type": "string", "description": "用于生成分镜视频的动态描述提示词（可编辑）" } }, "required": [ "shot_prompt" ] } } } }, "responses": { "200": { "description": "成功生成分镜视频", "content": { "application/json": { "schema": { "type": "object", "properties": { "shot_video_url": { "type": "string", "format": "uri" } } } } } } } } } }, "components": { "schemas": { "QiniuTokenResponse": { "type": "object", "properties": { "token": { "type": "string", "description": "七牛云上传Token" }, "domain": { "type": "string", "format": "uri", "description": "七牛云空间域名" }, "bucket": { "type": "string", "description": "七牛云空间名称" } } }, "Prompt": { "type": "object", "properties": { "id": { "type": "integer" }, "step": { "type": "string" }, "name": { "type": "string" }, "prompt": { "type": "string" } } }, "PromptCreate": { "type": "object", "properties": { "step": { "type": "string", "example": "create_shots" }, "name": { "type": "string", "example": "default_v1" }, "prompt": { "type": "string" } }, "required": [ "step", "name", "prompt" ] }, "Project": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "video_url": { "type": "string", "format": "uri", "nullable": true, "description": "项目合成视频URL" } } }, "ProjectCreate": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] }, "ProjectSummary": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "video_url": { "type": "string", "format": "uri", "nullable": true, "description": "项目合成视频URL" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "PaginatedProjects": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectSummary" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "size": { "type": "integer" } } }, "Asset": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "original_url": { "type": "string", "format": "uri", "nullable": true } } }, "Storyboard": { "type": "object", "properties": { "id": { "type": "integer" }, "frame_prompt": { "type": "string" }, "frame_asset_ids": { "type": "array", "items": { "type": "integer" } }, "frame_image_url": { "type": "string", "format": "uri", "nullable": true }, "shot_prompt": { "type": "string" }, "shot_video_url": { "type": "string", "format": "uri", "nullable": true } } }, "StoryboardGenerateRequest": { "type": "object", "properties": { "script": { "type": "string" }, "prompt": { "type": "string" } }, "required": [ "script", "prompt" ] }, "GenerateFrameRequest": { "type": "object", "properties": { "frame_prompt": { "type": "string" }, "frame_asset_ids": { "type": "array", "items": { "type": "integer" } } }, "required": [ "frame_prompt", "frame_asset_ids" ] }, "FullProjectResponse": { "type": "object", "properties": { "project": { "$ref": "#/components/schemas/ProjectSummary" }, "assets": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } }, "storyboards": { "type": "array", "items": { "$ref": "#/components/schemas/Storyboard" } } } }, "AssetResponse": { "type": "object", "properties": { "id": { "type": "integer", "description": "素材ID" }, "project_id": { "type": "integer", "description": "项目ID" }, "name": { "type": "string", "description": "素材名称" }, "description": { "type": "string", "nullable": true, "description": "素材描述" }, "tags": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "素材标签" }, "original_url": { "type": "string", "format": "uri", "nullable": true, "description": "素材原始URL" }, "created_at": { "type": "string", "format": "date-time", "description": "创建时间" }, "updated_at": { "type": "string", "format": "date-time", "description": "更新时间" } }, "required": [ "id", "project_id", "name", "created_at", "updated_at" ] }, "GenerateScriptResponse": { "type": "object", "properties": { "full_script": { "type": "string", "description": "生成的完整剧本" }, "assets": { "type": "array", "items": { "$ref": "#/components/schemas/AssetResponse" } } }, "required": [ "full_script", "assets" ] } } } }