智剧通（ZJT）文档中心 网格图片生成

宫格图片生成功能文档

功能概述

宫格图片生成功能允许用户在剧本节点或幕节点中一键生成4宫格或9宫格的分镜图片，系统会自动拆分并分配到各个分镜节点。

支持的节点类型

  1. 剧本节点: 点击"拆分幕 + 宫格生图"按钮，系统会自动解析剧本、创建幕和分镜节点，并生成宫格图片
  2. 幕节点: 点击"宫格生图"按钮，为该幕下的所有分镜节点批量生成宫格图片

幕节点不在"添加节点"菜单中提供手动新建入口，只能由剧本节点解析/拆分后自动创建；工作流重新加载时仍会恢复已保存的幕节点。

使用流程

1. 准备剧本

在剧本节点中输入或上传剧本内容。

2. 选择宫格模型

剧本节点和幕节点的宫格生图模型默认使用 标准版（默认模型）。原有"智能模式"入口已删除，旧工作流中保存的智能模式标识会在重新加载后迁移为标准版（默认模型）。

仍可在下拉框中选择其他支持宫格生图的模型，例如：

3. 点击"拆分幕 + 宫格生图"

系统会自动执行以下步骤：

  1. 调用大语言模型解析剧本，生成幕和分镜节点
  2. 收集参考图片（角色、场景、道具）
  3. 统计分镜数量和参考图片数量，决定使用4宫格还是9宫格
  4. 预估算力消耗
  5. 弹出确认对话框，显示生成信息（包括参考图片数量）
  6. 并行调用图片编辑能力生成宫格图片（如有参考图片则传递）
  7. 为每个分镜节点创建分镜图子节点

4. 自动同步

系统使用两阶段轮询机制：

第一阶段：任务完成轮询（每10秒检查一次）

第二阶段：节点状态轮询（每60秒或立即触发）

幕节点宫格生图

使用场景

当你已经有幕节点时，可以直接使用幕节点的宫格生图功能，无需从剧本节点重新开始。

使用步骤

  1. 选择宫格生图模型
  1. 点击"宫格生图"按钮
  1. 确认生成信息
  1. 等待生成完成

注意事项

参考图片收集

宫格生图会自动收集所有分镜中涉及的参考图片：

  1. 角色参考图: 从分镜提示词中提取用【【】】标记的角色名，查询相关数据表获取参考图
  2. 场景参考图: 根据分镜关联的场景ID，查询相关数据表获取场景参考图
  3. 道具参考图: 根据分镜中出现的道具，查询相关数据表获取道具参考图

注意事项：

宫格选择逻辑

系统会根据分镜数量自动选择宫格类型；模型默认使用标准版（默认模型），除非用户在下拉框中显式选择其他模型：

算力计算

算力按实际使用量计费，具体定价以产品页为准。确认对话框中会展示预计消耗，供用户参考。

提示词格式

系统会将分镜的图片提示词拼接成JSON格式：

4宫格示例

{
  "grid_layout": "2x2",
  "grid_aspect_ratio": "16:9",
  "grid_structure": "2 rows x 2 columns",
  "cell_aspect_ratio": "16:9",
  "style_guidance": "<系统生成的版式与风格约束文本>",
  "art_style": "赛博朋克风格",
  "shots": [
    {"shot_number": "1 (Top-Left)", "prompt_text": "**[Panel 1 of 4: Top-Left Quadrant]**\n<Subject>: 清晨的城市街道，阳光洒在建筑物上\n<Composition>: Cinematic 16:9 Wide framing."},
    {"shot_number": "2 (Top-Right)", "prompt_text": "**[Panel 2 of 4: Top-Right Quadrant]**\n<Subject>: 咖啡店内部，温暖的灯光\n<Composition>: ..."},
    {"shot_number": "3 (Bottom-Left)", "prompt_text": "..."},
    {"shot_number": "4 (Bottom-Right)", "prompt_text": "..."}
  ]
}

其中 style_guidance 为系统生成的风格约束文本（要求全图统一画风、不带文字编号等），具体文案不在此列出；art_style 仅在用户设置了画风时包含。

9宫格示例

{
  "grid_layout": "3x3",
  "grid_aspect_ratio": "16:9",
  "grid_structure": "3 rows x 3 columns",
  "cell_aspect_ratio": "16:9",
  "style_guidance": "<系统生成的版式与风格约束文本>",
  "art_style": "水墨画风格",
  "shots": [
    {"shot_number": "1 (Top-Left)", "prompt_text": "..."},
    {"shot_number": "2 (Top-Center)", "prompt_text": "..."},
    ...
    {"shot_number": "9 (Bottom-Right)", "prompt_text": "..."}
  ]
}

图片填充逻辑

重要：当分镜数量不足填满宫格时（例如5个分镜使用4宫格，第二张图只有1个分镜），系统会自动复制最后一个分镜的提示词填充剩余格子；若最后一个分镜没有可用提示词，则回退到固定的默认场景提示词。

示例：5个分镜使用4宫格

这样可以确保：

  1. 内容可控：复用最后一个分镜的提示词，避免模型对空缺格子随机填充内容
  2. 兜底提示词：无可用分镜提示词时回退到固定默认提示词，保证每个格子都有明确输入
  3. 尺寸正确：保持宫格结构完整，确保拆分后的图片尺寸正确

节点类型

图片节点（宫格生图）

宫格生图现在使用标准的图片节点（image类型），拥有完整的图片功能（上传、编辑、下载等）。

节点数据结构： 

{
  type: 'image',
  title: '分镜图 1/4',
  data: {
    name: '分镜图 1/4',
    aiToolsId: 12345,         // 关联的AI工具ID
    project_id: 12345,        // 关联的AI工具ID
    gridIndex: 1,             // 在宫格中的位置（1-4或1-9）
    gridSize: 4,              // 宫格大小（4或9）
    url: '/upload/...',       // 拆分后的图片URL（拆分完成前为空）
    preview: '/upload/...',   // 预览图片URL（拆分完成前为空）
    isSplit: true,            // 宫格拆分节点标记（创建时即为true）
    status: 'completed',      // 状态：pending→splitting→completed/failed
    shotFrameNodeId: 678,     // 父分镜节点ID
    // 标准图片节点属性
    file: null,
    prompt: '',
    ratio: '16:9',
    model: '<图像生成模型标识>',
    drawCount: 1
  }
}

图片节点功能：

API接口

1. 获取宫格拆分图片

GET /api/ai-tools/{ai_tools_id}/grid-split?grid_index={index}&user_id={user_id}

参数：

响应：

拆分成功： 

{
  "code": 0,
  "message": "获取成功",
  "data": {
    "image_url": "/upload/workflow/1/grid_split/12345/1.png",
    "grid_index": 1,
    "grid_size": 4
  }
}

处理中（AI 任务进行中，或其他 worker 正在下载/拆分）： 

{
  "code": 1,
  "message": "拆分处理中，请稍后重试"
}

前端收到 code:1 时不计入失败次数，下次轮询自动重试。

2. 查询AI工具状态

GET /api/get-status/{ai_tool_id}

响应： 

{
  "code": 0,
  "message": "获取成功",
  "data": {
    "id": 12345,
    "status": 2,           // 0=待处理, 1=处理中, 2=已完成, 3=失败
    "type": 7,             // 1=标准版, 7=加强版
    "result_url": "...",
    "message": null
  }
}

文件存储路径

拆分后的图片会被缓存，重复请求会直接返回缓存的图片。

技术实现

轮询与拆分机制

宫格图片生成使用两阶段机制：

图片大小

注意事项

  1. 算力消耗: 宫格生图会消耗算力，请确保账户有足够的算力
  2. 分镜数量: 只有1个分镜时不会生成宫格图片
  3. 模型限制: 标准版只支持4宫格，参考图片数量>5张时会自动切换到加强版
  4. 并行生成: 多张宫格图片会并行生成，提高效率
  5. 自动同步: 复用现有轮询机制，每10秒检查一次，无需手动刷新
  6. 4K输出: 加强版模型自动使用4K分辨率，确保图片质量
  7. 画风传递: 如果用户设置了画风，所有生图入口（分镜节点、幕节点、剧本节点）都会自动将画风信息传递到提示词中。分镜节点通过 图片风格：xxx 追加到 prompt 末尾，多宫格生图通过 JSON 中的 art_style 字段传递

分镜节点顺序

当通过"拆分幕"或"拆分幕 + 宫格生图"功能生成分镜节点时，系统会确保分镜节点按照 shot_number 字段从小到大依次排列（从上到下），保证镜头一、镜头二等按顺序显示。

实现细节

  1. 幕 Y 间距动态计算：创建幕节点时，根据每个幕内的分镜数量动态计算 Y 偏移量，避免不同幕的分镜节点在垂直方向交错。
  2. 分镜排序：创建分镜节点前对分镜数组按 shot_number 排序，确保组内分镜顺序正确。

故障排查

问题：宫格图已生成但未被拆分

已彻底重构：

问题：分镜图节点一直显示"等待生成..."

可能原因：

  1. AI工具生成失败
  2. 网络问题导致轮询失败
  3. 后端拆分接口异常

解决方法：

  1. 检查浏览器控制台的错误日志
  2. 手动刷新页面重新加载工作流
  3. 检查后端错误日志

问题：拆分后的图片无法显示

可能原因：

  1. 图片路径错误
  2. 文件权限问题
  3. 原始宫格图不存在

解决方法：

  1. 检查 upload/workflow/{user_id}/grid_split/ 目录是否存在
  2. 检查文件权限是否正确
  3. 查看后端日志确认拆分是否成功

问题：图片拆分失败或切分后图片不完整

根本原因：

图片库打开图片时默认惰性加载，只读取文件头而不加载像素数据，实际裁剪时才读取像素。若此时出现 IO 问题（并发访问、文件句柄等），像素数据可能不完整，导致切分后的图片只有一半或出现黑色/灰色区域。

系统处理（已修复并进一步重构）：

  1. 强制加载：打开图片后立即强制加载全部像素数据到内存，确保裁剪时数据完整
  2. 下载验证：下载原图后在线程池中执行写入+验证，不阻塞事件循环
  3. 原子写入：下载图片时先写入临时文件，校验通过后再原子重命名为目标文件
  4. 文件锁保护：确保同一 AI 工具 ID 只有一个 worker 进程执行下载+拆分，避免重复下载
  5. 损坏清理：校验失败时自动清理临时文件，不会留下损坏的缓存

手动解决方法：

  1. 删除损坏的切分缓存：rm -rf upload/workflow/{user_id}/grid_split/{ai_tools_id}/
  2. 重新访问图片URL或调用拆分接口，系统会自动重新切分

自动切分机制：

直接访问图片URL（如 /upload/workflow/{user_id}/grid_split/{ai_tools_id}/{grid_index}.png）时，如果文件不存在，系统会自动触发切分逻辑，无需手动调用API。

相关文件