跳到主要内容

完整入门教程

本教程带你从零开始部署 Sowall AI Studio，并完成第一条可预览、可回滚、可导出的 AI 视频。

你将完成什么​

完成教程后，你将能够：

  1. 使用 Docker 启动 Sowall AI Studio；
  2. 登录工作台并配置模型供应商；
  3. 创建小说、成品剧本或广告短片项目；
  4. 生成角色、场景、道具、分镜和视频片段；
  5. 查看任务状态和费用；
  6. 合成剧情演绎成片，或导出草稿和生成片段继续后期。

预计时间与费用​

  • 首次部署和配置通常需要约 10～20 分钟。
  • 视频生成耗时取决于分镜数量、供应商排队和所选模型。
  • 文本、图片、视频和 TTS 调用可能产生第三方 API 费用。
  • Sowall AI Studio 可以在生成前提供费用预估，并在生成后记录实际调用量。

建议第一次只使用少量内容和 2～4 个分镜验证流程，不要直接提交完整长篇项目。

1. 准备环境​

1.1 系统要求​

推荐环境：

  • Linux
  • macOS
  • Windows + WSL2
  • Docker Desktop

建议准备：

  • Docker
  • Docker Compose
  • 建议从 2 GB 可用内存起步
  • 可访问所选模型供应商的网络环境
  • 足够的磁盘空间保存图片、视频、项目归档和日志

默认工作流使用远程模型 API，通常不要求本机 GPU。接入本地模型服务时，CPU、GPU 和内存要求由该服务决定。

1.2 准备模型凭据​

Sowall AI Studio 中有两类凭据，职责不同。

Agent 凭据​

Agent（智能体）用于驱动项目对话、内容理解、角色提取、分集规划和工作流编排。

可使用 Anthropic 官方服务或 Sowall AI Studio 支持的兼容服务，并按需配置 Base URL 和模型名称。

媒体与文本生成凭据​

用于实际调用文本、图像、视频和 TTS 模型。

Sowall AI Studio 当前支持的预置供应商包括：

  • Sowall（默认预置供应商）
  • Gemini（AI Studio）
  • Vertex AI
  • 火山方舟
  • 火山方舟 Agent Plan
  • Grok
  • OpenAI
  • Vidu
  • 阿里百炼
  • MiniMax
  • 可灵 Kling
  • Agnes
  • 自定义 OpenAI 兼容或 Google 兼容供应商

不同供应商支持的媒体类型不同。完整流程通常至少需要：

  • 一个可用的文本生成能力；
  • 一个可用的图像生成能力；
  • 一个可用的视频生成能力；
  • 可选的 TTS 能力。

详细选择建议见 供应商与模型配置。

API Key 属于敏感信息。不要把真实密钥提交到 Git、Issue、日志截图或公开聊天记录中。

2. 部署 Sowall AI Studio​

2.1 克隆项目​

git clone http://192.168.0.39/token/puheai-studio.git
cd puheai-studio

2.2 使用 SQLite 默认部署​

默认部署适合首次体验、个人创作和轻量使用。

cd deploy
cp .env.example .env

编辑 .env：

AUTH_USERNAME=admin
AUTH_PASSWORD=请设置一个强密码
AUTH_TOKEN_SECRET=请设置一个长期固定的随机密钥

AUTH_TOKEN_SECRET 可以使用以下命令生成：

openssl rand -hex 32

启动：

docker compose up -d

检查状态：

docker compose ps
docker compose logs --tail=100 puheai-studio
curl http://localhost:1241/health

健康检查返回成功后，在浏览器打开：

http://localhost:1241

AUTH_PASSWORD 留空时，首次启动会自动生成密码并回写到 .env。正式使用时仍建议主动设置强密码并妥善保存。

2.3 使用 PostgreSQL 生产部署​

长期运行、并发访问或正式服务建议使用 PostgreSQL。PostgreSQL 改善并发、备份与运维能力，但不提供用户隔离；请勿让互不信任的用户共享同一 Sowall AI Studio 实例：

以下命令从 Sowall AI Studio 仓库根目录执行：

cd deploy/production
cp .env.example .env

编辑 .env：

AUTH_USERNAME=admin
AUTH_PASSWORD=请设置一个强密码
AUTH_TOKEN_SECRET=请设置一个长期固定的随机密钥
POSTGRES_PASSWORD=仅使用字母数字的数据库密码

启动：

docker compose up -d
docker compose ps
curl http://localhost:1241/health

本页只覆盖用户完成首次使用所需的步骤；服务器运维内容不属于公开用户手册。

3. 完成首次配置​

登录后，建议先完成首次使用引导并打开只读演示项目。它可以帮助你认识项目大厅、工作台、Agent 和设置入口，而不需要先消耗模型额度。

随后进入 设置 页面。

3.1 配置 Agent​

填写：

  • API Key 或凭证；
  • Base URL；
  • 主模型；
  • 按需要配置不同任务所使用的模型。

保存后先发送一条简单消息验证连接，不要直接开始大批量任务。

3.2 配置媒体供应商​

至少配置一个图像和一个视频供应商。

建议第一次使用以下策略：

  • 角色设计选择质量更稳定的图像模型；
  • 批量分镜选择速度和成本更均衡的图像模型；
  • 视频先选快速或低成本档位验证画面；
  • 确认角色、构图和运动方向后，再切换高质量模型。

3.3 配置并发和费用​

根据供应商配额调整：

  • RPM 限制；
  • 图像并发；
  • 视频并发；
  • 音频并发。

设置过高可能导致供应商限流，设置过低则会延长批量任务时间。初次使用建议保守设置，确认稳定后逐步提高。

4. 创建第一个项目​

在项目列表页点击 新建项目。

4.1 选择项目来源​

小说原文​

适合需要从原始内容开始进行角色提取、分集规划和剧本改编的项目。

建议第一次上传：

  • 一个完整但较短的章节；
  • 或者截取 1,000～3,000 字的剧情片段。

成品剧本​

适合已经拥有台词、画外音和场景结构，希望尽量保留原稿的项目。

Sowall AI Studio 会按照作者提供的内容建立角色和分镜，不应把成品剧本当作普通小说重新改写。

广告或短片​

适合商品展示、带货视频和目标时长明确的短内容。

准备：

  • 清晰的商品多角度照片；
  • 核心卖点；
  • 目标人群；
  • 期望时长和画面风格。

4.2 选择创作类型​

  • 旁白/解说：按朗读节奏组织片段，以旁白和画面为主。
  • 剧情演绎：按场景、角色和对话组织分镜。
  • 广告/短片：围绕目标时长、卖点和商品画面组织内容。

详细比较见 创作流程与模式。

5. 使用 Agent 推进工作流​

打开项目工作台右侧的 Agent 面板。

推荐按阶段推进，而不是一次要求“直接生成全部成片”。

5.1 内容分析​

让 Agent 分析：

  • 主要角色；
  • 重要场景；
  • 关键道具；
  • 剧情冲突；
  • 适合的分集边界。

审核重点：

  • 角色是否重复或漏掉；
  • 临时群演是否被错误建立为长期角色；
  • 关键物品是否需要跨分镜保持一致；
  • 分集边界是否完整，不要在关键动作中途切断。

5.2 分集和剧本​

确认内容分析后，生成当前要制作的剧集或短片脚本。

审核重点：

  • 单集是否拥有完整的小目标或情绪变化；
  • 台词和画外音是否忠于原文；
  • 分镜数量是否符合预算；
  • 每个分镜是否有清晰主体和动作；
  • 同一分镜是否塞入过多事件。

5.3 角色、场景和道具资产​

先生成主要角色设计，再生成关键场景和道具参考图。

审核重点：

  • 年龄、发型、服装、体型和气质是否准确；
  • 角色之间是否容易区分；
  • 参考图是否包含不希望后续复制的背景或文字；
  • 商品、标志和关键道具是否保持真实结构。

不要在角色资产尚未确认时批量生成全部分镜，否则后续返工会放大。

5.4 分镜图​

生成少量分镜验证：

  • 构图；
  • 人物位置；
  • 景别；
  • 光线和风格；
  • 角色与道具一致性；
  • 竖屏画面的安全区域。

确认方向后再批量生成。

每个分镜可以单独指定分镜图的分辨率档位：

  • 默认「跟随供应商默认」：提交请求时不带该参数，由供应商自己决定；
  • 选了档位就压过项目级设置，且只对这一个分镜生效；
  • 档位候选来自当前实际执行的模型声明；模型没有可选档位时，这个选择器不会出现。

5.5 视频片段​

根据项目选择生成模式：

  • 分镜图生视频（旁白/解说与剧情演绎项目可开启多宫格分镜）；
  • 参考生视频。

分镜图生视频开启多宫格分镜后，会先在一张或多张多宫格分镜中统一生成多个分镜，再切分为单分镜图，适合多分镜一致性要求较高的场景。

分镜与参考生视频单元都可以单独指定视频分辨率档位。未指定时依次跟随项目设置、系统设置与 当前模型规格；这些位置都没有值且模型没有声明时使用 720p。两点注意：

  • 部分模型在高分辨率下收窄可选时长，选了高档位后时长档位会相应变少，画布会提示当前秒数在当前分辨率下不可用；
  • 改档位等于改请求，已生成的片段会变为过期，需要重新生成。

审核重点：

  • 人物是否出现明显变形；
  • 动作是否符合分镜描述；
  • 运动方向是否在相邻分镜之间连续；
  • 视频结尾是否适合与下一分镜衔接；
  • 模型生成的音频是否与后期计划冲突。

5.6 旁白和 TTS​

旁白/解说项目可以逐段生成旁白配音：

  1. 在设置中选择 TTS 供应商；
  2. 设置音色和语速；
  3. 先试听一小段；
  4. 确认后批量生成；
  5. 检查专有名词、人物名和停顿。

6. 查看任务和费用​

生成任务会进入异步队列。

在任务监控中关注：

  • 排队中；
  • 运行中；
  • 成功；
  • 失败；
  • 取消。

遇到失败时，先查看失败原因，不要立刻连续重试。常见原因包括：

  • API Key 无效；
  • 额度不足；
  • 供应商限流；
  • 参数不被当前模型支持；
  • 网络超时；
  • 参考图数量或格式不符合要求。

在费用页面查看：

  • 预估费用；
  • 实际费用；
  • 文本、图像、视频和音频调用量；
  • 不同供应商和币种的统计。

7. 合成和导出​

7.1 剧情演绎合成最终视频​

分镜图生视频的剧情演绎（drama）项目确认所有视频片段后，可以使用 Sowall AI Studio 合成成片。分镜图生视频的旁白/解说和广告/短片项目请导出剪映草稿；参考生视频项目请下载生成片段继续后期。

建议在合成前检查：

  • 片段顺序；
  • 画面比例；
  • 每个片段的实际时长；
  • 旁白和画面的对齐；
  • 是否需要背景音乐；
  • 相邻分镜是否需要转场。

7.2 导出剪映草稿或生成片段​

分镜图生视频的旁白/解说和广告/短片项目通过剪映草稿完成成片；剧情演绎需要继续处理字幕、音轨、转场和节奏时也可以使用。参考生视频项目可以下载已生成的视频片段，进入剪映或其他后期工具继续制作。

详细步骤见 剪映草稿导出指南。

8. 第一次项目的完成标准​

不要以“所有素材都生成过”为完成标准。建议至少达到：

  • 角色设计已审核；
  • 关键道具和场景参考已审核；
  • 分镜结构合理；
  • 相邻分镜主体和运动方向可衔接；
  • 视频片段没有明显崩坏；
  • 费用在预期范围内；
  • 项目可以成功合成或导出；
  • 项目完成一次备份或归档。

9. 下一步​