角色圣经与资产版本
本文属于“当前架构”,描述 P4 / C7 已落地的实现。 受影响镜头分析见 资产变更影响分析。 16:9 角色设定板见 角色设定板。 P3 剧本确认产生的资产见 剧本结构化解析与统一审核。
1. 概念边界
| 概念 | 数据 | 说明 |
|---|---|---|
| 角色身份 | characters + asset_versions(version_kind=identity) | 剧情中的同一个人;正式名称、别名、基础外貌、身份版本、锁定状态 |
| 演员 | actors | 工作区级共享资源;可被多个项目角色绑定,不能因项目角色锁定而冻结 |
| 角色造型 | asset_versions(version_kind=appearance) | 同一角色的服装/发型/妆容/年龄/环境状态变体;不改变身份 |
| 资产基础版本 | asset_versions(version_kind=base) | Scene/Prop/Costume 的当前基础快照 |
| 资产衍生版本 | asset_versions(version_kind=derived) | 夜景、雨淋、破损、灯光变化等 |
| 图片候选 | asset_image_candidates | 一次生成或上传得到的图片;不等于已采纳 |
| 已采纳图片 | asset_image_candidates.is_adopted=true | 用户明确选中的图片;同一版本同一视角只保留一个 |
| 角色音色 | characters.voice_id / voice_source | 与视觉身份独立;未绑定视觉锁定不受影响 |
Character / Scene / Prop / Costume 仍是唯一业务主实体。版本通过
asset_type + asset_id 多态引用,不复制主实体,也不新增平行资产系统。
2. 数据模型
2.1 character_aliases
| 字段 | 说明 |
|---|---|
character_id | 指向稳定角色 ID |
alias | 原始称谓 |
normalized_alias | 去空白/小写后的匹配键 |
source | manual / p3_parse |
- 同一角色内别名唯一。
- 同项目不同角色使用相同别名时,服务端返回冲突,由人工确认是否合并角色;不做自动合并。
- P3 解析会读取项目正式别名做预匹配,并把候选别名补入角色。
2.2 asset_versions
| 字段 | 说明 |
|---|---|
asset_type / asset_id | character / scene / prop / costume |
version_no | 资产内递增版本号 |
parent_version_id | 衍生来源版本 |
version_kind | identity / appearance / base / derived |
variant_type | 兼容单值:base / costume / hairstyle / makeup / age / weather / lighting / other |
variant_types | 多选类型数组;旧数据为空时回退 variant_type,不设额外业务数量上限 |
name / description | 版本快照 |
attributes | 服装 ID、身份字段快照等 |
source | manual / generated / uploaded / p3_confirm |
status | draft / active / superseded |
当前指针:
characters.identity_version_id:当前视觉身份版本;characters.current_appearance_version_id:当前造型版本(可空);scenes.current_version_id/props.current_version_id/costumes.current_version_id:当前基础/衍生版本。
正式采纳版本不原地修改。切换版本只移动指针,旧版本保留为 superseded。
版本类型支持多选:variant_types 是权威数组,variant_type 取第一个值用于旧接口兼容。
例如同一版本可同时标记“发型 + 服装 + 年龄”。characters.tags 保存角色标签,
会进入角色卡提示词,也用于资产列表检索。
删除版本只允许未采纳、非当前/身份版本的草稿;已引用版本拒绝删除。
2.3 asset_image_candidates
| 字段 | 说明 |
|---|---|
asset_type / asset_id | 所属资产 |
asset_version_id | 归入哪个版本;采纳时仍可指定目标版本 |
candidate_batch_id | 一次生成(默认 1 张,手动可 2 张)共享批次 |
view_angle | FRONT / LEFT / RIGHT / BACK / THREE_QUARTER |
file_id | FileItem 图片文件 |
source | generated / uploaded |
generation_task_id | 现有 GenerationTask |
prompt / generation_params | 生成提示词、模型、比例、分辨率、image_kind |
status | pending / succeeded / failed / adopted / discarded |
is_adopted | 是否被采纳 |
generation_params 中:
target_ratio记录本次实际使用的比例;image_kind=character_card表示角色卡,character_angle表示补充视角;reference_warnings保存参考图缺失/不一致提示,前端必须展示。
图片文件仍保存为 FileItem(type=image);采用统一鉴权与对象存储,不保存临时 URL。
3. 图片生成与候选
- 复用现有资产图提示词渲染、项目图片模型、风格快照、比例/分辨率配置;
- 每次默认创建 1 个
GenerationTask,手动可生成 2 张;不假设供应商支持n=2; - 任务关联类型为
asset_image_candidate,relation_entity_id是候选行 ID; image_task_runner成功后回写候选file_id/status=succeeded,失败/取消写failed;- 用户重新抽卡只新增候选,不自动改变已采纳图片;
- 全局资产列表会附带
candidate_thumbnail/candidate_count/candidate_pending_count:未采纳的成功候选显示为「待选用」预览,生成中则显示「生成中」并轮询刷新;预览不等于当前图,仍需显式采纳; - 用户可上传图片作为同等级候选,
source=uploaded; - 采纳是显式动作:
- 同版本同视角其它候选取消
is_adopted; - 同步对应
CharacterImage/SceneImage/PropImage/CostumeImage槽位; - 不删除其它候选文件;
- 同版本同视角其它候选取消
- 已采纳候选不可删除。
4. 视觉身份锁定
前置条件:
- 角色名称非空;
- 基础外貌设定非空(
appearance或description); - 当前 identity 版本存在至少一张已采纳的
FRONT候选图。
音色不是锁定前置条件。
锁定后:
- 服务端拒绝直接修改
name、description、age_range、appearance、face_features、body_type、identity_features、identity_version_id; - 拒绝替换当前身份版本的正面已采纳图;
- 允许修改别名、音色、标签、造型版本、辅助视角、备注;
- 如需修改身份:创建新的 identity 草稿版本 → 采纳新的正面图 → 切换当前身份版本;旧版本保留;
identity_lock_version用于并发检查;切换身份版本时递增。
旧实体 PATCH 接口同样经过锁定校验,不能绕过前端禁用。
锁定是可选的资产保护动作,不是分镜规划、正式镜头应用或视频准备度的前置条件:
- 未锁定角色可以参与分镜规划、应用到正式镜头并进入视频生成;
- 未锁定角色的
identity_version_id/ 造型版本仍按资产当前版本参与参考图解析; - 锁定只用于阻止基础身份字段与当前身份正面图被直接覆盖。
5. 音色
继续沿用既有解析顺序:
显式 voice
→ characters.voice_id
→ 角色所绑 actors.voice_id
→ 未解析,配音 422P4 只增加人工绑定入口与最终生效来源展示;不新增音色克隆引擎、不复制音频任务。
角色音色变更不改变 identity_locked_at,也不自动开启项目级音频参考开关。
6. P3 衔接
- P3 确认创建的角色直接出现在工作台资产列表;
- 角色 aliases 从 P3 候选导入;冲突别名跳过并保留人工处理;
- P3 已填写的
appearance/age_range/body_type预填到角色圣经; - P3 重解析只关联已有角色,不覆盖人工维护的外貌、锁定字段或别名;
- 没有图片的角色可以存在,但不能锁定视觉身份。
7. API
| 方法 | 路径 | 说明 |
|---|---|---|
GET/PATCH | /api/v1/studio/projects/{pid}/assets/{type}/{aid}/profile | 资产档案 |
POST/PATCH/DELETE | .../assets/character/{aid}/aliases[/{alias_id}] | 别名维护 |
GET | .../assets/{type}/{aid}/versions | 版本历史 |
POST | .../assets/{type}/{aid}/versions | 创建衍生/造型版本 |
POST | .../assets/character/{aid}/identity-versions | 创建身份草稿 |
POST | .../assets/{type}/{aid}/versions/{vid}/switch | 切换当前版本 |
DELETE | .../assets/{type}/{aid}/versions/{vid} | 删除未引用草稿 |
GET | .../assets/{type}/{aid}/candidates | 候选列表 |
POST | .../assets/{type}/{aid}/candidates/generate | 生成候选(默认 1 张,最多 2 张) |
POST | .../assets/{type}/candidates/generate-batch | 多选批量生成;每项 1 张,跳过已有图片/生成中/待选用候选 |
POST | .../assets/{type}/{aid}/candidates/upload | 上传候选 |
POST | .../assets/{type}/{aid}/candidates/{cid}/adopt | 采纳候选 |
DELETE | .../assets/{type}/{aid}/candidates/{cid} | 删除未采纳候选 |
POST | .../assets/character/{aid}/lock | 锁定视觉身份 |
GET/PATCH | .../assets/character/{aid}/voice | 音色绑定与生效来源 |
所有接口按项目与工作区校验;编辑需要 editor。
7.1 批量生成规则
- 全局资产列表支持多选目标资产,调用
assets/{type}/candidates/generate-batch; - 每个资产固定生成 1 张候选,避免批量操作产生双倍费用;
- 批量任务先落库为 pending,再由独立
image_batchcoordinator 按projects.image_concurrency逐步入队; - 以下情况跳过并返回原因:
- 已有已采纳图片;
- 已有 pending 候选;
- 已有 succeeded 但未采纳的候选(先让用户选用,避免重复生成);
- 单项失败不影响其它资产;响应返回 generated/skipped/failed 数量与逐项原因。
8. 当前边界
- 不创建 P5 场次与镜头;
- 不建立 P6 镜头级有序参考绑定;
- 版本切换不自动改写历史镜头、分镜帧或视频;
- 角色默认只生成 16:9 正面全身角色卡;侧面/背面仅作为补充视角,不是默认流程;
- 多视角依赖现有资产图提示词与参考图能力;供应商不支持可靠参考图时应提示限制并允许手工上传;
- 真实图片生成仍受 P6 持久化额度门禁约束;P4 自动化测试使用 Mock。