# **AI视频分镜生成器 - 前端API接口文档 (最终版)**

## **基本信息**

  * **Base URL:** `/api/v1`
  * **Content-Type:** `application/json`

## **重要功能更新 - 自定义提示词模板**

**新增功能：** 现在支持自定义提示词模板！前端可以：
1. 让用户从预设模板中选择
2. 允许用户微调提示词内容
3. 将完整的提示词模板传递给后端

**约定变量格式：**
- 生成剧本：`${script_or_idea}` - 用户的剧本或创意内容
- 生成分镜：`${materials_description}` - 项目素材描述，`${script}` - 用户剧本

**验证机制：** 后端会自动验证提示词模板是否包含必需的变量，缺少时会返回明确的错误提示。

## **新的工作流程说明**

本次更新引入了全新的AI驱动工作流程，推荐按以下顺序进行：

### **推荐工作流程：**

1. **创建项目** → `POST /projects`
2. **生成剧本** → `POST /projects/{project_id}/generate-script`
   - 输入创意或剧本草稿
   - AI自动生成完整剧本和所需素材列表
3. **素材处理** (三选一)：
   - **选项A：** 批量生成所有素材图 → `POST /projects/{project_id}/generate-asset-images`
   - **选项B：** 单独生成指定素材图 → `POST /assets/{asset_id}/generate-image`
   - **选项C：** 手动为素材提供图片 → `PUT /assets/{asset_id}/image`
4. **生成分镜** → `POST /projects/{project_id}/generate-storyboards` 
   - 系统会检查所有素材是否都有图片
5. **生成首帧图** → `POST /storyboards/{storyboard_id}/generate-frame`
6. **（可选）首帧图指导修改** → `POST /storyboards/{storyboard_id}/guide-frame`
7. **生成分镜视频** → `POST /storyboards/{storyboard_id}/generate-video`
8. **合成项目视频** → `POST /projects/{project_id}/compose-video`

### **兼容性说明：**

- 旧的"关联素材"接口 (`POST /projects/{project_id}/assets`) 仍然保留，但不推荐使用
- 项目删除现在是软删除，不会真正删除数据

## **模块：公共服务 (Public Services)**

### **1. 获取七牛云上传Token**

获取用于客户端直传文件到七牛云存储的临时Token。

  * **Endpoint:** `GET /qiniu/upload-token`

  * **请求参数:** 无

  * **成功响应 (200 OK):**

      * **Type:** `Object`
      * **描述:** 返回上传所需的Token以及相关的存储桶信息。Token具有一定的有效期。

    <!-- end list -->

    ```json
    {
      "token": "qiniu_generated_upload_token_string",
      "domain": "https://your-qiniu-domain.com",
      "bucket": "your_bucket_name"
    }
    ```

-----

## **模块一：提示词管理 (Prompt Management)**

### **1. 查询所有提示词**

获取系统中存储的所有可用提示词列表。

  * **Endpoint:** `GET /prompts`

  * **请求参数:** 无

  * **成功响应 (200 OK):**

      * **Type:** `Array<Object>`

    <!-- end list -->

    ```json
    [
      {
        "step": "create_shots",
        "name": "default_v1",
        "prompt": "这是一个用于生成分镜的提示词..."
      }
    ]
    ```

### **2. 根据step查询提示词**

获取指定step阶段的所有提示词。

  * **Endpoint:** `GET /prompts/step/{step}`

  * **路径参数 (Path):** `step` (String) - 提示词使用的阶段

  * **请求参数:** 无

  * **成功响应 (200 OK):**

      * **Type:** `Array<Object>`

    <!-- end list -->

    ```json
    [
      {
        "id": 1,
        "step": "create_shots",
        "name": "default_v1",
        "prompt": "这是一个用于生成分镜的提示词...",
        "created_at": "2025-08-27T10:30:00Z",
        "updated_at": "2025-08-27T11:00:00Z"
      },
      {
        "id": 2,
        "step": "create_shots",
        "name": "custom_v2",
        "prompt": "这是另一个用于生成分镜的提示词...",
        "created_at": "2025-08-27T10:35:00Z",
        "updated_at": "2025-08-27T11:05:00Z"
      }
    ]
    ```

  * **错误响应:**
    
    * **500 Internal Server Error:** 查询失败
      ```json
      {
        "detail": "根据step获取提示词失败: 具体错误信息"
      }
      ```

### **3. 新增或修改提示词**

创建一个新的提示词，或者根据 `step` 和 `name` 更新一个已有的提示词。

  * **Endpoint:** `POST /prompts`

  * **请求体 (Body):**

    | 字段名 | 类型 | 必填 | 描述 |
    | :--- | :--- | :--- | :--- |
    | `step` | String | 是 | 提示词使用的阶段 |
    | `name` | String | 是 | 提示词的名称 |
    | `prompt` | String | 是 | 提示词的具体内容 |

    **示例:**

    ```json
    {
      "step": "create_shots",
      "name": "default_v1",
      "prompt": "请根据以下剧本和素材描述，生成分镜列表..."
    }
    ```

  * **成功响应 (200 OK):**

      * **Type:** `Object`

    <!-- end list -->

    ```json
    {
      "id": 1,
      "step": "create_shots",
      "name": "default_v1",
      "prompt": "请根据以下剧本和素材描述，生成分镜列表...",
      "created_at": "2025-08-27T10:30:00Z",
      "updated_at": "2025-08-27T11:00:00Z"
    }
    ```

### **4. 删除提示词**

删除指定ID的提示词。

  * **Endpoint:** `DELETE /prompts/{prompt_id}`

  * **路径参数 (Path):** `prompt_id` (Integer) - 要删除的提示词ID

  * **请求参数:** 无

  * **成功响应 (200 OK):**

      * **Type:** `Object`

    <!-- end list -->

    ```json
    {
      "message": "提示词删除成功"
    }
    ```

  * **错误响应:**
    
    * **404 Not Found:** 提示词不存在
      ```json
      {
        "detail": "提示词不存在"
      }
      ```
    
    * **500 Internal Server Error:** 删除失败
      ```json
      {
        "detail": "删除提示词失败: 具体错误信息"
      }
      ```

-----

## **模块二：项目与视频生成 (Project & Video Generation)**

### **1. 分页获取项目列表**

获取已创建项目的分页列表。

  * **Endpoint:** `GET /projects`

  * **查询参数 (Query):**

    | 参数名 | 类型 | 必填 | 默认值 | 描述 |
    | :--- | :--- | :--- | :--- | :--- |
    | `page` | Integer | 否 | 1 | 页码 |
    | `size` | Integer | 否 | 20 | 每页数量 |

  * **成功响应 (200 OK):**

      * **Type:** `Object`

    <!-- end list -->

    ```json
    {
      "items": [
        {
          "id": 1,
          "name": "我的第一个项目",
          "created_at": "2025-08-27T10:30:00Z",
          "updated_at": "2025-08-27T11:00:00Z"
        }
      ],
      "total": 1,
      "page": 1,
      "size": 20
    }
    ```

### **2. 新建项目**

创建一个新的空项目。

  * **Endpoint:** `POST /projects`

  * **请求体 (Body):**

    | 字段名 | 类型 | 必填 | 描述 |
    | :--- | :--- | :--- | :--- |
    | `name` | String | 是 | 项目名称 |

    **示例:**

    ```json
    {
      "name": "我的第一个项目"
    }
    ```

  * **成功响应 (201 Created):**

      * **Type:** `Object`

    <!-- end list -->

    ```json
    {
      "id": 1,
      "name": "我的第一个项目"
    }
    ```

### **3. 删除项目**

软删除指定的项目（不会真正删除数据，只是标记为已删除）。

  * **Endpoint:** `DELETE /projects/{project_id}`

  * **路径参数 (Path):** `project_id` (Integer)

  * **请求参数:** 无

  * **成功响应 (200 OK):**

      * **Type:** `Object`

    <!-- end list -->

    ```json
    {
      "message": "项目 1 删除成功"
    }
    ```

  * **错误响应:**
    
    * **404 Not Found:** 项目不存在
      ```json
      {
        "detail": "项目 1 不存在"
      }
      ```
    
    * **500 Internal Server Error:** 删除失败
      ```json
      {
        "detail": "删除项目失败: 具体错误信息"
      }
      ```

### **4. 生成剧本**

根据创意或剧本生成完整剧本和所需素材信息。这是新的工作流程的第一步。

> **重要更新：** 现在支持自定义提示词模板！前端可以让用户选择并微调提示词模板，然后传递给后端。

  * **Endpoint:** `POST /projects/{project_id}/generate-script`

  * **路径参数 (Path):** `project_id` (Integer)

  * **请求体 (Body):**

    | 字段名 | 类型 | 必填 | 描述 |
    | :--- | :--- | :--- | :--- |
    | `script_or_idea` | String | 是 | 剧本或创意内容 |
    | `prompt_template` | String | 是 | 提示词模板，必须包含 `${script_or_idea}` 占位符 |

    **示例:**

    ```json
    {
      "script_or_idea": "一个关于小猫冒险的故事，小猫在森林里遇到了各种动物朋友",
      "prompt_template": "基于以下创意或剧本，生成一个完整的视频剧本和所需的素材列表。\n\n创意/剧本：${script_or_idea}\n\n请返回以下JSON格式的结果：\n{\n  \"full_script\": \"完整的视频剧本内容，包含详细的场景描述、对话、动作等\",\n  \"assets\": [\n    {\n      \"name\": \"素材名称\",\n      \"description\": \"素材的详细描述\",\n      \"tags\": [\"标签1\", \"标签2\", \"标签3\"]\n    }\n  ]\n}\n\n要求：\n1. 完整剧本应该包含影视风格和详细的整个完整故事(大概30~90秒)\n2. 素材列表应该包含制作这个视频所需的所有关键元素（人物、场景、道具、动物等视觉相关的元素）\n3. 每个素材都要有清晰的名称、描述和相关标签\n4. 确保所有素材的风格统一\n5. 确保返回的是有效的JSON格式，不要包含其他文字"
    }
    ```

  * **模板变量说明:**
    - `${script_or_idea}`: 会被替换为用户输入的剧本或创意内容

  * **成功响应 (200 OK):**

      * **Type:** `Object`

    <!-- end list -->

    ```json
    {
      "full_script": "第一场：森林入口\n小猫咪咪好奇地走进了神秘的森林...",
      "assets": [
        {
          "id": 1,
          "name": "小猫咪咪",
          "description": "一只橘色的小猫，有着明亮的绿眼睛",
          "tags": ["动物", "主角", "小猫"],
          "original_url": null,
          "created_at": "2025-08-27T10:30:00Z",
          "updated_at": "2025-08-27T10:30:00Z"
        },
        {
          "id": 2,
          "name": "神秘森林",
          "description": "一片茂密的森林，阳光透过树叶洒下",
          "tags": ["场景", "森林", "自然"],
          "original_url": null,
          "created_at": "2025-08-27T10:30:00Z",
          "updated_at": "2025-08-27T10:30:00Z"
        }
      ]
    }
    ```

  * **错误响应:**
    
    * **400 Bad Request:** 提示词模板缺少必需变量
      ```json
      {
        "detail": "提示词模板缺少必需的变量: script_or_idea。请确保模板中包含: ${script_or_idea}"
      }
      ```

### **5. 更新素材图**

为素材更新图片URL。用户可以为生成的素材提供自定义的图片。

  * **Endpoint:** `PUT /assets/{asset_id}/image`

  * **路径参数 (Path):** `asset_id` (Integer)

  * **请求体 (Body):**

    | 字段名 | 类型 | 必填 | 描述 |
    | :--- | :--- | :--- | :--- |
    | `image_url` | String | 是 | 素材图片URL |

    **示例:**

    ```json
    {
      "image_url": "https://example.com/my-custom-image.jpg"
    }
    ```

  * **成功响应 (200 OK):**

      * **Type:** `Object`

    <!-- end list -->

    ```json
    {
      "message": "素材图片更新成功"
    }
    ```

### **6. 生成单个素材图**

为指定的单个素材生成图片。前端提供素材ID，后端返回生成图片后的素材信息。

  * **Endpoint:** `POST /assets/{asset_id}/generate-image`

  * **路径参数 (Path):** `asset_id` (Integer) - 要生成图片的素材ID

  * **请求参数:** 无

  * **成功响应 (200 OK):**

      * **Type:** `Object`
      * **描述:** 返回生成图片后的素材信息

    <!-- end list -->

    ```json
    {
      "asset": {
        "id": 1,
        "project_id": 1,
        "name": "小猫咪咪",
        "description": "一只橘色的小猫，有着明亮的绿眼睛",
        "tags": ["动物", "主角", "小猫"],
        "original_url": "https://your-qiniu-domain.com/generated_cat_123.png",
        "created_at": "2025-08-27T10:30:00Z",
        "updated_at": "2025-08-27T10:35:00Z"
      }
    }
    ```

  * **错误响应:**
    
    * **404 Not Found:** 素材不存在
      ```json
      {
        "detail": "素材 1 不存在"
      }
      ```
    
    * **500 Internal Server Error:** 生成失败
      ```json
      {
        "detail": "生成素材图失败: 具体错误信息"
      }
      ```

### **7. 批量创建素材图**

为项目中所有没有图片的素材自动生成图片。如果所有素材都已有图片，则可以跳过此步骤。

  * **Endpoint:** `POST /projects/{project_id}/generate-asset-images`

  * **路径参数 (Path):** `project_id` (Integer)

  * **请求参数:** 无

  * **成功响应 (200 OK):**

      * **Type:** `Array<Object>`
      * **描述:** 返回项目的所有素材信息（包括新生成图片的素材）

    <!-- end list -->

    ```json
    [
      {
        "id": 1,
        "name": "小猫咪咪",
        "description": "一只橘色的小猫，有着明亮的绿眼睛",
        "tags": ["动物", "主角", "小猫"],
        "original_url": "https://your-qiniu-domain.com/generated_cat_123.png",
        "created_at": "2025-08-27T10:30:00Z",
        "updated_at": "2025-08-27T10:35:00Z"
      },
      {
        "id": 2,
        "name": "神秘森林",
        "description": "一片茂密的森林，阳光透过树叶洒下",
        "tags": ["场景", "森林", "自然"],
        "original_url": "https://your-qiniu-domain.com/generated_forest_456.png",
        "created_at": "2025-08-27T10:30:00Z",
        "updated_at": "2025-08-27T10:35:00Z"
      }
    ]
    ```

### **8. 关联素材** [已弃用 - 保留兼容性]

> **注意：** 此接口已被新的工作流程替代，但保留用于兼容性。新的推荐流程是：生成剧本 → 更新/生成素材图 → 生成分镜。

  * **Endpoint:** `POST /projects/{project_id}/assets`

  * **路径参数 (Path):** `project_id` (Integer)

  * **请求体 (Body):**

    | 字段名 | 类型 | 必填 | 描述 |
    | :--- | :--- | :--- | :--- |
    | `asset_urls` | Array\<String\> | 是 | **已上传到七牛云的**素材URL数组 |

    **示例:**

    ```json
    {
      "asset_urls": [
        "https://your-qiniu-domain.com/image1.jpg",
        "https://your-qiniu-domain.com/image2.png"
      ]
    }
    ```

  * **成功响应 (200 OK):**

      * **Type:** `Array<Object>`
      * **描述:** 返回分析和入库后的素材信息列表。

    <!-- end list -->

    ```json
    [
      {
        "id": 1,
        "name": "海滩上的女孩",
        "description": "一个穿着白色连衣裙的女孩在夕阳下的海滩上奔跑。",
        "tags": ["海滩", "女孩", "夕阳", "连衣裙"]
      }
    ]
    ```

### **9. 删除素材**

删除指定ID的素材。

  * **Endpoint:** `DELETE /assets/{asset_id}`

  * **路径参数 (Path):** `asset_id` (Integer) - 要删除的素材ID

  * **请求参数:** 无

  * **成功响应 (200 OK):**

      * **Type:** `Object`

    <!-- end list -->

    ```json
    {
      "message": "素材 1 删除成功"
    }
    ```

  * **错误响应:**
    
    * **404 Not Found:** 素材不存在
      ```json
      {
        "detail": "素材 1 不存在"
      }
      ```
    
    * **500 Internal Server Error:** 删除失败
      ```json
      {
        "detail": "删除素材失败: 具体错误信息"
      }
      ```

### **10. 生成分镜**

为指定项目提交剧本和提示词，生成一系列结构化的分镜描述。

> **重要更新：** 现在支持自定义提示词模板！前端可以让用户选择并微调提示词模板，然后传递给后端。

  * **Endpoint:** `POST /projects/{project_id}/generate-storyboards`

  * **路径参数 (Path):** `project_id` (Integer)

  * **请求体 (Body):**

    | 字段名 | 类型 | 必填 | 描述 |
    | :--- | :--- | :--- | :--- |
    | `script` | String | 是 | 用户输入的剧本内容 |
    | `prompt_template` | String | 是 | 提示词模板，必须包含 `${materials_description}` 和 `${script}` 占位符 |

    **示例:**

    ```json
    {
      "script": "清晨，女孩在海边醒来...",
      "prompt_template": "请根据以下剧本和素材描述，生成分镜列表。\n\n可用素材描述：\n${materials_description}\n\n用户剧本：\n${script}\n\n请根据以上信息生成分镜，返回JSON数组格式，每个分镜包含：\n- frame_prompt: 首帧图片生成提示词\n- frame_asset_ids: 用于生成首帧的素材ID数组\n- shot_prompt: 分镜动态内容提示词\n\n请确保返回的是有效的JSON数组格式，不要包含其他文字。"
    }
    ```

  * **模板变量说明:**
    - `${materials_description}`: 会被替换为项目中所有素材的描述信息
    - `${script}`: 会被替换为用户输入的剧本内容

  * **成功响应 (200 OK):**

      * **Type:** `Array<Object>`

    <!-- end list -->

    ```json
    [
      {
        "id": 1,
        "frame_prompt": "清晨金色的阳光下...",
        "frame_asset_ids": [1],
        "shot_prompt": "镜头特写女孩的面部..."
      }
    ]
    ```

  * **错误响应:**
    
    * **400 Bad Request:** 提示词模板缺少必需变量
      ```json
      {
        "detail": "提示词模板缺少必需的变量: materials_description, script。请确保模板中包含: ${materials_description}, ${script}"
      }
      ```

### **11. 生成分镜首帧图**

为一个已生成的分镜，生成其首帧静态图。

  * **Endpoint:** `POST /storyboards/{storyboard_id}/generate-frame`

  * **路径参数 (Path):** `storyboard_id` (Integer)

  * **请求体 (Body):**

    | 字段名 | 类型 | 必填 | 描述 |
    | :--- | :--- | :--- | :--- |
    | `frame_prompt` | String | 是 | 用于生成首帧图的提示词（可编辑） |
    | `frame_asset_ids` | Array\<Integer\> | 是 | 用于生成首帧图的素材ID数组（可编辑） |

    **示例:**

    ```json
    {
      "frame_prompt": "日出时分，一个女孩在沙滩上醒来...",
      "frame_asset_ids": [1]
    }
    ```

  * **成功响应 (200 OK):**

      * **Type:** `Object`

    <!-- end list -->

    ```json
    {
      "frame_image_url": "https://your-qiniu-domain.com/generated_image_123.png"
    }
    ```

### **12. 首帧图指导修改**

使用指导图修改分镜的首帧图。用户可以在白板上画草图来指导首帧图的生成。

  * **Endpoint:** `POST /storyboards/{storyboard_id}/guide-frame`

  * **路径参数 (Path):** `storyboard_id` (Integer)

  * **请求体 (Body):**

    | 字段名 | 类型 | 必填 | 描述 |
    | :--- | :--- | :--- | :--- |
    | `guide_image_url` | String | 是 | 指导图URL（用户在白板上画的动作或位置指导草图） |

    **示例:**

    ```json
    {
      "guide_image_url": "https://example.com/my-guide-sketch.jpg"
    }
    ```

  * **成功响应 (200 OK):**

      * **Type:** `Object`

    <!-- end list -->

    ```json
    {
      "frame_image_url": "https://your-qiniu-domain.com/guided_frame_789.png"
    }
    ```

### **13. 生成分镜视频**

为一个已生成首帧图的分镜，生成其动态视频。

  * **Endpoint:** `POST /storyboards/{storyboard_id}/generate-video`

  * **路径参数 (Path):** `storyboard_id` (Integer)

  * **请求体 (Body):**

    | 字段名 | 类型 | 必填 | 描述 |
    | :--- | :--- | :--- | :--- |
    | `shot_prompt` | String | 是 | 用于生成分镜视频的动态描述提示词（可编辑） |

    **示例:**

    ```json
    {
      "shot_prompt": "镜头从女孩的特写平滑地拉远..."
    }
    ```

  * **成功响应 (200 OK):**

      * **Type:** `Object`

    <!-- end list -->

    ```json
    {
      "shot_video_url": "https://your-qiniu-domain.com/generated_video_456.mp4"
    }
    ```

### **14. 合成项目视频**

将项目中所有分镜的视频合并成一个完整的项目视频。

  * **Endpoint:** `POST /projects/{project_id}/compose-video`

  * **路径参数 (Path):** `project_id` (Integer)

  * **请求参数:** 无

  * **成功响应 (200 OK):**

      * **Type:** `Object`

    <!-- end list -->

    ```json
    {
      "video_url": "https://your-qiniu-domain.com/project_final_video_789.mp4"
    }
    ```

  * **错误响应:**
    
    * **400 Bad Request:** 项目不存在或分镜没有视频
      ```json
      {
        "detail": "项目 1 的分镜都没有生成视频"
      }
      ```
    
    * **500 Internal Server Error:** 合成失败
      ```json
      {
        "detail": "合成项目视频失败: 具体错误信息"
      }
      ```

### **15. 获取项目所有信息**

获取一个项目的完整信息，用于重新打开项目时恢复前端状态。

  * **Endpoint:** `GET /projects/{project_id}`

  * **路径参数 (Path):** `project_id` (Integer)

  * **成功响应 (200 OK):**

      * **Type:** `Object`

    <!-- end list -->

    ```json
    {
      "project": {
        "id": 1,
        "name": "我的第一个项目",
        "script": "清晨，女孩在海边醒来...",
        "video_url": "https://your-qiniu-domain.com/project_final_video_789.mp4",
        "created_at": "2025-08-27T10:30:00Z",
        "updated_at": "2025-08-27T12:00:00Z"
      },
      "assets": [
        {
          "id": 1,
          "name": "海滩上的女孩",
          "description": "一个穿着白色连衣裙的女孩...",
          "tags": ["海滩", "女孩"],
          "original_url": "https://your-qiniu-domain.com/image1.jpg"
        }
      ],
      "storyboards": [
        {
          "id": 1,
          "frame_prompt": "日出时分...",
          "frame_asset_ids": [1],
          "frame_image_url": "https://your-qiniu-domain.com/generated_image_123.png",
          "shot_prompt": "镜头从女孩的特写平滑地拉远...",
          "shot_video_url": "https://your-qiniu-domain.com/generated_video_456.mp4"
        }
      ]
    }
    ```