• 人工智能
• AI 应用
• 大模型
• 多模态
• 媒体生成
• 音视频
• AI Agent
• AI 技能

TapCanvas 是一款完全开源的 Agent 原生无限画布，面向 AI 影视、漫剧与多模态内容生产。它把文本、图像、视频和音频模型统一交给内置的鲁班 API 多模型网关（apps/new-api）接入、计量与动态下发——前端不写死任何模型列表，你在网关管理台配置好渠道与模型，画布即可"一键成片"。本文带你从零完成 TapCanvas 模型配置：启动部署、看懂网关架构、认识预置模型目录，再到图像/视频模型的逐项配置与常见问题排查。

一分钟理解：TapCanvas 为什么用"模型网关"

很多 AI 创作工具把模型列表硬编码在前端，换一家供应商就要改代码。TapCanvas 采用了完全不同的思路：

• 统一目录：所有可执行的文本、图像、视频模型，都来自网关管理台的"动态模型目录"，前端按需拉取；
• 统一计量：按 token、按张、按秒计费，价格快照来自网关实时接口；
• 显式失败：模型未启用、渠道缺 Key、规格不支持时直接报错，不做静默降级，也不会自动换模型。

这意味着"配置模型"这件事只发生在网关管理台一处，画布、AI 对话（小T）和一键成片工作流全部自动生效。

一键部署：三步启动 TapCanvas 全栈

只需 Docker、Docker Compose 和 OpenSSL，不需要在宿主机安装 Node.js、pnpm 或 Go。

git clone https://gitcode.com/anymouschina/TapCanvas cd TapCanvas ./scripts/dev.sh docker

脚本会自动生成一套强随机本地密钥写入apps/hono-api/.env（不打印、不提交 Git），并逐个构建 Web、API、鲁班 API 网关、Agents Bridge 与后台 Workers。首次冷构建耗时较长，属正常现象。

启动完成后，记下三个入口：

完整部署细节见 Docker 配置指南。

💡 首次进入 Web 会弹出"首次启动检查"：如果网关里没有已启用的模型和可用渠道，会显示"先配置一个可用模型渠道"，并提供跳转到网关配置页的按钮。看到它，说明一切正常，接下来就是配置模型。

内置模型渠道：开箱即用的 20 个预置模型

全新部署的网关由数据补丁自动初始化，无需手工粘贴 Key 即可体验（详见 补丁说明）：

• 供应商：Lluban API（OpenAI 兼容中继）
• 渠道：lluban-recommended共享渠道
• 20 个可执行目录模型：10 个图像、4 个视频、6 个文本/对话，均带真实路由与定价

图像模型目录（示例）：

视频模型目录：

文本模型包括deepseek-v4-flash（1M 上下文、双模推理，也承担 AI 对话与内容安全预检）以及多个 GPT 系列。

⚠️ 网关启动时会从渠道上游同步最新模型目录与定价（见 patches README），所以你在管理台看到的模型以实时目录为准；新发现的模型必须先补齐元数据与价格才会进入可选项，避免把未验证路由伪装成可用模型。

进阶渠道：HeyRoute 与 Factory/Droid 号池

除了内置推荐渠道，社区版还预置了两类进阶渠道（默认停用、Key 为空，需填自己的 Key 后启用）：

• HeyRoute：7 个渠道、共 31 个模型——15 个对话（Claude、GPT、Grok、Gemini、Kimi）、5 个图像（gpt-image-2、Flux、Grok Imagine 等）、11 个视频（Grok 系、MiniMax H3 多档、Seedance 系）。在渠道列表点"申请 API Key"完成注册后填 Key 启用即可，说明见 HeyRoute 接入文档；
• Factory / Droid 号池：支持批量追加 Key、账号启停与单号测试、Standard/Core 额度窗口、订阅展示，以及额度不足时同池换号重试，说明见 Droid 接入文档。

预置渠道的初始 SQL 位于 004-expand-heyroute-channels.sql 与 005-bootstrap-droid-factory-channel.sql，可重复执行，不会覆盖你已填的 Key 与启停状态。

核心操作：在鲁班 API 管理台配置模型渠道

打开http://localhost:4455进入鲁班 API 管理台，模型配置遵循一条固定动线：渠道（Channel）→ 模型（Model）→ 能力（Ability）→ 价格（Pricing）。

第 1 步：渠道配置

进入渠道列表，找到推荐渠道lluban-recommended（或新建渠道）：

1. 填入模型供应商的API Key（内置推荐渠道已带公开分发凭证，可直接使用）；
2. 确认Base URL（如https://tt-api.lluban.com）与协议端点正确；
3. 保存后启用渠道。渠道被禁用或 Key 被清空时，前端会回到强制配置引导。

第 2 步：模型与能力

在模型管理中：

1. 确认目标模型的kind（image / video / text）与协议端点（如openai、openai-video、image-generation）；
2. 在default分组下启用对应ability——渠道启用 + 模型启用 + ability 启用三者齐全，模型才进入"可执行目录"；
3. 检查params_def声明的规格（宽高比、分辨率、时长、参考图上限等），这些规格会原样投影到画布的下拉选项。

第 3 步：价格与计量

• 文本按输入/输出/缓存 token 计价；图像按张 + 规格计价；视频按分辨率与实际提交秒数计价；
• 公开价格接口提供channel_text_prices、channel_image_prices、channel_video_prices三类渠道独立报价；
• 例如gpt-image-2使用image:{1k|2k|4k}:{low|medium|high}九档计费合同，每张参考图另计。

🔑 定价原则与倍率机制详见 模型渠道计价原则。

验证配置是否生效

回到 Web（http://localhost:5175），点击"首次启动检查"里的重新检查。面板会显示三个数字：

• 启用模型：模型目录中启用的数量；
• 可用渠道：已配置有效 Key 的渠道数；
• 可执行模型：真正形成"渠道 × 模型 × ability"完整路由的数量。

三者均大于 0，页面自动放行，画布里的生图/生视频/对话模型下拉框就会填充动态目录。

动态模型目录：配置一次，处处生效

这是 TapCanvas 最值得理解的机制之一，规则写在 agents-cli 架构文档 中：

所有前端/对话中的"模型可选列表"必须来自系统模型管理（model catalog / vendor 配置）的动态数据；禁止写死模型枚举作为可选来源。

具体到使用体验：

• 小T 对话：发送前会等待真实目录加载，按你保存的目录顺序选择文本模型；目录为空或加载失败会显式阻止发送，而不是悄悄用默认模型；
• 图像节点：按所选模型目录提交的规格（比例/尺寸/质量）计算报价，同一质量值同时进入预估、请求与结算；
• 一键成片：从流水线选择章节后，触发器按实时目录的durationOptions（如 5/10/15 秒档位）与分辨率/画幅选项冻结生成合同；目录外规格会在付费提交前原地报错；
• 子代理继承：主代理创建的子代理继承本轮实际生效的模型配置，继承失败会显式报错，不回落到默认模型。

常见问题排查（FAQ）

Q1：Web 一直提示"先配置一个可用模型渠道"？依次核对：渠道是否启用 → Key 是否有效 → 模型 ability 是否启用 → 网关能否连通上游。前端的就绪检查读取的就是这四类真实事实，缺任何一项都不会放行（实现见 NewApiSetupGate.tsx）。

Q2：目录里明明有模型，为什么不可选？"有名称"不等于"可执行"。只有同时具备真实路由、完整元数据和正价格快照的模型才进入可执行目录；仅有名称的未验证路由会被显式排除。

Q3：生成时提示模型不支持某个规格？规格（分辨率、画幅、时长）以所选模型的实时params_def为准。网关不会自动改成另一个规格，也不会静默降级——请从下拉选项中重选一个合法档位。

Q4：改了渠道 Key 或启停状态，会随升级被覆盖吗？不会。所有补丁重复执行时都保留管理员替换过的 Key 与渠道启停状态，只维护结构性字段（见 补丁失败策略）。

Q5：多个渠道都能跑同一个模型，怎么计费？按实际路由命中的渠道结算：文本走该渠道的输入/输出/缓存单价，图像按渠道规格与实际张数，视频按渠道分辨率与提交秒数。

参考路径速查

配置完成后，从章节或正文节点进入"一键成片"，选择已启用的文本、图像与视频模型，TapCanvas 的 Agents 就会沿着"剧本 → 角色与场景 → 分镜 → 视频片段 → 最终成片"的流水线，把长篇小说变成可交付的成片。

• 人工智能
• AI 应用
• 大模型
• 多模态
• 媒体生成
• 音视频
• AI Agent
• AI 技能