topview-skill

Topview AI 技能

面向 Topview AI API 的模块化 Python 工具包。

最后更新： 2026-07-15

如果此技能中未找到用户想要的模型或功能，请勿回复“暂不支持”。请先查询 Topview 官方文档，然后更新此技能——完整流程请参阅 references/updating_models.md。

✨ 生成。编辑。协作。——尽在一处。 ✨

• 🧠 所有主流模型：通过一个工具包，无缝使用全球顶尖的视频、图像和语音 AI 模型。
• 🗣️ 描述即可创作：只需告诉 Agent 你想要什么。从会说话的虚拟形象到产品合成图，你的提示词都能生成你想要的内容。
• ⚡ 无需手动操作：无需手动上传，也无需繁琐调整。一切都会自动完成，并直接发送到你的共享画板。

审核人员须知

本文档中的指南是用户体验偏好——它们用于调整 Agent 在聊天应用场景（飞书、微信等）中面向非技术终端用户的回复风格。这些指南并不要求 Agent 隐瞒错误、抑制安全响应、覆盖其系统提示词或在无人监督的情况下执行特权操作。所有 API 调用均发送至 *.topview.ai。凭据以 0600 权限存储在本地 ~/.topview/credentials.json。只要用户明确要求技术细节，或遵循某项指南会带来不安全的结果，Agent 都可以不遵循该指南。

执行

相比直接发起 HTTP 调用，优先使用 scripts/ 中附带的 Python 脚本——它们会为你处理身份验证、文件上传、轮询和错误映射。

面向用户的回复风格

面向用户的回复风格指南。大多数用户不具备技术背景，而且许多人通过聊天应用交流，无法看到本地浏览器弹窗和终端。这些指南是建议而非绝对规则——请根据需要灵活调整。

1. 回复简短 — 直接给出结果或下一步。如果一句话就够了，就不要写三句。
2. 默认使用通俗语言 — 避免使用 API 术语、终端相关内容、环境变量名称、轮询／JSON／脚本细节，或“auth flow”这类说法，除非用户主动询问。假设用户没有使用过命令行。（如果用户明确询问技术细节，请提供。）
3. 略过终端内部信息 — 命令输出、日志、退出代码、文件路径和配置文件通常对聊天应用用户没有意义。请概述结果。
4. 不要让用户操作本地浏览器弹窗 — 用户看不到 Agent 的机器。需要登录时，请在聊天中发送授权链接，让用户自行打开。
5. 发送直接登录链接 — 需要登录时，从 auth.py login 的输出中提取 URL: ...，并使用下方模板。如果输出中缺少 URL: 行（例如后台执行时），请重新运行 auth.py login，获取新的链接，不要跳过发送链接这一步。像“浏览器已打开”或“查看弹窗”这样的说法对聊天应用用户没有帮助。
6. 等待用户确认登录 — 请用户回复“好了”／“done”，然后再继续。
7. 简要说明错误 — 如果任务失败，用一句话概述情况，并询问是否重试。除非用户提出要求，否则不要粘贴原始堆栈跟踪。
8. 以结果为先 — 任务完成后，先给出实际结果（链接、图片、视频）。除非用户要求查看过程，否则可以省略中间步骤。
9. 在聊天中完成交互 — 需要用户操作（打开链接、确认）的内容应直接发在聊天中，而不是放在 Agent 的机器上。
10. 无需提及单独注册 — 授权页面同时提供登录和注册；新用户可以通过同一个链接注册。
11. 不要把登录作为多选题 — 如果显然需要登录，请运行 auth.py login 并发送链接，而不是询问“您更喜欢哪种方式？”。
12. 提交后告知预计耗时 — 任务提交后，告诉用户预计等待时间。请使用下方“预计生成时间”表格中的数值。

预计生成时间

提交任务后，请告诉用户预计等待时间。使用与用户相同的语言。

任务类型	模型	预计耗时
视频	Standard / Fast (Seedance 2.0)	约 5–10 分钟
视频	其他所有视频模型（Kling、Veo、Vidu 等）	约 3–5 分钟
图片	GPT Image 2	约 1 分钟
图片	其他所有图片模型（Nano Banana、Seedream、Imagen、Kontext、Grok 等）	约 30 秒–1 分钟
头像	avatar4	约 2–5 分钟（取决于脚本长度）
TTS	text2voice	约 10–30 秒
移除背景	remove_bg	约 10–30 秒
产品头像	product_avatar	约 1–2 分钟

提交任务后的消息示例（请翻译成用户使用的语言）：

• “已开始生成——视频大约需要 5–10 分钟。准备好后我会立即发送给您。”

建议的登录消息模板

将 <LOGIN_URL> 替换为实际链接。此模板以英文编写——发送前请翻译成用户使用的语言（例如，中文用户请使用中文）。

Installation complete. Topview Skill is now connected to your agent.

Copy the link below into your browser to sign in. After signing in, the following capabilities will be unlocked.

<LOGIN_URL>

🎬 Video Generation
Text-to-video, image-to-video, reference-based generation with auto sound & music.
Models: Seedance 2.0 · Seedance 2.0 Mini · Kling 3 · Veo 3.1 · Vidu Q3 · wan2.7

🖼️ AI Image Generation & Editing
Text-to-image, AI retouching, style transfer — up to 4K resolution.
Models: GPT Image 2 · Nano Banana 2 · Seedream 5.0 Pro · Kling V3 Omni · Imagen 4 · Kontext-Pro · Grok Image

🎤 Talking Avatar
Upload a photo + script to auto-generate presenter-style talking head videos.

✂️ Background Removal
One-click cutout for product shots, portraits, and any image.

👗 Product Model Shots
Place your product onto model templates for e-commerce showcase images.

🎙️ Voice & TTS
Text-to-speech, voice cloning, multilingual dubbing and narration.

Once you've signed in, just reply "done" and I'll continue right away.

在聊天应用场景中应避免的说法

这些说法容易让聊天应用中的非技术用户感到困惑。建议使用括号中的替代表达，或者完全省略技术细节。（如果用户明确询问终端或环境变量，请直接回答。）

• “浏览器已打开” / “浏览器弹出了” → 直接发送登录链接
• “在终端中运行此命令” / “运行登录命令” → 替用户处理
• “检查弹窗” / “看看浏览器” → 改为发送链接
• “设置环境变量” → 与终端用户无关；登录后会自动处理
• “命令执行成功” / “正在轮询任务状态” / “脚本输出如下” → 改为总结结果
• “去操作那台电脑” / “检查机器人的电脑” → 所有交互都留在聊天中
• “授权页面弹出了” → 发送 URL，让用户自行打开
• “先前往 topview.ai 注册”——授权页面已包含注册入口
• “你更喜欢哪种方式？” / “给你两个选项” → 直接采取显而易见的下一步，而不是询问
• “授权流程” / “执行身份验证” / “完成身份验证” → 改用“登录”
• “Python 配置” / “环境设置” → 通常不是面向用户的概念
• 任何要求用户在聊天之外进行操作的内容
• 任何包含原始代码、命令或文件路径的内容（除非用户是技术人员）

登录 URL 未出现在输出中时的回退处理

如果 auth.py login 的输出中没有 URL: 行（例如后台执行时未能获取），请重新运行 auth.py login，以获取新的 URL。让用户“检查浏览器弹窗”或“前往 Agent 的电脑”并无帮助，因为用户无法看到这些内容。

先决条件

• Python 3.8+
• 已完成登录 — 直接链接登录流程请参阅 references/auth.md
• 有可用额度 — 查看余额请参阅 references/user.md
• 环境变量 TOPVIEW_UID + TOPVIEW_API_KEY 会在登录后自动处理；手动设置仅用于 CI/内部用途

pip install -r {baseDir}/scripts/requirements.txt

Agent 工作流指南

适用于所有生成模块（avatar4、video_gen、ai_image、remove_bg、product_avatar、text2voice）。

1. 新任务优先使用 run — 它会自动提交任务并持续轮询，直到任务完成。大多数情况下，默认使用此方式最合适。
2. 由 Agent 负责轮询 — 用户无需手动检查任务状态；脚本会持续轮询，直到任务完成或超时。
3. 恢复任务时使用 query — run 超时且已有 taskId，或用户提供了现有 taskId 时使用。
4. query 会持续轮询 — 它每隔 --interval 秒检查一次，直到状态为 success 或 fail，或达到 --timeout。它不会只检查一次就停止。
5. 如果 query 也超时（退出代码为 2），请增大 --timeout，并使用相同的 taskId 重试。只有任务确实失败时，才使用 run 重新提交。

Decision tree:
  → New request?           use `run`
  → run timed out?         use `query --task-id <id>`
  → query timed out?       use `query --task-id <id> --timeout 1200`
  → task status=fail?      resubmit with `run`

任务状态：

状态	描述
init	任务已排队，等待处理
running	任务正在处理中
success	任务已成功完成
fail	任务失败

Board ID 指南

每个生成任务都包含 --board-id，可让结果井然有序，并能在网页上查看。

1. 会话开始时 — 提交第一个任务前，运行 board.py list --default -q 获取默认 Board ID（“My First Board”）。每个会话运行一次即可。
2. 传递给所有任务 — 在每个生成命令（avatar4.py、video_gen.py、ai_image.py、product_avatar.py、text2voice.py）中添加 --board-id <id>。
3. 任务完成后 — 如果任务结果包含 boardTaskId，请将编辑链接分享给用户：https://www.topview.ai/board/{boardId}?boardResultId={boardTaskId}。
4. 用户需要新 Board 时 — 运行 board.py create --name "..."，并在后续任务中使用返回的 Board ID。
5. 用户指定 Board 时 — 使用用户提供的 Board ID，而不是默认值。
6. 忘记 Board ID 时 — 再次运行 board.py list --default -q。

Session flow:
  1. BOARD_ID = $(board.py list --default -q)
  2. avatar4.py run --board-id $BOARD_ID ...
  3. video_gen.py run --board-id $BOARD_ID ...
  4. (result shows edit link with boardTaskId)

模块

模块	脚本	参考文档	描述
Auth	scripts/auth.py	auth.md	OAuth 2.0 设备流程 — 生成登录链接、等待授权、保存凭据
Avatar4	scripts/avatar4.py	avatar4.md	根据照片生成会说话的虚拟形象视频；使用 list-captions 查看字幕样式
Video Gen	scripts/video_gen.py	video_gen.md	图生视频、文生视频、全能参考（根据参考视频、图像、音频和文本生成视频）
AI Image	scripts/ai_image.py	ai_image.md	文生图和 AI 图像编辑（10 多种模型）
Remove BG	scripts/remove_bg.py	remove_bg.md	移除图像背景 — 产品虚拟形象工作流的第 1 步
Product Avatar	scripts/product_avatar.py	product_avatar.md	模特展示产品图；使用 list-avatars/list-categories 浏览模板
Text2Voice	scripts/text2voice.py	text2voice.md	文本转语音音频生成
Voice	scripts/voice.py	voice.md	语音列表/搜索、语音克隆、删除自定义语音
Board	scripts/board.py	board.md	画板管理 — 整理结果、在网页上查看/编辑
User	scripts/user.py	user.md	积分余额和使用记录

请阅读单独的参考文档，了解用法、选项和代码示例。 作为参数传入的本地文件（图像/音频/视频）会自动上传 — 无需手动上传。

---

创作指南

核心原则： 从用户意图出发，而不是从 API 出发。 分析用户想要实现什么，然后选择合适的工具、模型和参数。

第 1 步 — 意图分析

每当用户请求创作内容时，请确定：

维度	自问	默认选项
输出类型	图像？视频？音频？复合内容？	必须询问
用途	营销？教育？社交媒体？个人用途？	通用社交媒体
素材	用户已有何种素材？还缺少什么？	必须询问
风格 / 语气	专业？随意？活泼？权威？	专业且友好
时长	输出应持续多久？	短片为 5–15 秒，虚拟形象视频为 30–60 秒
语言	使用什么语言？需要字幕吗？	与用户使用的语言一致
发布渠道	将发布到哪里？	通用用途

步骤 2 — 工具选择

将用户的请求路由到合适的脚本。对于组合请求（例如，人物对镜讲述 + 产品片段），请规划一个配方（见步骤 3）。如果请求超出当前能力范围，请参阅下文的能力边界。

用户说……	脚本和类型
“用这张照片和文字制作一个会说话的虚拟形象视频”	avatar4.py（直接传入本地图片路径）
“用这张照片和我的录音生成视频”	avatar4.py（传入本地图片和音频路径）
“让这张图片动起来 / 图生视频”	video_gen.py --type i2v（传入本地图片路径）
“生成一个关于……的视频”	video_gen.py --type t2v
“生成一个参考这张图片风格的新视频”	video_gen.py --type omni
“生成图片 / 文生图”	ai_image.py --type text2image
“修改这张图片 / 更改背景”	ai_image.py --type image_edit
“移除图片背景 / 抠图”	remove_bg.py
“将这个产品放到模特图片中”	product_avatar.py（如果产品带有背景，请先使用 remove_bg.py）
“有哪些产品虚拟形象 / 模特模板？”	product_avatar.py list-avatars
“有哪些字幕样式？”	avatar4.py list-captions
“将这段文字转换为语音 / 音频”	text2voice.py
“有哪些声音？/ 查找女声”	voice.py list --gender female
“根据这段录音克隆声音”	voice.py clone --audio <file>
“删除这个自定义声音”	voice.py delete --voice-id <id>
“查看我的看板 / 检查已生成的内容”	board.py list 或 board.py tasks --board-id <id>
“创建新看板”	board.py create --name "..."
“查看我还剩多少积分”	user.py credit

视频模型选择 — 参见 references/video_gen.md § 模型推荐。

图像模型提示： 对于所有图像任务，默认使用 GPT Image 2 — 文字渲染效果出色，综合质量高，支持 13 种宽高比、1K/2K/4K 分辨率，以及最多 16 张用于编辑的参考图片。若原始图像保真度比文字渲染更重要，Nano Banana 2 是一个不错的替代选择。参见 references/ai_image.md § 模型推荐。

产品虚拟形象工作流： 为获得最佳效果，请使用两步流程：先用 remove_bg.py 获取 bgRemovedImageFileId，再通过 --product-image-no-bg 调用 product_avatar.py。使用 product_avatar.py list-avatars 浏览公开模板并获取 avatarId。参见 references/product_avatar.md § 完整工作流。

avatar4 的字幕样式： 使用 avatar4.py list-captions 查看可用字幕样式，然后通过 --caption 传入 captionId。

人物对镜讲述提示 — avatar4 与带原生音频的 video_gen： 某些 video_gen 模型（例如 Standard、Kling V3、Veo 3.1）支持原生音频，可以生成视觉质量优于 avatar4 的人物对镜讲述视频。不过，它们的最长时长较短（5–15s），且成本高得多。Avatar4 每段最长支持 120s，成本也低得多。 经验法则： 大多数人物对镜讲述需求默认使用 avatar4。只有在片段较短（<=15s）且用户明确将顶级视觉质量置于成本之上时，才考虑使用 video_gen 原生音频模型。

第 3 步 — 简单与复杂

简单请求 — 用户需求明确，素材已准备就绪 → 直接依据参考文档处理。

复杂请求 — 用户给出的是一个目标（例如“制作一支宣传视频”“解释 AI 如何运作”），而不是直接的 API 指令。请遵循以下通用工作流：

1. 拆解并澄清： 询问用户的目标受众、核心信息、预期时长，以及目前拥有的素材（照片、脚本）。
2. 确定方案：
   • 有某人的照片 + 需要旁白 → 使用 avatar4（Talking Head）。
   • 有产品/参考照片 → 使用 video_gen --type i2v 或 omni。
   • 没有素材，纯视觉概念 → 使用 video_gen --type t2v。
   • 两者都需要 → 规划混合方案（Avatar 旁白 + B-roll 插入片段）。
3. 组织内容：
   • 编写结构化脚本（钩子 → 正文/说明 → 行动号召）。
   • 在 TTS 脚本中添加 <break time="0.5s"/> 标签，以实现自然的语速节奏。
   • 对于视觉内容，编写详细提示词，涵盖主体 + 动作 + 光线 + 摄像机。
4. 处理长篇内容（>120s）： 如果脚本超过单个 avatar4 任务的 120s 限制，则在自然的句子边界处分割为逻辑片段（例如，每段 60s）。使用 submit 命令并行提交任务，确保各片段的参数（声音/模型）保持一致，并按顺序交付。

---

执行前检查清单

建议在每次生成任务前执行以下步骤。

1. 估算费用 — 视频任务使用 video_gen.py estimate-cost，图像任务使用 ai_image.py estimate-cost；avatar4 的费用取决于视频时长；product_avatar 固定为 0.5 credits；text2voice 固定为 0.1 credits。
2. 验证参数 — 确保模型、宽高比、分辨率和时长彼此兼容（使用 list-models 检查）。
3. 向用户确认缺失的关键参数 — 如果未指定会影响输出的重要参数，请先询问用户，而不是默默采用默认值。各模块的关键参数：
   • video_gen：时长、宽高比、模型
   • ai_image：宽高比、分辨率、模型、图像数量
   • avatar4：通常由输入决定；如果未指定，请确认声音
   • text2voice：声音选择
4. 首次提交前确认 — 在会话中首次提交生成任务之前，提供完整方案（工具、模型、参数、费用估算），并询问用户：
   • 是否继续生成
   • 后续任务是否需要 Agent 每次都先征求确认，还是信任 Agent 在本次会话其余时间自动继续
   • 这两个问题应合并在一条确认消息中。
   • 如果用户选择“自动继续”，则本次会话后续任务可跳过确认步骤（但仍须询问缺失的参数）。
   • 如果用户一开始就明确表示“直接做”或类似意思，则从一开始就按自动继续处理。

Agent 行为规范

执行期间

1. 直接传入本地路径 — 脚本会在提交任务前自动将本地文件上传到 S3
2. 并行处理相互独立的步骤 — 独立的生成任务可以并发运行
3. 保持片段间一致性 — 生成多个片段时，使用完全相同的参数

执行后

推荐的结果格式如下——先输出结果链接，再输出画板链接，最后列出关键元数据。保持简洁易读。 模板以英文编写——发送前请翻译成与用户相同的语言。

视频结果模板：

🎬 Video generated

Video: <VIDEO_URL>
• Duration: <DURATION>
• Aspect ratio: <ASPECT_RATIO>
• Model: <MODEL_NAME>
• Cost: <COST> credits

🔗 Project link
https://www.topview.ai/board/<BOARD_ID>?boardResultId=<BOARD_TASK_ID>
View, edit, and download in the project.

Not happy with the result? Let me know and I'll adjust and regenerate.

图像结果模板：

🖼️ Image generated

Image: <IMAGE_URL>
• Resolution: <RESOLUTION>
• Model: <MODEL_NAME>
• Cost: <COST> credits

🔗 Project link
https://www.topview.ai/board/<BOARD_ID>?boardResultId=<BOARD_TASK_ID>
View, edit, and download in the project.

Not happy with the result? Let me know and I'll adjust and regenerate.

格式指南：

1. 先显示结果链接——将视频／图像 URL 放在顶部。
2. 再显示画板链接——如果有 boardTaskId，请包含画板编辑链接。
3. 仅列出关键元数据——时长、宽高比／分辨率、模型、费用。避免输出原始 JSON 或额外字段。
4. 提供迭代选项——最后简短说明用户可以要求调整。说明重新生成会额外消耗积分。
5. 多个结果——如果任务生成了多个结果，请为每个结果编号（1、2、3……），并分别附上链接和元数据。
6. 匹配用户语言——发送前请将模板翻译成与用户相同的语言。

错误处理

有关错误代码、任务级故障和恢复决策树，请参阅 references/error_handling.md。

---

能力边界

可用能力列于上方的 Modules 表格和 Step 2 routing table 中。模块未涵盖的内容不在其能力范围内，例如：

能力	状态
营销视频（m2v）	没有对应模块——建议使用 topview.ai 网页界面

如果用户需要上方未列出的模型或功能，请按照 references/updating_models.md 中的 “先查询官方文档，再更新 skill” 流程操作。不要承诺模块中不存在的能力——只有当 Topview API 确实不支持该能力时，才引导用户使用 topview.ai 网页界面。