DramaAIStudio（灵伴智能AI影视工场）

本技能封装了灵伴智能AI影视工场（DramaAIStudio）平台提供的多项 HTTP API，帮助用户在对话中完成：

• 剧目（项目）管理（§4）：获取剧目列表、创建剧目、获取单个剧目详情；获取剧目统计信息；获取/更新项目默认风格配置
• 剧本管理与资产分析（§5）：获取剧本集列表、按集上传剧本、按集读取剧本内容、按集删除剧本；剧本资产智能分析，从剧本抽取人物/场景/道具资产并写入资产库
• 资产管理（§6）：按类型/集数/名称过滤资产列表、创建资产、获取/更新单个资产；辅助生成资产提示词；基于参考图与提示词生成资产图像；查询资产终稿候选图像列表、将单张候选图像设为/取消终稿；对候选图（含终稿）查询/新增评论并将评论标为已解决
• 分镜脚本管理（§7）：按集读取分镜脚本、分析生成分镜脚本；查询镜头详情；为镜头关联资产；生成/优化镜头提示词；删除镜头
• 分镜视频生成（§8）：创建/查询分镜视频生成任务

当用户提到「列出所有剧目（项目）」「创建剧目（项目）」「查询剧目（项目）统计信息」「短剧（项目）风格配置」「上传/读取剧本」「剧本分析」「创建资产」「更新资产」「资产列表」「查看资产详情」「生成资产提示词」「生成资产图像」「候选图/终稿评论」「查看/分析分镜」「生成/优化镜头提示词」「生成分镜视频」等需求时，可使用本技能文档中列出的对应 API。

当以评审角色定期巡检资产变更、对候选图写评论与终稿决策、或基于参照图指导再次生图时，可结合 §3 评审模式 与 §6 相关接口（评论：§6.9～§6.11；终稿：§6.8；生图：§6.6）。

接口详解文件：§2.2 与 §4～§8 各 HTTP 接口的完整说明（参数、请求/响应示例、错误处理等）位于 {baseDir}/references/ 下，文件名形如 ref-*.md。占位符 {baseDir} 与本技能文件 SKILL.md 所在目录相同（二者同级，详见各小节文末引用路径）。

1. 本技能的使用方式

• 技能名称：drama-ai-studio
• 所有接口统一通过 HTTP 调用：
  • 基础域名示例：https://idrama.lingban.cn/
  • 对外网关统一前缀：/openapi
  • 最终访问路径形如：https://idrama.lingban.cn/openapi/drama/...

智能体需要选择一个支持 HTTP 的工具（如 http_request 或 bash）发起请求，并在 Header 中附带认证信息。

2. 认证

2.1 在 iDrama API令牌获取页面获取 Token

1. 引导用户在浏览器中打开：https://idrama.lingban.cn/api-token。
2. 提示用户在该页面完成登录（如果尚未登录）。
3. 登录成功后，在该页面上获取专用于 OpenClaw 的访问 Token（页面会显示一串 Token，如 xxxx...）。
4. 让用户将该 Token 复制并粘贴回对话中，作为后续所有接口调用的认证凭据。

请求头中携带：

Authorization: Bearer <从 idrama API令牌获取页面复制的 token>

2.2 通过iDrama的账号和密码获取 Token

• 接口：POST /openapi/uaa/oauth/token

完整说明（参数表、请求/响应示例与错误处理）：{baseDir}/references/ref-2-2-idrama-token.md

3. 工作模式与业务流程总览

本技能在流程上区分为两种工作模式：创作模式（从零搭建内容与管线）与评审模式（面向已生成资产的巡检、评论与迭代生图依据）。二者共用同一套鉴权与 OpenAPI（§2、§4～§8），智能体可按用户当前 intent 择一为主或组合使用。

3.0 IDRAMA_TOKEN 读取、校验与持久化（§3 入口）

进入 §3 相关流程时，智能体先处理访问令牌，再执行 3.1 / 3.2 中的业务步骤。

1. 读取（按优先级合并理解；若多处同时存在且不一致，以环境变量为准并提示用户）：

   • 当前进程/会话中的环境变量 IDRAMA_TOKEN；
   • 技能包根目录下文件 {baseDir}/.env 中的 IDRAMA_TOKEN= 行（标准 dotenv：KEY=value，# 为注释）。

2. 若已读到非空值：

   • 向用户部分隐藏展示（例如仅保留头尾各若干字符、中间为 …，不输出完整串），并说明来源（环境变量或 .env）。
   • 询问用户是否更新。若用户要更新，则按 §2（页面取 Token 或 POST /openapi/uaa/oauth/token）重新取得令牌。

3. 若未读到、为空、或调用 §4～§8 任一试请求验证失败（视为无效）：

   • 直接按 §2 引导用户完成认证并取得新 IDRAMA_TOKEN。

4. 落盘与同步（取得有效 Token 后必须执行）：

   • 将 IDRAMA_TOKEN 写入运行环境（使后续本技能相关 HTTP 与脚本子进程能继承），并更新或创建 {baseDir}/.env：保留该文件其它已有行，仅新增或替换 IDRAMA_TOKEN=… 一行（勿在聊天中回显完整新 Token）。

3.1 创作模式

整体业务围绕「剧目 → 剧本 → 资产 → 分镜脚本 → 分镜视频」的闭环；逐步操作示例见 §10 实践案例。

当识别到用户开启了创作模式，并且智能体不确定当前创作的项目ID时，智能体应该先读取 {baseDir}/session_state.json，获取当前会话关注的项目信息（id、name、focused_at），将其展示给用户并询问是否继续该项目创作。
若用户确认继续，则沿用该项目；若用户改为创作其他短剧项目（包括新建项目），则在完成项目切换后同步更新 {baseDir}/session_state.json 中对应字段（ID、名称、关注时间）；

{baseDir}/session_state.json 示例：

{
  "current_project": {
    "id": "12345",
    "name": "校园奇妙夜",
    "focused_at": "2026-04-07T09:30:00Z"
  }
}

基本创作流程如下（注意对于其中任一步骤，中间发生项目切换都要更新{baseDir}/session_state.json）：

1. 创建剧目（§4.2）
2. 查看剧目统计与风格配置（§4.4、§4.5/4.6）
3. 上传剧本、查看剧集列表、按剧集读取或删除（§5）
4. 按剧集智能分析与提取各类资产（§5.5）
5. 查看资产列表、按需创建资产（§6）
6. 按需辅助生成资产提示词（§6.5），并更新和保存至资产数据
7. 按需为资产生成图像（§6.6）
8. 按剧集智能分析与拆分镜头（§7）
9. 参考资产图像生成分镜视频（§8）

3.2 评审模式

面向已存在剧目的资产候选图与终稿状态，强调定时拉取差异、人工过目、评论回写、必要时用参照图约束下一轮生图。

1. 定时发现资产变更
   本技能直接使用 OpenClaw Gateway 内置 Cron 调度器。

   （1）查看当前 Cron 任务

   • 列表：openclaw cron list
   • 查看某任务运行历史：openclaw cron runs --id <jobId>
   • 手动触发一次：openclaw cron run <jobId>

   （2）创建“资产快照巡检”定时任务（推荐：isolated）
   资产变更巡检属于高频后台工作，建议用 isolated session，避免污染主会话上下文；并通过 --announce 将结果投递回对话（或你配置的 channel）。

   示例：每 30 秒巡检一次指定项目 play_id=12345（以北京时间为准）：

   openclaw cron add \
     --name "iDrama 资产巡检 play_id=12345" \
     --cron "*/30 * * * * *" \
     --tz "Asia/Shanghai" \
     --session isolated \
     --message "评审模式：请用 bash 执行 `python {baseDir}/scripts/sync_project_assets_snapshot.py 12345 --token <IDRAMA_TOKEN> --quiet`。若输出 status=changed，则把 diff 详情贴回（对于图片，需要给出可点击查看的url）；若 unchanged 则保持静默。最后，获取和显示当前的Cron定时任务列表，询问用户是否做出调整（创建、启用、停用、修改和删除）" \
     --announce

   说明：

   • sync_project_assets_snapshot.py 会把快照写入数据目录（默认 ./project_data/<play_id>/assets.json，也可通过环境变量 IDRAMA_DATA_DIR 调整），并在检测到变化时输出结构化 diff（JSON）。
   • 若你的 Gateway/主机在整点触发很多任务，可用 --stagger 30s（或 --exact 强制不抖动）调整触发节奏。

   （3）修改/停用/删除任务

   • 修改（patch）：openclaw cron edit <jobId> --cron "*/30 * * * *" --tz "Asia/Shanghai"
   • 停用：openclaw cron edit <jobId> --disable
   • 启用：openclaw cron edit <jobId> --enable
   • 删除：openclaw cron rm <jobId>

   （4）反馈资产变更摘要（评审侧衔接）
   定时任务每次运行完成后：

   • 若检测到变更（脚本输出 status=changed），智能体应将 diff 详情反馈给用户（对于图片，需要给出可点击查看的url），并提示下一步进入「2. 查看候选图与评审」。
   • 若用户不使用 Cron，则在对话内直接用 §6.1 / §6.3 / §6.7 比对即可。

2. 查看候选图与评审
   用户根据 §6.3 或上一步贴回的脚本/接口结果里的图片 URL（需补全为可访问地址时，与 §1 基址、/openapi 规则一致）在浏览器中打开候选图，进行视觉评审。
   评审结论可通过 OpenAPI 写回后台：新增评论（§6.10）、查看已有评论（§6.9）、将评论标为已解决（§6.11）；设终稿 / 取消终稿（§6.8）；必要时结合 §6.7 核对终稿列表。

3. 参照图：检索与上传，并用于候选图生成
   用户在智能体辅助下确定更适合的资产视觉特征，并从网络搜索和下载相匹配的图片作为资产参考图，通过 OpenAPI 上传资产参考图到后台（§6.12）

4. 剧目（项目）管理 API

前缀：/openapi/drama

4.1 GET /openapi/drama/list

获取剧目列表。

完整说明（参数表、请求/响应示例与错误处理）：{baseDir}/references/ref-4-1-get-openapi-drama-list.md

4.2 POST /openapi/drama/create

创建新剧目。

完整说明（参数表、请求/响应示例与错误处理）：{baseDir}/references/ref-4-2-post-openapi-drama-create.md

4.3 GET /openapi/drama/{play_id}

获取单个剧目详情；找不到返回 404。

完整说明（参数表、请求/响应示例与错误处理）：{baseDir}/references/ref-4-3-get-openapi-drama-play-id.md

4.4 GET /openapi/drama/{play_id}/stats

获取剧目统计信息（集数、镜头数、资产数量等）。

完整说明（参数表、请求/响应示例与错误处理）：{baseDir}/references/ref-4-4-get-openapi-drama-play-id-stats.md

4.5 GET /openapi/drama/{play_id}/style-config

4.6 PUT /openapi/drama/{play_id}/style-config

获取/更新项目默认风格配置。

完整说明（参数表、请求/响应示例与错误处理）：{baseDir}/references/ref-4-5-4-6-drama-style-config.md

5. 剧本管理与资产分析 API

前缀：/openapi/drama/{play_id}/scripts

5.1 GET /openapi/drama/{play_id}/scripts

获取剧本集列表。

完整说明（参数表、请求/响应示例与错误处理）：{baseDir}/references/ref-5-1-get-openapi-drama-play-id-scripts.md

5.2 POST /openapi/drama/{play_id}/scripts/upload

上传或更新单集剧本文本，支持 multipart/form-data 与 application/json。

完整说明（参数表、请求/响应示例与错误处理）：{baseDir}/references/ref-5-2-post-openapi-drama-play-id-scripts-upload.md

5.3 GET /openapi/drama/{play_id}/scripts/{episode_no}/content

获取指定集剧本原文；不存在时返回 404。

完整说明（参数表、请求/响应示例与错误处理）：{baseDir}/references/ref-5-3-get-openapi-drama-play-id-scripts-episode-no-content.md

5.4 DELETE /openapi/drama/{play_id}/scripts/{episode_no}

删除指定集剧本。

完整说明（参数表、请求/响应示例与错误处理）：{baseDir}/references/ref-5-4-delete-openapi-drama-play-id-scripts-episode-no.md

5.5 POST /openapi/drama/{play_id}/scripts/analyze

剧本资产智能分析，从原文中抽取场景/角色/道具并更新资产库。

完整说明（参数表、请求/响应示例与错误处理）：{baseDir}/references/ref-5-5-post-openapi-drama-play-id-scripts-analyze.md

6. 资产管理 API

前缀：/openapi/drama/{play_id}/assets

6.1 GET /openapi/drama/{play_id}/assets/list

按类型、集数、名称过滤资产列表，并附带封面与是否有终稿图标记。

完整说明（参数表、请求/响应示例与错误处理）：{baseDir}/references/ref-6-1-get-openapi-drama-play-id-assets-list.md

6.2 POST /openapi/drama/{play_id}/assets/create

创建新资产。

完整说明（参数表、请求/响应示例与错误处理）：{baseDir}/references/ref-6-2-post-openapi-drama-play-id-assets-create.md

6.3 GET /openapi/drama/{play_id}/assets/{asset_id}

获取单个资产详情。

完整说明（参数表、请求/响应示例与错误处理）：{baseDir}/references/ref-6-3-get-openapi-drama-play-id-assets-asset-id.md

6.4 PUT /openapi/drama/{play_id}/assets/{asset_id}

更新已有资产的名称、类型、描述、来源集数、提示词等。请求体 至少提供一个可更新字段；仅允许修改未软删除的资产。

完整说明（参数表、请求/响应示例与错误处理）：{baseDir}/references/ref-6-4-put-openapi-drama-play-id-assets-asset-id.md

6.5 POST /openapi/drama/{play_id}/assets/prompt-helper/generate

调用大模型 辅助生成资产图像提示词：根据资产类型、模式与描述等，经模板渲染后请求文本模型，返回一段可直接用于图像生成的中文提示词。

完整说明（参数表、请求/响应示例与错误处理）：{baseDir}/references/ref-6-5-post-openapi-drama-play-id-assets-prompt-helper-generate.md

6.6 POST /openapi/drama/{play_id}/assets/{asset_type}/{asset_id}/generate_image

资产图片生成：基于用户提示词、提示词模板与参考图调用模型生成图片，并作为新候选图写入对应资产。

完整说明（参数表、请求/响应示例与错误处理）：{baseDir}/references/ref-6-6-post-openapi-drama-play-id-assets-asset-type-asset-id-generate-image.md

6.7 GET /openapi/drama/{play_id}/assets/{asset_type}/{asset_id}/general/candidates/final-candidates

获取该资产下已选为终稿的候选图列表，顺序由终稿选中时间等规则决定。

完整说明（参数表、请求/响应示例与错误处理）：{baseDir}/references/ref-6-7-get-openapi-drama-play-id-assets-asset-type-asset-id-general-candidates-final-candidates.md

6.8 PUT /openapi/drama/{play_id}/assets/{asset_type}/{asset_id}/general/candidates/{cand_id}/final

将单张资产候选图设为终稿或从终稿集合中移除。

完整说明（参数表、请求/响应示例与错误处理）：{baseDir}/references/ref-6-8-put-openapi-drama-play-id-assets-asset-type-asset-id-general-candidates-cand-id-final.md

6.9 GET /openapi/drama/{play_id}/assets/{asset_type}/{asset_id}/general/candidates/{cand_id}/comments

获取指定候选图下的评论列表，按创建时间正序排列。

完整说明（参数表、请求/响应示例与错误处理）：{baseDir}/references/ref-6-9-get-openapi-drama-play-id-assets-asset-type-asset-id-general-candidates-cand-id-comments.md

6.10 POST /openapi/drama/{play_id}/assets/{asset_type}/{asset_id}/general/candidates/{cand_id}/comments

为指定候选图新增一条评论。cand_id 对应的候选图须已存在。

完整说明（参数表、请求/响应示例与错误处理）：{baseDir}/references/ref-6-10-post-openapi-drama-play-id-assets-asset-type-asset-id-general-candidates-cand-id-comments.md

6.11 PATCH /openapi/drama/{play_id}/assets/{asset_type}/{asset_id}/general/candidates/{cand_id}/comments/{comment_id}/resolve

将指定评论标记为已解决。

完整说明（参数表、请求/响应示例与错误处理）：{baseDir}/references/ref-6-11-patch-openapi-drama-play-id-assets-asset-type-asset-id-general-candidates-cand-id-comments.md

6.12 POST /openapi/drama/{play_id}/assets/{asset_type}/{asset_id}/general/references/create

为指定资产新建一张参考图（multipart/form-data 上传 name 与 image）。

完整说明（参数表、请求/响应示例与错误处理）：{baseDir}/references/ref-6-12-post-openapi-drama-play-id-assets-asset-type-asset-id-general-references-create.md

7. 分镜脚本管理 API

前缀：/openapi/drama/{play_id}/storyboard

7.1 GET /openapi/drama/{play_id}/storyboard/{episode_no}

获取某集分镜；尚未分析时 shots 为空。

完整说明（参数表、请求/响应示例与错误处理）：{baseDir}/references/ref-7-1-get-openapi-drama-play-id-storyboard-episode-no.md

7.2 POST /openapi/drama/{play_id}/storyboard/{episode_no}/analyze

触发该集分镜分析：读取该集剧本 → AI 拆分为镜头序列并关联资产。

完整说明（参数表、请求/响应示例与错误处理）：{baseDir}/references/ref-7-2-post-openapi-drama-play-id-storyboard-episode-no-analyze.md

7.3 GET /openapi/drama/{play_id}/storyboard/{episode_no}/shots/{shot_id}

获取单个镜头详情，包含 prompt、description、original_script / original_content。

完整说明（参数表、请求/响应示例与错误处理）：{baseDir}/references/ref-7-3-get-openapi-drama-play-id-storyboard-episode-no-shots-shot-id.md

7.4 POST /openapi/drama/{play_id}/storyboard/{episode_no}/shots/{shot_id}/add-asset

为镜头添加资产（补标），可新建或关联已有资产。

完整说明（参数表、请求/响应示例与错误处理）：{baseDir}/references/ref-7-4-post-openapi-drama-play-id-storyboard-episode-no-shots-shot-id-add-asset.md

7.5 POST /openapi/drama/{play_id}/storyboard/{episode_no}/shots/{shot_id}/optimize-prompt

生成或优化分镜视频合成的提示词（专门针对SD2.0智能参考视频生成模式）。

完整说明（参数表、请求/响应示例与错误处理）：{baseDir}/references/ref-7-5-post-openapi-drama-play-id-storyboard-episode-no-shots-shot-id-optimize-prompt.md

7.6 DELETE /openapi/drama/{play_id}/storyboard/{episode_no}/shots/{shot_id}

删除指定镜头。

完整说明（参数表、请求/响应示例与错误处理）：{baseDir}/references/ref-7-6-delete-openapi-drama-play-id-storyboard-episode-no-shots-shot-id.md

8. 参考资产图片生成分镜视频 API

前缀：/openapi/drama/{play_id}/storyboard-video

8.1 POST /openapi/drama/{play_id}/storyboard-video/episodes/{episode_no}/shots/{shot_id}/tasks

创建分镜视频生成任务（异步入队）

完整说明（参数表、请求/响应示例与错误处理）：{baseDir}/references/ref-8-1-post-openapi-drama-play-id-storyboard-video-episodes-episode-no-shots-shot-id-tasks.md

8.2 GET /openapi/api/ai-tasks/tasks/

查询 AI 任务状态与最终执行结果（异步任务通用）

完整说明（参数表、请求/响应示例与错误处理）：{baseDir}/references/ref-8-2-get-openapi-api-ai-tasks-tasks-task-id.md

9. 关键术语和字段解释

• play_id：剧目 ID，对应一个短剧项目。

• episode_no：集号，从 1 开始。

• shot_id：分镜中的单个镜头 ID。

• 资产类型：

  值	含义
  1	场景
  2	角色
  3	道具
  4	平面
  5	其他

• source_episode_nos：资产首次出现的集号列表。

• candidate：候选图（五官图或造型图），通常与提示词和模型配置绑定。

• reference：参考图，常用作造型/场景风格的视觉参考。

10. 实践案例概览

10.1 从零开始一个短剧项目（剧目 + 剧本 + 资产 + 分镜）

1. 认证（§2）：让用户在 https://idrama.lingban.cn/api-token 页面登录并复制 Token，或通过 POST /openapi/uaa/oauth/token 登录获取 access_token。
2. 创建剧目（§4.2）：POST /openapi/drama/create，请求体 {"name": "新剧本名称"}，获得 play_id。
3. 查看或更新风格配置（§4.11/4.12）：GET /openapi/drama/{play_id}/style-config 查看，PUT /openapi/drama/{play_id}/style-config 更新默认风格。
4. 上传剧本（§5.2）：POST /openapi/drama/{play_id}/scripts/upload 上传剧本文件/粘贴剧本文本。
5. 查看剧本集列表（§5.1）：GET /openapi/drama/{play_id}/scripts 确认各集上传情况。
6. 按集读取剧本内容（§5.3）：GET /openapi/drama/{play_id}/scripts/{episode_no}/content 查看某集原文。
7. 剧本资产智能分析（§5.5）：POST /openapi/drama/{play_id}/scripts/analyze，从剧本抽取人物/场景/道具并写入资产库。
8. 查看资产列表（§6.1）：GET /openapi/drama/{play_id}/assets/list，可按 type、episode_no、name 过滤。
9. 创建资产（§6.2）：若需手工补充资产，POST /openapi/drama/{play_id}/assets/create，传入 type、name（及可选 description）。
10. 生成资产图像提示词（§6.5）：POST /openapi/drama/{play_id}/assets/prompt-helper/generate；将 generated_prompt 通过 §6.4 PUT .../assets/{asset_id} 写入 prompt / prompt_by_mode。
11. 生成资产图像（§6.6）：POST /openapi/drama/{play_id}/assets/{asset_type}/{asset_id}/generate_image，按接口要求传入提示词与参考图等参数，生成新图并挂接到该资产。
12. 分析生成/更新分镜（§7.2）：POST /openapi/drama/{play_id}/storyboard/{episode_no}/analyze 基于剧本/资产生成分镜结构与镜头信息。
13. 按集查看分镜（§7.1）：GET /openapi/drama/{play_id}/storyboard/{episode_no} 获取该集分镜结构（若不存在可先执行下一步分析生成）。
14. 查看镜头详情（§7.3）：GET /openapi/drama/{play_id}/storyboard/{episode_no}/shots/{shot_id} 获取单镜头字段、已绑定资产等信息。
15. 为镜头绑定资产（§7.4）：POST /openapi/drama/{play_id}/storyboard/{episode_no}/shots/{shot_id}/add-asset 将角色/场景/道具等资产关联到镜头。
16. 生成和优化分镜提示词（§7.5）：POST /openapi/drama/{play_id}/storyboard/{episode_no}/shots/{shot_id}/optimize-prompt 在当前提示词基础上做 AI 优化，并按需回写（save=true/false）。
17. 生成分镜视频（§8.1）：POST /openapi/drama/{play_id}/storyboard-video/episodes/{episode_no}/shots/{shot_id}/tasks 创建任务；按文档约定轮询/订阅任务状态直至完成。
18. 查看剧目统计（§4.8）：GET /openapi/drama/{play_id}/stats 获取集数、镜头数、资产数量等。

10.2 按集查看、读取与删除剧本（§5）

1. 剧本集列表：GET /openapi/drama/{play_id}/scripts 获取所有剧集及文件名、标题、上传时间。
2. 某集剧本内容：GET /openapi/drama/{play_id}/scripts/{episode_no}/content 获取该集原文。
3. 删除某集剧本：DELETE /openapi/drama/{play_id}/scripts/{episode_no} 删除指定集（需确认该集不再用于分析或已备份）。

10.3 查看剧目统计与风格配置（§4）

1. 单个剧目详情：GET /openapi/drama/{play_id} 获取剧目名称、删除状态、操作时间。
2. 剧目统计信息：GET /openapi/drama/{play_id}/stats 获取集数、镜头数、预估时长、各类型资产数量。
3. 当前风格配置：GET /openapi/drama/{play_id}/style-config 获取 selected_style_key 与 styles。
4. 更新风格配置：PUT /openapi/drama/{play_id}/style-config，请求体传入 selected_style_key 和/或 styles。

10.4 资产列表、详情与基于参考图生成图像（§6）

1. 按条件查资产：GET /openapi/drama/{play_id}/assets/list，可用查询参数 type（1 场景/2 角色/3 道具/4 平面/5 其他）、episode_no、name、include_deleted 过滤。
2. 单个资产详情：GET /openapi/drama/{play_id}/assets/{asset_id}（§6.3）获取该资产元数据、提示词字段、候选图 URL 等。
3. 创建资产：POST /openapi/drama/{play_id}/assets/create（§6.2），传入 type、name，可选 description。
4. 更新资产：PUT /openapi/drama/{play_id}/assets/{asset_id}（§6.4），可更新名称、类型、prompt、prompt_by_mode、生图配置、画布字段等（至少传一项）。
5. 生成资产图像提示词（§6.5）：POST /openapi/drama/{play_id}/assets/prompt-helper/generate；可将返回的 generated_prompt 再通过 §6.4 写入资产。
6. 生成资产图像（§6.6）：POST /openapi/drama/{play_id}/assets/{asset_type}/{asset_id}/generate_image，按接口要求传入提示词与参考图等参数，生成新图并挂接到该资产。

10.5 分镜脚本：按集生成、查看镜头并绑定资产（§7）

1. 读取某集分镜：GET /openapi/drama/{play_id}/storyboard/{episode_no} 获取分镜结构与镜头列表。
2. 生成/更新分镜：若分镜为空或需要重算，POST /openapi/drama/{play_id}/storyboard/{episode_no}/analyze 进行分析生成。
3. 查看镜头详情：GET /openapi/drama/{play_id}/storyboard/{episode_no}/shots/{shot_id} 获取镜头信息、提示词、已绑定资产等。
4. 为镜头添加资产：POST /openapi/drama/{play_id}/storyboard/{episode_no}/shots/{shot_id}/add-asset 绑定角色/场景/道具等（建议先用 §6 的资产列表/详情确认 asset_id）。
5. 生成和优化分镜提示词：POST /openapi/drama/{play_id}/storyboard/{episode_no}/shots/{shot_id}/optimize-prompt 优化镜头提示词，并按需回写（save=true）。
6. 删除镜头（谨慎）：若需移除镜头，DELETE /openapi/drama/{play_id}/storyboard/{episode_no}/shots/{shot_id}（建议先确认是否已关联生成任务或引用资源）。

10.6 分镜出图与视频：任务生成（§8）

1. 创建分镜视频生成任务：POST /openapi/drama/{play_id}/storyboard-video/episodes/{episode_no}/shots/{shot_id}/tasks 发起该镜头视频生成任务。
2. 查询任务结果：按照 §8.1 的返回结构与状态字段轮询/订阅，直到 completed 并取得 result_video_path（或失败时按 status/msg 提示处理）。