Local Mini Drama

GET {baseUrl}/api/v1/dramas?page=1&page_size=20

3. 创建新剧集项目

POST {baseUrl}/api/v1/dramas
Content-Type: application/json

{
  "title": "少年修仙传",
  "style": "古风仙侠",
  "type": "short_drama",
  "metadata": {
    "aspect_ratio": "16:9",
    "video_duration": 5
  }
}

metadata.aspect_ratio 支持 16:9（横屏）、9:16（竖屏）、1:1（方形）

4. 生成剧本（支持流式）

流式（推荐）：实时接收 AI 生成的剧本内容

POST {baseUrl}/api/v1/generation/story/stream
Content-Type: application/json

{
  "premise": "一个少年意外获得上古修仙传承...",
  "style": "古风仙侠",
  "episode_count": 3,
  "genre": "仙侠"
}

非流式：等待完整结果后一次性返回

POST {baseUrl}/api/v1/generation/story
Content-Type: application/json

{
  "premise": "...",
  "style": "古风仙侠",
  "episode_count": 3
}

流式响应格式（SSE）：

• { "type": "start" } — 开始
• { "type": "progress", "text": "已生成的文字..." } — 增量文本
• { "type": "done", "result": { "episodes": [...] } } — 完成，附结构化集数
• { "type": "error", "message": "..." } — 错误

将生成的剧本保存到项目集数：

字段名：script_content（不是 content），title（集标题），episode_number

PUT {baseUrl}/api/v1/dramas/{drama_id}/episodes
Content-Type: application/json

{
  "episodes": [
    {
      "episode_number": 1,
      "title": "山涧奇遇，石中传承",
      "script_content": "第一集剧本完整正文..."
    }
  ]
}

📋 项目管理

获取项目详情

GET {baseUrl}/api/v1/dramas/{drama_id}

更新项目信息

PUT {baseUrl}/api/v1/dramas/{drama_id}
Content-Type: application/json

{
  "title": "新标题",
  "style": "都市言情",
  "metadata": { "aspect_ratio": "9:16" }
}

删除项目（软删除）

DELETE {baseUrl}/api/v1/dramas/{drama_id}

获取项目统计

GET {baseUrl}/api/v1/dramas/stats

👤 角色管理

获取项目角色列表

GET {baseUrl}/api/v1/dramas/{drama_id}/characters

AI 提取剧本角色（异步任务）

POST {baseUrl}/api/v1/generation/characters
Content-Type: application/json

{
  "drama_id": "项目ID"
}

→ 返回 { "task_id": "...", "status": "pending" }，用 GET /api/v1/tasks/{task_id} 轮询

手动保存角色

PUT {baseUrl}/api/v1/dramas/{drama_id}/characters
Content-Type: application/json

{
  "characters": [
    { "name": "李逍遥", "description": "少年，侠客", "appearance": "白衣少年，剑眉星目" },
    { "name": "赵灵儿", "description": "仙女", "appearance": "青衣少女" }
  ]
}

生成角色形象图（AI）

POST {baseUrl}/api/v1/characters/{character_id}/generate-image
Content-Type: application/json

{
  "prompt_override": "古风仙侠，白衣少年，剑眉星目..."
}

生成角色四视图

POST {baseUrl}/api/v1/characters/{character_id}/generate-four-view-image

从图片提取角色描述

POST {baseUrl}/api/v1/characters/{character_id}/extract-from-image
Content-Type: application/json

{
  "image_url": "/static/storage/..."
}

全局角色库

GET  {baseUrl}/api/v1/character-library
POST {baseUrl}/api/v1/character-library   # 新建角色
PUT  {baseUrl}/api/v1/character-library/{id}
DELETE {baseUrl}/api/v1/character-library/{id}

🏠 场景管理

获取项目场景

GET {baseUrl}/api/v1/dramas/{drama_id}/scenes

提取场景（从集数剧本）

POST {baseUrl}/api/v1/episodes/{episode_id}/extract-backgrounds

生成场景图

POST {baseUrl}/api/v1/scenes/{scene_id}/generate-image

全局场景库

GET  {baseUrl}/api/v1/scene-library
POST {baseUrl}/api/v1/scene-library
PUT  {baseUrl}/api/v1/scene-library/{id}
DELETE {baseUrl}/api/v1/scene-library/{id}

🎬 道具管理

获取项目道具

GET {baseUrl}/api/v1/dramas/{drama_id}/props

提取道具

POST {baseUrl}/api/v1/episodes/{episode_id}/extract-props

生成道具图

POST {baseUrl}/api/v1/props/{prop_id}/generate

全局道具库

GET  {baseUrl}/api/v1/prop-library
POST {baseUrl}/api/v1/prop-library
PUT  {baseUrl}/api/v1/prop-library/{id}
DELETE {baseUrl}/api/v1/prop-library/{id}

🎥 分镜管理

生成分镜（异步任务）

POST {baseUrl}/api/v1/episodes/{episode_id}/storyboards
Content-Type: application/json

{
  "model": "qwen-plus",          // 可选，AI 模型名称
  "style": "古风仙侠",            // 可选，覆盖项目风格
  "storyboard_count": 8,         // 可选，分镜数量（默认自动）
  "video_duration": 5,            // 可选，单个视频秒数
  "aspect_ratio": "16:9",        // 可选，覆盖比例
  "include_narration": false      // 是否含旁白
}

→ 返回 { "task_id": "...", "status": "pending" }

获取集数分镜列表

GET {baseUrl}/api/v1/episodes/{episode_id}/storyboards

获取单条分镜详情

GET {baseUrl}/api/v1/storyboards/{storyboard_id}

更新分镜

PUT {baseUrl}/api/v1/storyboards/{storyboard_id}
Content-Type: application/json

{
  "dialogue": "调整后的台词",
  "action": "调整后的动作",
  "image_prompt": "调整后的画面描述"
}

删除分镜

DELETE {baseUrl}/api/v1/storyboards/{storyboard_id}

新增分镜（在指定位置前插入）

POST {baseUrl}/api/v1/storyboards/{storyboard_id}/insert-before

批量推断摄影参数（毫秒级，无需 AI）

POST {baseUrl}/api/v1/storyboards/batch-infer-params
Content-Type: application/json

{
  "episode_id": "集数ID",
  "overwrite": false   // 是否覆盖已有参数
}

优化分镜画面描述（AI）

POST {baseUrl}/api/v1/storyboards/{storyboard_id}/polish-prompt

生成分镜首/尾帧提示词

POST {baseUrl}/api/v1/storyboards/{storyboard_id}/frame-prompt
Content-Type: application/json

{
  "frame_type": "first",   // "first" | "last" | "key"
  "panel_count": 3,
  "model": "qwen-plus"
}

分镜图片超分（2x）

POST {baseUrl}/api/v1/storyboards/{storyboard_id}/upscale

🖼️ 图片生成

批量生成图片（推荐）

POST {baseUrl}/api/v1/images/episode/{episode_id}/batch
Content-Type: application/json

{
  "types": ["image"]          // 或 ["image", "video"] 同时出图和视频
}

查询图片任务

GET {baseUrl}/api/v1/images/{image_gen_id}

获取分镜关联的图片

GET {baseUrl}/api/v1/storyboards/{storyboard_id}/images

手动上传图片覆盖分镜

POST {baseUrl}/api/v1/storyboards/{storyboard_id}/upload
Content-Type: multipart/form-data