name: wonda-cli
description: 在终端中使用Wonda CLI生成图像、视频、音乐和音频——以及LinkedIn、Reddit和X/Twitter的研究与自动化

Wonda CLI

Wonda CLI 是一个面向终端代理的内容创作工具包。可用于生成图像、视频、音乐和音频；编辑和合成媒体；发布到社交平台；以及在 LinkedIn、Reddit 和 X/Twitter 上进行研究和自动化操作。

安装

如果 wonda 不在 PATH 中，请先安装：

# npm
npm i -g @degausai/wonda

# Homebrew
brew tap degausai/tap && brew install wonda

设置

• 身份验证：wonda auth login（推荐，打开浏览器）或设置 WONDA_API_KEY 环境变量
• 验证：wonda auth check

组织与消费上下文

Wondercat 组织是共享钱包，拥有各自的席位和计费。

成员可以从组织钱包中消费（而不是个人积分），

通过切换上下文：

• wonda organizations list（别名：wonda orgs list、wonda org list）—— 查看你所属的每个组织，以及你在其中的角色和席位计划。
• wonda use --org <slug> —— 从此机器粘性使用组织上下文。设置

X-Wonda-Org 请求头到每个请求上；预扣费、计费和 wonda balance

都会通过组织钱包路由。

• wonda use --personal —— 回到个人。

wonda topup 始终为你的个人钱包充值，无论上下文如何。

充值组织钱包（以及配置自动充值）仅限管理员操作，需要在网站上

/organizations/<slug> 完成。如果组织积分用完，错误信息会提示

用户联系管理员或切换回个人 —— 他们无法通过 CLI 充值组织钱包。

组织内的角色与席位计划是分开的：

• 拥有者：最初的创建者。不能被降级或踢出。可以从组织页面将所有权转移给另一个成员（很少发生）。
• 管理员：可以邀请（单个或批量粘贴）、踢出、更改角色、更改席位、充值、配置自动充值、更改每月限额。
• 用户：只能在组织钱包内消费（如果管理员设置了按成员每月限额，则受其限制）。

付费组织席位（WONDA / WONDA_PREMIUM）授予与个人付费计划相同的付费功能访问权限（技能等），但仅在组织上下文中有效。wonda use --personal 回退到用户的个人账户计划。

访问层级

并非所有命令对每种账户类型都可用：

如果命令返回 403 错误，请检查你的计划：https://app.wondercat.ai/settings/billing。

声音克隆

从 10 秒以上的音频片段克隆声音，并在 TTS 中使用。硬限制：每个账户 20 个克隆声音。费用：每个克隆 1.50 美元。

# 从本地文件克隆（先自动上传到媒体库）
wonda voice create "Andu" --file ./sample.mp3 --description "我的声音"

# 从现有的 wonda 媒体克隆
wonda voice create "Brand" --media-id <uuid>

# 可选的源音频预处理
wonda voice create "Clean" --file ./raw.wav --noise-reduction --normalize-volume

# 列出克隆的声音（每行报告 isExpired 和 expiresInDays）
wonda voice list

# 单个声音
wonda voice get <voice-id>

# 重命名/重新描述（仅本地，不调用提供商）
wonda voice update <voice-id> --name "新名称" --description "..."

# 删除
wonda voice delete <voice-id>

在 TTS 中使用克隆声音：将 voice get 返回的 providerVoiceId 作为 voiceId 传递给 /audio/speech：

wonda audio speech "Hello world" \
  --model minimax-speech-2-8-hd \
  --params '{"voiceId":"<providerVoiceId>"}'

7 天过期：克隆的声音如果在 7 天内未在 TTS 中使用，将自动过期。使用克隆声音运行 TTS 会自动刷新其过期时间。闲置过期的声音必须重新克隆（再花 1.50 美元）。

凭据保险库

持久化在外部平台（Instagram、TikTok、Twitter 等）上创建的登录信息，以便在下次运行时重复使用。密码使用服务器端密钥进行 AES-256-GCM 加密，仅在 get 时解密。

# 创建
wonda credentials create --website instagram.com --username myhandle \
  --email me@example.com --password-stdin <<< "hunter2" \
  --metadata '{"signup_source":"wonda-email"}'

# 列出（省略密码）
wonda credentials list --website instagram.com

# 获取完整记录，包括解密后的密码
wonda credentials get <id>

# 更新任意字段（使用 --password-stdin 轮换；--username "" 清除）
wonda credentials update <id> --username newhandle

# 删除
wonda credentials delete <id>

# 一次调用获取并记录使用原因——POST，不是 GET，因为
# 它会写入一个包含原因的 'used' 事件。在你能说明原因时，优先使用此命令而不是 `get`。
wonda credentials use <id> --reason "instagram 注册流程"

# 查看最近的事件（创建/使用/轮换/更新），用于审计
wonda credentials events <id>

字段：website（必需——输入的文本如 insta 会被规范化为 instagram.com）、username、email、password（必需）、metadata（任意 JSON）。username / email 中至少有一个必须存在。允许多条 (website, username) 记录——如果你需要去重，请自行处理。

事件日志：每次 credentials get/use、create、密码轮换和其他更新都会记录为凭据上的事件（操作者：cli | web | system）。使用 credentials events <id> 或 Web UI 的历史图标进行审计。事件日志是仅追加的，并在凭据删除时级联删除。

全局输出标志

所有命令都支持以下输出控制标志：

• --json —— 强制 JSON 输出（当 stdout 被管道传输时自动启用）
• --quiet —— 仅输出主要标识符（任务 ID、媒体 ID 等）—— 适合脚本使用
• -o <path> —— 将输出下载到文件（隐含 --wait）
• --fields status,outputs —— 选择特定的 JSON 字段
• --jq '.outputs[0].media.url' —— 使用 jq 表达式过滤 JSON 输出

CLI 公告与弃用警告

每次命令运行时，CLI 都会轮询 GET /api/v1/updates（匿名，缓存 1 小时到 ~/.wonda/state.json）以获取活动公告：弃用通知、事件提醒、升级提示。消息仅打印到 stderr，因此 stdout/JSON 保持干净以便管道传输。

每个请求的弃用提示以标准的 Warning: 299 - "<message>" HTTP 头部形式到达，并由 CLI 的 HTTP 客户端以 [deprecated METHOD /path] <message> 格式输出到 stderr。

使用 WONDA_QUIET=1（环境变量）或 --quiet（标志）可以静默这两个通道。仅禁用网络检查使用 WONDA_NO_UPDATE_CHECK=1。

WAB / Wonda 自动化浏览器（wonda wab）

Wonda 自动化浏览器（WAB）是一个高级隐形反检测浏览器，经过加固，使得平台无法将其识别为自动化工具。wonda wab 是反检测 Chromium 栈（Patchright，未检测的 Playwright 分支）的统一命令。它有两个面孔：

• 认证会话。 每个人设一个持久化的有头 Chromium，持有 LinkedIn、X、Reddit 等平台的已登录会话。CLI 按需启动它，让它闲置超时，并在命令通过 --via wab 运行时将平台读写操作路由通过它。Cookie 存储在该人设的 Chromium 配置文件中，而不是 ~/.wonda/config.json。
• 匿名捕获。 wonda wab record <url>（以及 wonda brand extract）驱动一个临时 Chromium，使用全新的指纹，没有人设，没有 cookie。请参见下面的 record 部分。

思维模型：你有账户（每个平台一个身份）。每个平台命令通过扁平 JSON 存储（--via cookies，快速，无需 Chromium）或通过该账户的人设（--via wab，实时的反检测 Chromium）将请求路由到该账户的 cookie。人设是可以持有多个账户（在同一个指纹下）的 Chromium 外壳。在几乎所有情况下，人设在首次 --via wab 使用时自动创建，以账户命名，因此你从不需要输入人设名称。

wonda wab install                             # 一次性：npm install + patchright chromium（由会话、record、brand extract 共享）
wonda wab start [account]                     # 启动（默认后台；--visible 显示）
wonda wab stop [account]                      # 优雅关闭
wonda wab status                              # 列出人设 + 最后活动时间
wonda wab login <account> <linkedin|x|reddit> # 打开有头窗口，用户登录，cookie 持久化
wonda wab check <account> <linkedin|x|reddit> # 非交互式会话存活检测
wonda wab bind <persona> --x <acct> --reddit <acct> --linkedin <acct>  # 多账户高级用户路径：将 N 个账户绑定到一个 PERSONA
wonda wab record <url>                        # 匿名一次性捕获（无账户，无 cookie），见下文
wonda wab sync-cookies [account]              # 立即强制 wab → 磁盘 cookie 同步（不等 10 分钟定时器）
wonda wab logs [account] --tail 100           # 查看 driver.log（--audit 获得结构化按命令日志）
wonda wab errors --tail 20 --since 24h        # 查看跨人设的操作失败日志
wonda wab bundle-failures list                # 最近的操作失败包（每个失败运行一个：截图、DOM、可见元素、cookie 摘要 REDACTED）
wonda wab bundle-failures show <id>           # 打印包清单 + 文件树（id = unix-ms-ts 前缀）
wonda wab bundle-failures ship <id>           # 压缩到 ~/Downloads/wonda-failure-<id>.zip 以便分享
wonda wab bundle-failures prune               # 删除超过 30 天的包（或 --max-per-persona、--all）
# 遥测：每次 wab 操作失败时，我们报告（action, platform, reason, error-string, has_bundle, cli_version）作为 wab_action_failed PostHog 事件，以便维护者可以发现跨用户的平台轮换。没有包内容、没有 cookie、没有 DOM、没有截图离开用户的机器。选择退出：WONDA_TELEMETRY_DISABLED=1
wonda wab migrate-legacy                      # 将旧的 patchright-li-driver 配置文件复制到人设槽中
wonda wab restore <persona> [timestamp]       # 从每小时快照恢复（--list 枚举）
wonda wab backup enable                       # 选择加入：每次磁盘同步后自动将同步的 cookie JSON 推送到 wondercat
wonda wab backup disable                      # 选择退出（现有云备份不受影响）
wonda wab backup status                       # 显示配置 + 远程清单
wonda wab backup push [account]               # 一次性手动推送所有平台绑定
wonda wab backup pull [account]               # 在新机器上将云 cookie 恢复到 ~/.wonda/<platform>-cookies/<account>.json
wonda wab backup list                         # 云备份清单（仅元数据）
wonda wab backup delete <plat> <persona> [acct] # 删除一个备份

生命周期命令接受 --account（例如 wonda wab login mathieu linkedin）；人设从账户名自动派生。wonda wab bind 是唯一一个显式命名人设的地方：当一个 Chromium 需要托管不同平台上有不同名称的账户时使用。

匿名捕获（record）。 wonda wab record <url> 在一个临时 Chromium 中将 URL 录制为 webm（每次调用使用全新指纹，无人设，无 cookie）。用于需要绕过 cookie 横幅的页面（Notion 公开分享、pdf.js 渲染、任何普通 Playwright 会触发机器人检测的网站）以及营销演示捕获。

wonda wab record https://example.notion.site/page \
  --output recording.webm \
  --duration 5 \
  --viewport 960x1080 \
  --inject-js scripts/page-script.mjs   # 可选：在加载后、计时器启动前运行

# 将 webm 转码为 30 fps 的 mp4（Patchright 录制 webm/VP8）
ffmpeg -y -i recording.webm -t 5 -r 30 -an \
  -c:v libx264 -pix_fmt yuv420p -crf 18 recording.mp4

--inject-js 文件被包裹在异步 IIFE 中，因此顶层的 await 可以工作。它在 domcontentloaded + networkidle + 400ms 渲染稳定后运行，在持续时间计时器启动前。其中的任何 await 都会计入录制窗口内。用于注入深色主题、移除 cookie 横幅、滚动动画等需要在页面上下文中进行的操作。

Node.js 要求：wonda 需要 Node >= v20 在 PATH 中。Homebrew 用户通过 node 依赖获得；npm 用户本身就有；install.sh 用户可能需要 brew install node（或任何 Node 发行版）。如果 Node 缺失，wonda wab install 会获取私有副本到 ~/.wonda/node/。

Cookie 云备份。 默认关闭。一旦使用 wonda wab backup enable 启用，WAB 驱动会在每次 wab → 磁盘同步（以及优雅关闭）后将每个绑定平台的同步 cookie JSON 推送到 wondercat 后端。在服务器端以明文存储（无客户端加密）；权衡是在新机器上可以通过 wonda wab backup pull <account> 进行自助恢复。每 (account, platform, persona, account_label) 行，最后写入者获胜，限制为每 60 秒一次推送。

源代码位于 cli/wondercat/wab/。驱动是 launch.mjs，每个平台的操作脚本位于 actions/<platform>/ 下。

每条命令的传输方式（--via）。 linkedin、x 和 reddit 命令接受：

• --via cookies|wab：cookies 读取扁平的每个账户 JSON 存储（快速，无需 Chromium）；wab 通过该账户的 Chromium 人设路由（cookie + TLS 指纹继承自真实浏览器会话）。不支持的值会报错，而不是静默降级。
• --account <name>：使用哪个磁盘上的身份（cookie 文件名/人设）。人设解析是隐式的：首次 --via wab 使用会自动创建一个以账户命名的人设，并在 TTY 上直接进入登录流程。

读取与写入的默认值不同。 读取命令（资料、帖子、搜索、时间线等）默认为 cookies（直接 API），因为该路径快速且检测安全。写入/互动命令（发帖、评论、点赞、关注、连接、私信、转发、删除）默认为 wab，因为 cookie-API 路径在有任何规模的活动时都会触发 LinkedIn / X / Reddit 的反滥用检测。如果你明确想要传统 API 路径（在该命令支持的情况下），请传递 --via cookies。

需要 --via wab 的命令。 少数命令没有 cookie 路径，只能通过 Wonda 自动化浏览器运行：wonda linkedin comment、wonda x delete 和 wonda x reply --attach。在这些命令上，默认值已经解析为 wab（一行 stderr 提示）；传递 --via cookies 会明确报错。Reddit 的写入操作（vote、comment、subscribe、save、unsave、delete 和 subreddit submit）同样只支持 wab。

每个账户的凭据。 Cookie 保存在磁盘上每个账户的 JSON 文件中：

• ~/.wonda/x-cookies/<account>.json
• ~/.wonda/reddit-cookies/<account>.json
• ~/.wonda/linkedin-cookies/<account>.json（从旧的单一文件格式自动迁移）

向 auth set 传递 --account <name> 可以并排保存多个登录。绑定记录在该账户的人设的 account-bindings.json 中，如果该人设的 Chromium 正在运行，轮换后的 cookie 会被推送到实时上下文中。驱动每 10 分钟（以及在优雅关闭时）也会将 cookie 同步回磁盘，因此轮换后的 cookie（ct0 循环、token_v2 服务器端刷新等）会流回 cookie 路径，无需手动重新粘贴。

配置键

wonda config get|set|list 键：

• api-key：你的 wondercat API 密钥。
• base-url：API 基础地址（默认为生产环境，设置为 https://staging.api.wondercat.ai 用于暂存环境）。
• default-account：当平台命令未传递 --account 时使用的账户。
• wab-backup-enabled：true/false，用于 cookie 云备份（与 wonda wab backup enable/disable 相同）。

传输方式不是配置键。每条命令根据其类型选择（读取默认为 cookies，写入/互动默认为 wab），在所有平台上相同。使用 --via cookies|wab 可以为特定命令覆盖（如果该平台支持）。

如何思考内容创作

你是一位拥有完整制作工具包的营销总监。在使用任何工具之前，思考：

1. 什么产品类别？（美妆、食品、科技、时尚、健身等）
2. 什么格式对该类别表现最佳？（日常用品的 UGC 梗、奢侈品的电影感、转型产品的前后对比、服务类的推荐证明）
3. 钩子是什么？（ relatable 场景、惊人转折、理想生活方式、社交证明）
4. 什么具体场景？（不是“产品在桌子上”，而是“人在有趣的情景中发现产品”）

决策流程

当被要求创建内容时，按以下顺序操作：

第 1 步：收集上下文

wonda brand                                                    # 活跃品牌：标识、颜色、字体、徽标、产品
wonda brand list                                               # 该账户/组织拥有的所有品牌
wonda brand show <brand-id>                                    # 特定品牌
wonda brand extract https://stripe.com                         # 仅本地：写入 ./output/stripe.com/{DESIGN.md, tokens.json, assets/}
wonda brand extract https://stripe.com --save --make-active    # 本地 + 持久化 + 激活（常用路径）
wonda brand extract https://stripe.com --save --name "Stripe"  # 持久化并使用自定义名称
wonda brand extract https://stripe.com --no-output --save      # 不写入磁盘，仅持久化
wonda brand save                                               # 将最近的 ./output/<domain>/ 目录持久化到服务器
wonda brand save --from ./output/stripe.com --make-active
wonda brand pull <brand-id>                                    # 将已保存的品牌下载回 ./output/<domain>/
wonda brand activate <brand-id>                                # 设置为活跃品牌
wonda brand upload-logo <brand-id> https://acme.com/logo.svg   # 通过 URL 附加徽标（--variant wordmark|icon|dark|light）
wonda brand upload-font <brand-id> https://acme.com/Geist.woff2 --weight 700
wonda brand delete <brand-id>
wonda analytics instagram                                      # 哪些内容表现良好
wonda scrape social --handle @competitor --platform instagram --wait  # 竞争研究（如果相关）

# 跨平台研究（如果相关）
wonda x search "topic OR keyword"                              # 在 X/Twitter 上查找讨论
wonda x user-tweets @competitor                                # 竞争对手的近期推文
wonda reddit search "topic" --sort top --time week             # Reddit 讨论
wonda reddit feed marketing --sort hot                         # Subreddit 趋势
wonda linkedin search "topic" --type COMPANIES                 # LinkedIn 公司/人员研究
wonda linkedin profile competitor-vanity-name                  # LinkedIn 资料情报

第 2 步：检查内容技能

内容技能是常见内容类型的逐步指南。每个技能告诉你使用哪些模型、提示和编辑操作——以及按什么顺序。在从头构建之前，始终检查技能。

wonda skill list                                # 浏览所有内容技能
wonda skill get <slug>                          # 技能的完整逐步指南

完整技能索引：

如果技能匹配 → wonda skill get <slug>，阅读，根据上下文调整，执行每个步骤。

如果没有技能匹配 → 从头构建（第 3 步）。

第 2.5 步：决定是否在本地完成

并非每个媒体任务都应该通过 Wonda 编辑回传。使用以下路由规则：

• 使用 wonda 进行 AI 生成、AI 转录/对齐、爬取、发布、托管转场，以及需要媒体 ID 或远程任务的工作流。
• 使用本地 ffmpeg 进行你已经拥有或可以下载的文件的确定性转换：裁剪、缩放/填充、拼接（合并多个片段）、替换音频、提取音频/帧、反转、交付标准化、烧录字幕、分割场景、剪切静音、构建分析工件。始终在本地合并片段——服务器端合并一旦任何输入超过约 7MB，可能会挂起 30 分钟以上。

当任务从 Wonda 媒体 ID 开始但实际编辑是确定性的时，先将其移动到本地文件：

wonda media download <mediaId> -o ./input.mp4

在任何本地 ffmpeg 工作之前：

which ffmpeg
which ffprobe
ffmpeg -version
ffprobe -v error -show_format -show_streams -of json ./input.mp4

本地字幕/文字工作的字体规则：

• 优先使用明确的字体文件路径，而不是字体系列名称。
• 永远不要假设字体存在。首先使用 fc-match、fc-list、/System/Library/Fonts、/Library/Fonts、~/Library/Fonts 或 /usr/share/fonts 检查。
• 如果任务主要是本地收尾/字幕/格式化/分割/工件提取，请在发明命令之前检查 ffmpeg 技能。
• wonda edit video 为每个编辑器操作运行本地 ffmpeg：trim、crop、volume、speed、reverseVideo、extractFrame、extractAudio、editAudio、imageCrop、imageToVideo、merge、overlay、splitScreen、splitScenes、skipSilence。渲染在你的机器上通过 ffmpeg 运行：没有服务器端 editor_job，渲染本身不扣积分（输入被下载，结果被上传）。textOverlay 和 animatedCaptions 也通过捆绑的 hyperframes（Chromium）渲染器在本地运行。ffmpeg 必须在 PATH 中（wonda doctor 验证）。公共 API /video/edit、/image/edit、/audio/edit 不再用于这些操作，返回 410 Gone。
• 始终在本地合并片段。 服务器端合并一旦任何输入超过约 7MB，可能会挂起 30 分钟以上，并且 wonda edit video --operation merge 现在默认也在本地 ffmpeg 中运行，原因相同。
• 永远不要为每个片段混合音频然后拼接。 先拼接视频轨道，然后在整个合并后的时间线上层叠完整的画外音或音乐轨道。每个片段的音频烘焙会产生剪辑线冲突和静音间隙。

默认本地导出目标，除非用户另有要求：

-c:v libx264 -preset medium -crf 18 -pix_fmt yuv420p -movflags +faststart -c:a aac -b:a 192k

始终传递 -y 作为第一个标志，以便命令自动覆盖输出。ffmpeg 在输出路径存在时会交互式提示，代理 shell 会挂在该提示上直到超时。

第 2.6 步：选择正确的本地工具

编辑映射到四个工具之一。选择第一个匹配的行。

在新机器上运行一次 wonda doctor，确认 ffmpeg、node 和 hyperframes 都可用。传递 --warm-chrome 以预取 hyperframes 捆绑的 Chromium（约 150 MB），以便第一个剪辑渲染不会暂停下载。

示例：

基本裁剪和合并（wonda edit，本地 ffmpeg）：

wonda edit video --operation trim --media $VID \
  --params '{"trimStartMs":3000,"trimEndMs":10000}' \
  --wait -o ./trimmed.mp4

wonda edit video --operation merge --media $A,$B,$C \
  --wait -o ./merged.mp4

动态图形片头（wonda compose，hyperframes）：

wonda compose motion --template fade-in \
  --text "Q4 Recap" --subtitle "Wondercat" \
  --duration 4 --resolution portrait -o intro.mp4

wonda compose text --input ./clip.mp4 --text "NEW DROP" \
  --position bottom-center -o overlay.mp4

完成片段上的动态字幕（转场服务）：

wonda transitions run --media $VID --preset caption_word_pop --wait -o final.mp4

原始 ffmpeg 用于未涵盖的基本操作（例如带音频渐出的拼接）：

ffmpeg -y -f concat -safe 0 -i list.txt \
  -af "afade=out:st=29:d=1" \
  -c:v libx264 -crf 18 -pix_fmt yuv420p \
  -c:a aac -b:a 192k out.mp4

多步骤管线（合成片头 → wonda 合并主片段 → 转场字幕）：

wonda compose motion --template scale-pop --text "Hello" --duration 3 -o intro.mp4
wonda edit video --operation merge --media $(wonda media upload intro.mp4 --quiet),$MAIN_VID \
  --wait -o merged.mp4
MERGED_ID=$(wonda media upload merged.mp4 --quiet)
wonda transitions run --media $MERGED_ID --preset caption_word_pop --wait -o final.mp4

第 3 步：从头构建（链式端点）

当没有技能匹配时，链式调用单个 CLI 命令。每个步骤生成一个输出，输入到下一步。

单个资产：

wonda generate image --model gpt-image-2 --prompt "..." --aspect-ratio 9:16 --wait -o out.png
# --params '{"quality":"high"}' — auto/low/medium/high（默认 auto）
# --negative-prompt "..."       — 覆盖要排除的内容（模型相关）
# --seed <number>               — 固定种子以获得可重复结果（模型相关）
wonda generate video --model seedance-2 --prompt "..." --duration 5 --params '{"quality":"high"}' --wait -o out.mp4
wonda generate text --model <model> --prompt "..." --wait
wonda generate music --model suno-music --prompt "upbeat lo-fi" --wait -o music.mp3

音频（语音、转录、对话）：

# 列出可用声音（TTS + 对话使用同一组）
wonda audio voices

# 文本转语音
wonda audio speech --model elevenlabs-tts --prompt "Your script here" \
  --params '{"voiceId":"hpp4J3VqNfWAUOO0d1Us"}' --wait -o speech.mp3
# elevenlabs-tts 始终需要 voiceId——从 `wonda audio voices` 中选取一个

# 将音频/视频转录为文本
wonda audio transcribe --model elevenlabs-stt --attach $MEDIA --wait

# 多说话人对话（每个说话人需要一个来自 `wonda audio voices` 的 voiceId）
wonda audio dialogue --model elevenlabs-dialogue \
  --prompt 'ALICE: Hi! BOB: Hello!' \
  --params '{"speakers":[{"label":"ALICE","voiceId":"hpp4J3VqNfWAUOO0d1Us"},{"label":"BOB","voiceId":"IKne3meq5aSn9XLyUdCD"}]}' \
  --wait -o dialogue.mp3

音频 AI 操作（直接推理，非编辑器操作）：

# 去噪 / 去混响语音
wonda audio enhance --model replicate-resemble-enhance --attach $MEDIA \
  --params '{"denoise":true,"chunkSeconds":10}' --wait -o enhanced.wav

# 将曲目分离为声乐和器乐音轨
wonda audio extract-voice --model replicate-demucs --attach $MEDIA \
  --wait -o vocals.wav

为视频添加动画字幕：

animatedCaptions 操作一步完成所有操作——提取音频、转录以获得单词级时间，并渲染逐词动画字幕到视频上。

# 生成带有语音的视频
VID_JOB=$(wonda generate video --model seedance-2 --prompt "..." --duration 5 --aspect-ratio 9:16 --params '{"quality":"high"}' --wait --quiet)
VID_MEDIA=$(wonda jobs get inference $VID_JOB --jq '.outputs[0].media.mediaId')

# 添加动画字幕（单步）
wonda edit video --operation animatedCaptions --media $VID_MEDIA \
  --params '{"fontFamily":"TikTok Sans SemiCondensed","position":"bottom-center","sizePercent":80,"strokeWidth":2.5,"fontSizeScale":0.8,"highlightColor":"rgb(252, 61, 61)"}' \
  --wait -o final.mp4

视频的原始音频被保留。不要用 TTS 替换音频——Sora 已经生成了语音。

替代引擎：--captions-engine ffmpeg。

当用户想要打字机效果或当前活跃单词后面有透明/圆角条时使用。普通的 brew install ffmpeg 就足够了。此路径目前仅限 CLI（它不经过 editor_job，因此渲染不扣积分）。

# 渐进式（ffmpeg 引擎的默认值）——累积显示，
# 通过 highlightColor 在活跃单词后显示可选的圆角药丸形状。
wonda edit video --operation animatedCaptions \
  --captions-engine ffmpeg --captions-preset progressive \
  --media $VID_MEDIA \
  --caption-segments "$(echo "$STT_OUT" | jq -c '.outputs[] | select(.outputKey=="wordTimestamps") | .outputValue | map({text: .word, startS: .start})')" \
  --params '{"fontFamily":"TikTok Sans","textColor":"#FFFFFF","strokeColor":"#000000","strokeWidth":3,"fontSizeScale":1.1,"paddingBottom":25,"highlightColor":"#FF3D3D","backgroundBorderRadius":18}' \
  -o final.mp4

# 打字机——字母以恒定间隔（60ms/字符）逐个出现
# 带有白色方形光标。传递纯白色文字（无背景）。
wonda edit video --operation animatedCaptions \
  --captions-engine ffmpeg --captions-preset typewriter \
  --media $VID_MEDIA \
  --caption-segments "$STT_WORD_TIMESTAMPS" \
  --params '{"fontFamily":"TikTok Sans","textColor":"#FFFFFF","fontSizeScale":1.1,"paddingBottom":12}' \
  -o final.mp4

字体被捆绑到二进制文件中，因此标准的 fontFamily 值（TikTok Sans 变体、Nohemi、Comic Cat、Gavency）无需额外设置即可开箱即用。对于想要使用自己字体集合的高级用户，--fonts-dir 是一个可选覆盖：设置后，渲染器首先搜索该目录，只有在找不到匹配项时才回退到捆绑集。

垂直位置由 paddingBottom 控制（画布高度的百分比，从画布底部到字幕底边的距离）。合理值：12 用于传统的底部字幕，25 用于 TikTok 的 3/4 从顶部的最佳位置，35 用于明显的中底部。当 position 以 top-* 开头时，paddingTop 执行相同操作。没有这些值，字幕会吸附到画布的边缘。

转场（单个视频上的效果管线）：

wonda transitions presets                            # 列出内置预设（JSON）
wonda transitions operations                         # 按类别分组（analysis/effect/...）
wonda transitions operations --json                  # 每个参数的完整元数据
wonda transitions llms                               # 完整参考（预设 + 操作 + 依赖关系）
wonda transitions run --media $VID --preset flash_glow --wait -o out.mp4
# 或者发送代理生成的片段时间线（内联 JSON）：
wonda transitions run --media $VID \
  --clips '[{"layer_type":"video","start_frame":0,"end_frame":60}]' --wait -o out.mp4
# 或者从文件（对长代理时间线方便）：
wonda transitions run --media $VID --clips ./timeline.json --wait -o out.mp4
# 要附加 scene_transitions：传递一个包含 clips + scene_transitions 的信封
# 而不是纯片段数组——同一文件，两个字段都转发。
wonda transitions run --media $VID --clips ./timeline_with_transitions.json --wait -o out.mp4
# 其中 timeline_with_transitions.json 是：
#   { "clips": [...],
#     "scene_transitions": [{"name":"crossfade","params":{"duration":8},"boundaries":[60]}] }
wonda transitions job <jobId>                        # 轮询转场任务

精确使用 --preset 或 --clips 之一。需要完整（已登录）账户。在编写片段时间线时，始终首先阅读 wonda transitions llms。它记录了检测/分段/效果的依赖关系、哪些操作需要遮罩，以及完整的片段规范形状（图层类型、轨道、效果、变换）。

预设变量（variables 块）。 每个预设会在 wonda transitions presets 的 variables 下声明其接受的模板变量。每个条目有 name、description 和 required。必需变量必须提供，否则任务会被 400 拒绝——不再静默跳过。通过 --var name=value（可重复）传递它们，或者对于常见的 prompt 情况，使用 --prompt 快捷方式：

# flash_glow_prompted 需要 { prompt }
wonda transitions run --media $VID --preset flash_glow_prompted \
  --prompt "woman in white dress" --wait -o out.mp4

# text_behind_person 需要 { prompt, text }
wonda transitions run --media $VID --preset text_behind_person \
  --var prompt="the person" --var text="HELLO WORLD" --wait -o out.mp4

# 数字类型变量：裸数字被解码为数字，"true"/"false" 被解码为
# 布尔值，其他所有内容保持为字符串。需要数值比较帧索引的预设
#（border_frame、marquee_text、quick_motion_text、bg_remove_scale）
# 需要这个——引用 int 会将其变回字符串。
wonda transitions run --media $VID --preset border_frame \
  --var exit_start_frame=200 --var exit_end_frame=251 --wait -o out.mp4

prompt 变量是一个检测文本查询，描述要遮罩的主题，馈送到 SAM3 以生成逐帧分割遮罩。不是内容生成提示。

构建需要检测遮罩的自定义 --clips 时间线？添加一个带有 layer_type: "video" 和 mask: {layer_type: "mask", analysis_steps: [{name: segment, params: {prompt: "..."}}]} 的片段。SAM3 通过提示一步处理检测和分割，因此不需要单独的 detect 步骤。

渲染前预热遮罩（推荐）

对于带有 mask:<label> 变量的预设，先运行 wonda transitions ensure-masks，以便渲染在遮罩已准备好的情况下开始。第一次对 (media, label) 对的调用需要 1-3 分钟；后续调用几乎是即时的。

# 1. 确保为你将使用的标签准备了遮罩，阻塞直到准备就绪。
wonda transitions ensure-masks --media $VID --labels person,phone --wait

# 2. 运行渲染。遮罩已经准备好。
wonda transitions run --media $VID --preset slide_reflect_background \
  --var "masks=mask:person+phone" --wait -o out.mp4

ensure-masks 标志：

• --media MEDIA_ID — 必需，遮罩对应的视频
• --label NAME — 可重复，每次调用一个标签（--label person --label phone）
• --labels NAME,NAME — 逗号分隔的替代方式（--labels person,phone）
• --wait — 阻塞直到每个标签都准备好
• --timeout DUR — 当设置 --wait 时限制等待时间（默认 10m）

多提示语法：--var 中的 mask:woman+phone 被拆分为单独的遮罩（woman、phone）并按帧合并。将每个子标签分别传递给 ensure-masks，以便所有子标签都被预热。

何时跳过 ensure-masks：

• 非遮罩预设（没有 mask:<label> 变量）——无需准备
• 之前的渲染已经使用过这些 (media, labels)——已经准备好

ensure-masks 最重要的时候：

• 首次使用遮罩预设渲染新媒体时
• 迭代渲染参数时——预热一次，然后想运行多少次就运行多少次，无需重新准备

多场景预设（requiresMultiScene: true）。 一些预设使用场景感知逻辑，期待具有多个剪辑/场景的视频。检查 wonda transitions presets 中的 requiresMultiScene。如果为 true，提供单个连续镜头只会产生一个场景，效果可能显得平淡。先合并片段，或者使用具有自然剪辑的视频。

调整预设参数。 每个预设都是片段形状。使用 wonda transitions preset <name> --json 拉取单个预设，读取其 clips:（单轨）或 tracks:（多轨）字段，编辑任何片段参数，然后以 --clips 提交。对于多轨预设，通过为每个片段提供一个来自其所属轨道的 track 索引来展平。如果预设声明了 sceneTransitions:，在请求中按原样传递该数组。

# 单轨预设（例如 flash_glow_montage）：直接复制 clips:
wonda transitions preset flash_glow_montage --json | jq '.preset.clips' > clips.json
# 编辑 clips.json
wonda transitions run --media $VID --clips "$(cat clips.json)" --wait -o out.mp4

自动修复安全网（--auto-repair、--face-bbox）。 对于 --clips 渲染，工作器在渲染前对提交的 JSON 运行确定性修复，默认开启。修复：宽度适应字体钳制、下行字母钳制相对于画布底部、堆叠间距快照（ROW1_py 来自大写高度公式）、关键帧边界钳制到 [0, source_duration]、同行标题重叠修剪、遮罩全时长扩展、描边宽度归零、字母间距按字体的目标快照、遮罩镂空时长扩展、负起始位置钳制，以及（使用 --face-bbox）面部重叠标题移动。传递 --auto-repair=false 进行严格验证；超规格的值随后会作为渲染错误呈现。

# 将主体标题移出说话者的面部。bbox 是 x1,y1,x2,y2，以画布像素为单位（左上角原点）。
wonda transitions run --media $VID --clips ./timeline.json \
  --face-bbox 200,160,520,520 --wait -o out.mp4

# 严格模式——禁用自动修复以准确查看哪些片段验证失败。
wonda transitions run --media $VID --clips ./timeline.json \
  --auto-repair=false --wait -o out.mp4

--face-bbox 仅移动主体标题。你想放在说话者后面的装饰性文字仍然需要通过显式的 mask_cutout {prompt: "person"} 片段路由。

输出 URL 路径因任务类型而异：

• 推理任务（generate、audio）：.outputs[0].media.url 和 .outputs[0].media.mediaId
• 编辑器任务（edit）：.outputs[0].url 和 .outputs[0].mediaId

模型瀑布

图片

默认：gpt-image-2。OpenAI 的旗舰——最强的提示遵守、最佳图片内文字、通过参考图像的高保真编辑。处理 1-4 张参考图像。质量级别：auto（默认）、low、medium、high——通过 --params '{"quality":"high"}' 传递。输出上限为 1536px。

对于专门的 img2img 编辑（更改、添加/删除、重新风格化、背景移除、裁剪、文字叠加、矢量化），使用 wonda skill get image-edit——它有完整的编辑特定决策树。

仅当以下情况之一适用时才选择其他模型：

• 用户明确要求另一个模型
• 超过 4 张参考图像 → nano-banana-2（gpt-image-2 上限为 4 张参考；nano-banana-2 接受最多 14 张）。对于 1-4 张参考，保持在 gpt-image-2。
• 需要矢量输出 → runware-vectorize
• 需要背景移除 → birefnet-bg-removal
• 最便宜/最快草稿 → z-image
• 需要 >1536px / 真正的 4K 输出 → nano-banana-pro（1K/2K/4K）或 nano-banana-2（1K/2K/4K）。gpt-image-2 输出上限为 1536px。
• gpt-image-2 不可用 / OpenAI 宕机 → nano-banana-2 或 seedream-4-5 或 grok-imagine-pro

视频

默认：seedance-2（时长 5/10/15s，默认 5s，质量：high）。升级：

• 质量投诉或不同风格 → sora2 或 sora2pro
• 单个片段最长时长为 Seedance 2 的 15s，Sora 的 20s → 对于更长的内容，通过合并多个片段来实现
• Veo（veo3_1、veo3_1-fast）可用，但不在默认瀑布中。仅当用户明确按名称要求 Veo 时才选择 Veo。
• Gemini Omni（gemini-omni-video）可用，但不在默认瀑布中。仅当用户要求 Gemini 按名称，或特别需要多图像参考 T2V/I2V（最多 7 张参考图像）或 4K 输出时才选择它。

图像到视频路由（当附加参考图像时强制）：

• 参考图像中出现人物/面部 → 必须使用 kling_3_pro（对面部保留更好）
• 参考图像中没有人 → 使用 seedance-2
• 文本到视频（无参考图像）： Seedance 2 生成人物没有问题。此规则仅在你 --attach 图像时适用。

Kling 模型系列：

• kling_3_pro — 文本到视频和图像到视频，支持起始/结束图像、自定义元素（@Element1、@Element2），3-15s 时长，16:9/9:16/1:1
• kling_2_6_pro — 通用，5-10s，16:9/9:16/1:1，文本到视频和图像到视频
• kling_2_6_motion_control — 动作转移：需要参考图像 AND 参考视频，用图像的外观重现视频的动作
• kling2_5-pro — 预算 Kling 选项，5-10s，支持首/末帧图像

Kling 提示规则（重要）： Kling 的提示字段上限为 2,500 个字符，Kling 对 Sora 风格的结构化摘要（SCENE: / SUBJECT: / MOTION: / BANNED LOOK: 节标题）反应不佳。在这种格式下，Kling 会锁定氛围名词并静默丢弃中心主体（经验验证：同一份 2,842 字符的 Sora 风格提示在 Sora 2 Pro 和 Seedance 2 上正确渲染，但在 Kling 上完全没有显示手机——即使裁剪到 2,250 字符）。当从 Seedance 升级到 Kling，或直接针对 Kling 时，将提示重写为简短的自然语言散文（约 1,000–1,500 字符） 并且在开头句子中以主角主体开头，而不是将其埋藏在 SUBJECT: 块内。不要将 Sora 格式的提示原封不动地传递给 Kling。

其他视频模型：

• grok-imagine-video — xAI 视频生成，5-15s，支持 7 种宽高比，包括 4:3 和 3:2
• gemini-omni-video：Google Gemini Omni。文本到视频和图像到视频，最多 7 张参考图像（插槽 reference_image_1 到 reference_image_7）。时长 4/6/8/10s，宽高比 9:16 和 16:9，分辨率 720p / 1080p / 4K。定价：720p/1080p 下 $0.15 基础 + $0.075/秒，4K 下 $0.75 基础 + $0.075/秒。无原生音频（如果需要语音，与单独的音频模型配对）。
• topaz-video-upscale — 视频分辨率放大（1-4 倍因子，支持帧率转换）
• sync-lipsync-v2-pro — 用户提供的视频 + 音频对的传统口型同步。不如原生音频生成好，对于新内容几乎从来不是正确选择。有关规则，请参见“口型同步”部分。

Seedance 系列（默认视频模型，水印自动移除）：

• seedance-2 — 基础 Seedance 2.0（T2V/I2V，5-15s，high=standard/basic=fast）
• seedance-2-omni — 多参考生成（图像、音频参考）
• seedance-2-video-edit — 通过文本提示编辑现有视频

视频时长： 接受的 --duration 值因模型而异。使用 wonda capabilities 或 wonda models info <slug> 检查。

音频

• 音乐：suno-music（设置 --params '{"instrumental":true}' 以排除人声）
• 文本转语音：elevenlabs-tts — 仅用于在静默片段上显式的旁白/画外音需求。不要用来“让 UGC 角色说话”——Sora / Sora 2 Pro / Veo 3.1 / Kling 3 / Seedance 2 会生成任何语言的本地同步语音，看起来和听起来都好得多。始终在参数中设置 voiceId。默认女性声音：--params '{"voiceId":"21m00Tcm4TlvDq8ikWAM"}'（Rachel）。
• 转录：elevenlabs-stt
• 多说话人对话：elevenlabs-dialogue
• 音频增强（清理嘈杂语音）：通过 wonda audio enhance 使用 replicate-resemble-enhance — 去噪 + 去混响。当录音听起来闷闷的、有回声或背景噪音时使用。不是通用的“听起来更好”按钮；如果源已经干净，这可能会使其变软。
• 提取声音（分离人声 / 分离音轨）：通过 wonda audio extract-voice 使用 replicate-demucs — 分离为人声和器乐轨道。用于从轨道中提取说话者或歌手，或隔离人声后面的音乐。

原生同步语音（优于 TTS + 口型同步）： Sora、Sora 2 Pro、Veo 3.1、Kling 3 和 Seedance 2 都在视频内部直接生成任何语言的对话，口型动作已内置。将台词（和语言）放在视频模型的 --prompt 中。永远不要链式调用 elevenlabs-tts → sync-lipsync-v2-pro 来为无声生成伪造语音。

角色

角色是可重用的保存组合（图像 + 可选的语音音频），你可以在提示中用 @name 提及。服务器会自动将图像、可选面部视频和音频注入到所选模型的适当插槽中。适用于 Kling 3 Pro（start_image + element_1 + voice_audio）和 Seedance 2 Omni（ref_image_1 + ref_video_1 + ref_audio_1）。名称规则：必须以字母开头，1-31 个字符，字母数字 + _/-。

提供商注意事项（Seedance 2 Omni）： 当角色被提及时，API 会自动将 Seedance 路由到 MuAPI。Replicate 强制对 ref_audio_1 施加 15s 上限，并拒绝著名名人参考，返回 E005 — input flagged as sensitive。MuAPI 是角色驱动任务的可靠路径。即使在 MuAPI 上，顶级名人参考（想象 Sydney Sweeney、Leonardo DiCaprio）也会被阻止，返回 "Face detected in uploaded image. Please use an image without real people." 非名人面孔和不太知名的公众人物可以顺利通过。如果你在真实人物参考上看到此错误，请改用 Kling 3 Pro（其角色管线在服务器端运行语音克隆，因此原始面部音频永远不会触及审核分类器）。

从 Kling 片段中 — 从你喜欢的生成中提取帧 + 声音：

VID=$(wonda generate video --model kling_3_pro --prompt "young man, grey tshirt, talking to camera" --wait --quiet)
VID_MEDIA=$(wonda jobs get inference $VID --jq '.outputs[0].media.mediaId')
wonda character from-media alex --source $VID_MEDIA --frame-ms 2500
wonda generate video --model kling_3_pro --prompt "@alex welcomes viewers to the channel" --wait -o alex-welcome.mp4

从头开始 — 生成肖像和 TTS 样本，然后绑定它们：

IMG=$(wonda generate image --model nano-banana-2 --prompt "young woman, studio portrait" --wait --quiet)
IMG_MEDIA=$(wonda jobs get inference $IMG --jq '.outputs[0].media.mediaId')
AUD=$(wonda audio speech --model elevenlabs-tts --prompt "Hi, this is me" --params '{"voiceId":"21m00Tcm4TlvDq8ikWAM"}' --wait --quiet)
AUD_MEDIA=$(wonda jobs get inference $AUD --jq '.outputs[0].media.mediaId')
wonda character create maya --image $IMG_MEDIA --audio $AUD_MEDIA

列出 / 检查 / 更新 / 删除：wonda character list、wonda character get <name>、wonda character update <name> --audio $NEW、wonda character delete <name>。每次生成只能引用一个带有音频的角色。

提示编写规则

按以下瀑布顺序从上到下进行。使用第一个匹配的规则并停止。

1. 透传 — 如果用户说“使用我确切的提示”/“逐字”/“无增强” → 逐字复制他们的文字。零修改。

1. 图像到视频 — 当源图像馈送到视频模型时，仅描述运动。模型可以看到图像。不要描述图像内容。

• 好："gentle breathing motion, camera slowly pushes in, atmospheric lighting shifts"
• 坏："Two cats on a lavender background breathing softly"（描述了图像）

1. 空提示（从头开始） — 将用户的确切请求用作提示。不要添加风格描述符、灯光、构图或情绪。

• 用户说“create an image of a cat with sunglasses” → 提示："create an image of a cat with sunglasses"
• 不要增强为 "A playful orange tabby wearing oversized reflective sunglasses, studio lighting, shallow depth of field"

1. 非空提示（改编模板） — 保持结构和风格，仅交换内容以匹配用户的请求。保持提示字面和约束密集。

宽高比规则

三种情况，没有例外：

1. 用户指定了比例 → 使用它：--aspect-ratio 16:9
2. 用户没有提到比例 → 对于社交内容（UGC、TikTok、Reels、Stories）明确设置 --aspect-ratio 9:16。竖屏是任何社交/营销视频的默认值。
3. 编辑现有媒体 → 使用 --aspect-ratio auto 以保留源尺寸

UGC 和社交内容始终是竖屏（9:16）。 如果有人要求 TikTok、Reel、Story 或 UGC 视频，始终使用 --aspect-ratio 9:16。横屏仅用于 YouTube、演示文稿或明确要求时。

正方形（1:1） 所有 Kling 模型和一些图像模型都支持——在要求时用于 Instagram 帖子。

常见链式模式

这些模式展示了如何通过链式调用 CLI 命令来组合多步骤管线。每个步骤的输出馈送到下一步。

无需在步骤之间下载和重新上传。 每次生成和编辑

都会在其输出中产生一个媒体 ID。将该 ID 直接传递给下一个命令

通过 --media 或 --audio-media。使用 --jq '.outputs[0].media.mediaId'

用于推理任务，使用 --jq '.outputs[0].mediaId' 用于编辑器任务。

仅在最后步骤使用 -o <file> 下载最终输出。

将图像动画化为视频

MEDIA=$(wonda media upload ./product.jpg --quiet)
# 图像中没有人 → Seedance 2
wonda generate video --model seedance-2 --prompt "camera slowly pushes in, product rotates" \
  --attach $MEDIA --duration 5 --params '{"quality":"high"}' --wait -o animated.mp4
# 图像中有人 → Kling（仅当附加包含人物的参考图像时）
wonda generate video --model kling_3_pro --prompt "the person turns and smiles" \
  --attach $MEDIA --duration 5 --wait -o person.mp4

替换视频上的音频（TTS 画外音或音乐）

# 生成 TTS
TTS_JOB=$(wonda audio speech --model elevenlabs-tts --prompt "The script" \
  --params '{"voiceId":"21m00Tcm4TlvDq8ikWAM"}' --wait --quiet)
TTS_MEDIA=$(wonda jobs get inference $TTS_JOB --jq '.outputs[0].media.mediaId')
# 混合到视频（静音原始音频，完整画外音）
wonda edit video --operation editAudio --media $VID_MEDIA --audio-media $TTS_MEDIA \
  --params '{"videoVolume":0,"audioVolume":100}' --wait -o with-voice.mp4

仅当你需要替换视频的音频时才使用此方法。Sora、Sora 2 Pro、Veo 3.1、Kling 3 和 Seedance 2 都会生成任何语言的本地同步语音——除非用户明确要求不同的画外音，否则不要用 TTS 替换它。永远不要为了“添加语音”到 UGC/说话头部片段而使用此步骤；将对话放在视频模型的提示中。

添加静态文字叠加

静态叠加（梗文字、“chat did i cook”等）使用比字幕更小的字号。它们是环境性的，不旨在主导画面。

wonda edit video --operation textOverlay --media $VID_MEDIA \
  --prompt-text "chat, did i cook" \
  --params '{"fontFamily":"TikTok Sans SemiCondensed","position":"top-center","sizePercent":66,"fontSizeScale":0.5,"strokeWidth":4.5,"paddingTop":10}' \
  --wait -o with-text.mp4

精选 textOverlay + animatedCaptions 预设。 wonda edit {video,image,audio} 接受 --preset <name>（作用域为 --operation）。--params 字段在键冲突时覆盖预设值。

textOverlay（静态，顶部居中）：

• TikTok White Highlight — 黑色文字在轻微圆角的白色框上。
• TikTok Black Highlight — 白色文字在轻微圆角的黑色框上。
• TikTok Red Highlight — 白色文字在轻微圆角的红色（#E14135）框上。

animatedCaptions（STT 驱动，底部居中）：

• TikTok White Captions — 黑色文字，活跃单词白色高亮。
• TikTok Black Captions — 白色文字，活跃单词黑色高亮。
• TikTok Red Captions — 白色文字，活跃单词红色（#E14135）高亮。

wonda edit video --operation textOverlay \
  --preset "TikTok Red Highlight" --media <id> \
  --params '{"text":"YOUR HEADLINE"}' --wait -o ./out.mp4

textOverlay 通过捆绑的 hyperframes（Chromium）渲染器在本地渲染。不再有服务器端图像 textOverlay。

字体大小指南：

• 静态叠加：sizePercent: 66、fontSizeScale: 0.5、strokeWidth: 4.5
• 动画字幕：sizePercent: 80、fontSizeScale: 0.8、strokeWidth: 2.5、highlightColor: rgb(252, 61, 61)
• 字体：两者都使用 TikTok Sans SemiCondensed

添加动画字幕（逐词带时间）

animatedCaptions 操作提取音频、转录并渲染逐词动画字幕——一步完成。

wonda edit video --operation animatedCaptions --media $VIDEO_MEDIA \
  --params '{"fontFamily":"TikTok Sans SemiCondensed","position":"bottom-center","sizePercent":80,"strokeWidth":2.5,"fontSizeScale":0.8,"highlightColor":"rgb(252, 61, 61)"}' \
  --wait -o with-captions.mp4

对于快速静态字幕（无时间，仅屏幕上的文字），使用带有 --prompt-text 的 textOverlay：

wonda edit video --operation textOverlay --media $VIDEO_MEDIA \
  --prompt-text "Summer Sale - 50% Off" \
  --params '{"fontFamily":"TikTok Sans SemiCondensed","position":"bottom-center","sizePercent":80}' \
  --wait -o captioned.mp4

添加背景音乐

MUSIC_JOB=$(wonda generate music --model suno-music \
  --prompt "upbeat lo-fi hip hop, warm vinyl crackle" --wait --quiet)
MUSIC_MEDIA=$(wonda jobs get inference $MUSIC_JOB --jq '.outputs[0].media.mediaId')
wonda edit video --operation editAudio --media $VID_MEDIA --audio-media $MUSIC_MEDIA \
  --params '{"videoVolume":100,"audioVolume":30}' --wait -o with-music.mp4

编辑器输出链式调用

当链式调用多个编辑器操作（例如 editAudio → animatedCaptions → textOverlay）时，从每个编辑器任务输出中提取媒体 ID，并传递给下一步。注意 jq 路径与推理任务不同：

# 推理任务：.outputs[0].media.mediaId
# 编辑器任务：.outputs[0].mediaId

EDIT_JOB=$(wonda edit video --operation editAudio --media $VID --audio-media $AUDIO \
  --params '{"videoVolume":0,"audioVolume":100}' --wait --quiet)
STEP1_MEDIA=$(wonda jobs get editor $EDIT_JOB --jq '.outputs[0].mediaId')

CAP_JOB=$(wonda edit video --operation animatedCaptions --media $STEP1_MEDIA \
  --params '{"fontFamily":"TikTok Sans SemiCondensed","position":"bottom-center","sizePercent":80,"strokeWidth":2.5,"fontSizeScale":0.8,"highlightColor":"rgb(252, 61, 61)"}' --wait --quiet)
STEP2_MEDIA=$(wonda jobs get editor $CAP_JOB --jq '.outputs[0].mediaId')

wonda edit video --operation textOverlay --media $STEP2_MEDIA \
  --prompt-text "Hook text" --params '{"position":"top-center","fontFamily":"TikTok Sans SemiCondensed","sizePercent":66,"fontSizeScale":0.5,"strokeWidth":4.5}' --wait -o final.mp4

合并多个片段

始终使用 ffmpeg 在本地合并。 服务器端合并（wonda edit video --operation merge）一旦任何输入超过约 7MB，可能会挂起 30 分钟以上。

下载每个 Wonda 媒体 ID，然后拼接。流复制很快，但需要匹配的编解码器/配置文件/分辨率；如果出错则回退到重新编码：

wonda media download $CLIP1 -o /tmp/clip-1.mp4
wonda media download $CLIP2 -o /tmp/clip-2.mp4
wonda media download $CLIP3 -o /tmp/clip-3.mp4
cat > /tmp/concat.txt <<EOF
file '/tmp/clip-1.mp4'
file '/tmp/clip-2.mp4'
file '/tmp/clip-3.mp4'
EOF
ffmpeg -y -f concat -safe 0 -i /tmp/concat.txt -c copy /tmp/merged.mp4
# 如果流复制失败，重新编码：
# ffmpeg -y -f concat -safe 0 -i /tmp/concat.txt \
#   -c:v libx264 -preset medium -crf 18 -pix_fmt yuv420p -movflags +faststart \
#   -c:a aac -b:a 192k /tmp/merged.mp4

# 仅当下游 wonda 步骤需要 mediaId 时才重新上传。
MERGED_MEDIA=$(wonda media upload /tmp/merged.mp4 --quiet)

concat.txt 中的文件顺序 = 播放顺序。有关完整拼接参考，请参见 ffmpeg 技能。

分割场景 / 保留特定场景

两种模式，根据目的选择：

# 分割模式（默认）——返回每个检测到的场景作为自己的媒体。
# JSON 输出在 scenes[] 下列出每个场景（{mediaId,index,startS,endS}）。
wonda edit video --operation splitScenes --media $VID_MEDIA \
  --params '{"mode":"split","threshold":0.5,"minClipDuration":2}' --json
# 使用 -o，每个场景下载到编号文件（out-1.mp4、out-2.mp4、...）；
# 单个检测到的场景直接写入路径。
wonda edit video --operation splitScenes --media $VID_MEDIA \
  --params '{"mode":"split","threshold":0.5,"minClipDuration":2}' -o scenes.mp4

# 移除一个场景（省略模式）——移除一个场景，合并其余部分到一个文件。
wonda edit video --operation splitScenes --media $VID_MEDIA \
  --params '{"mode":"omit","threshold":0.5,"minClipDuration":2,"outputSelection":"first"}' \
  --wait -o without-first.mp4
# outputSelection（仅省略模式）："first"、"last" 或从 1 开始的数字 = 要 REMOVE 的场景

对“移除冻结的第一帧”（Sora 视频常见）使用省略模式。使用分割模式获取所有场景作为单独的片段。

图片编辑

任何图片编辑——img2img、背景移除、裁剪、文字叠加、矢量化——都有其自己的技能，包含完整的决策树、宽高比规则和编辑的模型瀑布：

wonda skill get image-edit

一个值得在这里记住的陷阱：图像和视频背景移除使用不同的模型（birefnet-bg-removal 与 bria-video-background-removal）。永远不要交换它们。

口型同步（最后手段回退——首选原生音频视频模型）

Sora、Sora 2 Pro、Veo 3.1、Kling 3 和 Seedance 2 都会作为视频本身的一部分生成任何语言的语音，并带有正确同步的口型动作。该路径比 sync-lipsync-v2-pro 产生显著更好的结果：更好的口型物理、更好的光线、更好的成本，没有第二次推理往返。对于任何说话的 UGC、广告或发言人视频，将对话直接放在视频模型的提示中——不要链式调用 TTS + 口型同步。

仅当用户明确提供预先存在的视频和预先存在的音频片段并要求你将口型对齐到该音频时，才考虑 sync-lipsync-v2-pro。如果用户要求口型同步作为让角色说话默认方法，请说服他们：原生音频视频模型是更好的工具，并且适用于任何语言。

wonda generate video --model sync-lipsync-v2-pro --attach $VIDEO_MEDIA,$AUDIO_MEDIA --wait -o synced.mp4

视频放大

wonda generate video --model topaz-video-upscale --attach $VIDEO_MEDIA \
  --params '{"upscaleFactor":2}' --wait -o upscaled.mp4

剪辑（长视频 → 竖屏短视频）

wonda clipping 将长视频（播客、采访、说话头部）

转换为短视频片段。选择是 LLM 驱动的，支持

自然语言 --brief，因此你可以要求特定时刻，而不是通用病毒性。

V1 渲染 9:16 的面部跟踪重新构图（LR-ASD 活跃说话者

检测 + One-Euro 稳定器，默认）和现有的

animatedCaptions 操作 + 每个片段顶部三分之一钩子叠加。传递

--reframe blur-fill 以在带有模糊背景的竖屏画布内

保持完整的横屏源。

异步：POST /api/v1/clipping 返回一个 clippingJobId；CLI 轮询

GET /api/v1/clipping/jobs/{id} 在 --wait 下。传递 --output <dir>

，CLI 会下载每个渲染的片段 + 一个 plan.json。

身份验证：在生产环境中需要 clippingEnabled PostHog 功能标志；本地

dev 自动绕过。

源： --url 接受 YouTube 和直接 mp4 URL。

wonda clipping --url "<youtube-url>" --brief "the most controversial moments" --wait

YouTube 链接有效；长视频在转录开始前可能需要几分钟才能摄取。如果 YouTube 摄取失败，本地下载文件并先上传，然后使用 --media 进行剪辑：

yt-dlp -o /tmp/source.mp4 \
  -f "bv*[ext=mp4][height<=720]+ba[ext=m4a]/b[ext=mp4][height<=720]" \
  --merge-output-format mp4 "<youtube-url>"
MEDIA=$(wonda media upload /tmp/source.mp4 --quiet)

# 仅计划——快速，不渲染
wonda clipping --media $MEDIA --brief "the most controversial moments" --dry-run --wait

# 完整管线：选择 + 渲染 + 下载
wonda clipping --media $MEDIA \
  --brief "the most controversial moments" \
  --caption-preset "TikTok Red Captions" \
  --hook auto \
  --wait --output ./clips/

# 按说话者过滤（使用 ElevenLabs 说话人标签）
wonda clipping --media $MEDIA --speaker SPEAKER_00 --wait --output ./clips/

# 说话者重命名以获得可读的理由
wonda clipping --media $MEDIA --speaker Joe \
  --speaker-map '{"SPEAKER_00":"Joe","SPEAKER_01":"Guest"}' --wait --output ./clips/

# 调整数量和时长——选择目标长度并带公差
wonda clipping --media $MEDIA --brief "punchy one-liners" \
  --count 5 --duration 20 --tolerance 5 --wait --output ./clips/

# 或者指定显式的 min/max 范围（与 --duration/--tolerance 互斥）
wonda clipping --media $MEDIA --brief "punchy one-liners" \
  --count 5 --min-duration 8 --max-duration 30 --wait --output ./clips/

# 从目录中自动为每个片段选择 FX 预设
wonda clipping --media $MEDIA --auto-preset \
  --preset-catalog '[{"slug":"flash_glow","description":"glow + scene flash"},{"slug":"text_glow","description":"per-word text glow"}]' \
  --wait --output ./clips/

任务状态形状（由 GET /api/v1/clipping/jobs/{id} 返回）：

{
  "clippingJobId": "...",
  "status": "succeeded",
  "stage": "succeeded",
  "progress": 1,
  "plan": {
    "sourceDurationSec": 1800.5,
    "speakers": ["SPEAKER_00", "SPEAKER_01"],
    "clips": [
      {
        "start": 12.4,
        "end": 38.7,
        "title": "Why he quit the agency",
        "hookText": "He admits…",
        "rationale": "Concedes \"the agency model is dead\" then explains why...",
        "score": 87,
        "dominantSpeaker": "SPEAKER_00",
        "reframeMode": "blur-fill",
        "preset": null,
        "mediaId": "uuid-of-rendered-clip",
        "url": "https://storage.googleapis.com/.../clip.mp4"
      }
    ]
  },
  "error": null
}

编辑器操作参考

crop 与 imageCrop： 视频 crop 是基于比例/百分比的（aspectRatio 或 cropPercent+cropAxis）；它不接受像素坐标，并且会拒绝 cropPixelX/Y/Width/Height 并报错。对于精确像素矩形，使用 imageCrop。运行 wonda operations info <operation> 以获取任何操作的完整参数列表、默认值和范围。

有效的 textOverlay 字体：Inter、Montserrat、Bebas Neue、Oswald、TikTok Sans、TikTok Sans Condensed、TikTok Sans SemiCondensed、TikTok Sans SemiExpanded、TikTok Sans Expanded、TikTok Sans ExtraExpanded、Nohemi、Poppins、Raleway、Anton、Comic Cat、Gavency

有效位置：top-left、top-center、top-right、center-left、center、center-right、bottom-left、bottom-center、bottom-right

营销与分发

# 连接的社交账户
wonda accounts instagram
wonda accounts tiktok

# 分析
wonda analytics instagram
wonda analytics tiktok
wonda analytics meta-ads

# 抓取竞争对手
wonda scrape social --handle @nike --platform instagram --wait
wonda scrape social-status <taskId>                   # 获取社交抓取结果
wonda scrape ads --query "sneakers" --country US --wait
wonda scrape ads --query "sneakers" --country US --search-type keyword \
  --active-status active --sort-by impressions_desc --period last30d \
  --media-type video --max-results 50 --wait
wonda scrape ads-status <taskId>                      # 获取广告搜索结果

# 下载单个 Reel 或 TikTok 视频
SCRAPE=$(wonda scrape video --url "https://www.instagram.com/reel/ABC123/" --wait --quiet)
# → 返回抓取结果，媒体数组中包含 mediaId

# 发布
wonda publish instagram --media <id> --account <accountId> --caption "New drop"
wonda publish instagram --media <id> --account <accountId> --caption "..." --alt-text "..." --product IMAGE --share-to-feed
wonda publish instagram-carousel --media <id1>,<id2>,<id3> --account <accountId> --caption "..."
wonda tiktok creator-info --account <accountId>      # 实时隐私选项 + 评论/二重唱/接唱默认值
wonda publish tiktok --media <id> --account <accountId> --caption "New drop" --privacy PUBLIC_TO_EVERYONE
wonda publish tiktok --media <id> --account <accountId> --caption "..." --privacy PUBLIC_TO_EVERYONE \
  --disable-comment --commercial-disclose --brand-organic
wonda publish tiktok-carousel --media <id1>,<id2> --account <accountId> --caption "..." \
  --privacy PUBLIC_TO_EVERYONE --cover-index 0

# 安排帖子（Instagram 和 TikTok 单帖）
wonda publish instagram --media <id> --account <accountId> --caption "..." --scheduled-at 2026-05-01T14:00:00Z
wonda publish tiktok --media <id> --account <accountId> --caption "..." --scheduled-at 2026-05-01T14:00:00-07:00
# --scheduled-at 接受带时区的 RFC3339 时间戳；5 分钟到 29 天内。

# 管理已安排的任务
wonda publish scheduled list                  # 列出待处理的已安排帖子
wonda publish scheduled cancel <outputJobId>  # 在发布前取消

# 历史
wonda publish history instagram --limit 10
wonda publish history tiktok --limit 10

# 浏览媒体库
wonda media list --kind image --limit 20
wonda media info <mediaId>

X/Twitter

支持读取、写入和社交图谱。

⚠️ 反欺诈注意：不要探测刚粘贴的 cookie。 当你刚刚收到 cookie（你自己的或用户的）时，它们上的第一个请求应该是用户实际想要的操作，而不是 wonda x auth check、不是 wonda x home、也不是任何会触发探测的操作。新 IP/设备/进程上的突发活动是 X（以及 Reddit、LinkedIn、IG）标记为凭据盗窃的典型信号，cookie 会被影子封禁或硬性杀死。如果必须验证，请使用 wonda x auth check --account <name> --via wab（它通过账户现有的已登录浏览器会话路由：相同 IP、相同指纹、相同浏览历史），而不是从新进程触发原始的 API 请求。

# 身份验证设置（运行 `wonda x auth --help` 了解详情）
wonda x auth set --auth-token <token> --ct0 <ct0>
wonda x auth set --account burner --auth-token <...> --ct0 <...>  # 多账户
wonda x auth check                                              # 原始探测，见上方警告
wonda x auth check --account <name> --via wab               # 安全：通过账户的 WAB 会话路由

# 读取
wonda x search "sneakers" -n 20                     # 搜索推文
wonda x user @nike                                   # 用户资料
wonda x user-tweets @nike -n 20                      # 用户的近期推文
wonda x read <tweet-id-or-url>                       # 单条推文
wonda x replies <tweet-id-or-url>                    # 推文的回复
wonda x thread <tweet-id-or-url>                     # 完整线程（作者的自回复）
wonda x home                                         # 首页时间线（--following 为“正在关注”选项卡）
wonda x bookmarks                                    # 你的书签
wonda x likes                                        # 你点赞的推文
wonda x following @handle                            # 谁关注了某个用户
wonda x followers @handle                            # 某个用户的关注者
wonda x lists @handle                                # 用户的列表（--member-of 为成员身份）
wonda x list-timeline <list-id-or-url>               # 列表中的推文
wonda x news --tab trending                          # 热门话题（标签页：for_you、trending、news、sports、entertainment）

# 写入（默认为 --via wab；在辅助账户上传递 --via cookies 用于内部 API 路径）
wonda x tweet "Hello world"                          # 发布推文
wonda x tweet "Hello world" --account <name> --via wab  # 通过真实浏览器完全隐身
wonda x tweet "Hello world" --attach ~/clip.mp4      # 附加图片/gif/视频（最多 4 个）
wonda x reply <tweet-id-or-url> "Great point"        # 回复
wonda x like <tweet-id-or-url>                       # 点赞
wonda x unlike <tweet-id-or-url>                     # 取消点赞
wonda x retweet <tweet-id-or-url>                    # 转发
wonda x unretweet <tweet-id-or-url>                  # 取消转发
wonda x follow @handle                               # 关注
wonda x unfollow @handle                             # 取消关注

# 维护
wonda x refresh-ids                                  # 从 X 的 JS 包刷新缓存的 GraphQL 查询 ID

所有分页命令支持：-n <count>、--cursor、--all、--max-pages、--delay <ms>。

推文模式： tweet 命令有两种传输方式：

• --via cookies（内部 API）： X 的内部 GraphQL（CreateTweet 用于 ≤280 字符，CreateNoteTweet 用于长格式 Premium）。快速（<1s），支持 --attach 用于媒体。偶尔在 X 轮换查询 ID 或功能标志时会失败，错误 226。发生这种情况时，通过 twitter-tone-research/_artifacts/scripts/capture-ct-bw.mjs 重新捕获，并调整 xclient/ 中的三个参数。
• --via wab（写入的默认值）： 通过账户的 WAB Chromium（首次 --via wab 使用时自动启动）路由，打开 x.com 编辑器，以人类风格抖动输入，点击发布。支持 --attach（图片/gif/视频，最多 4 个）；文件通过 Playwright 的 setInputFiles 驱动到隐藏的编辑器输入，不会打开原生选择器对话框；脚本在提交前等待 X 的上传管线完成（视频最多 5 分钟）。零指纹风险。较慢（文本约 10 秒，带视频约 30-90 秒）但完全抗漂移：无需维护 queryIds、功能标志或请求形状。Patchright + Chromium 通过 wonda wab install 一次性安装（约 315 MB，一次性，幂等）。Cookie 保存在 ~/.wonda/x-cookies/<account>.json，通过 account-bindings.json 绑定到账户的人设。wonda x reply --attach 仅支持 wab（无 cookie 路径）。

LinkedIn

支持搜索、资料、公司、私信和互动。

⚠️ 与 X 相同的反欺诈注意：不要探测刚粘贴的 cookie。 新 cookie 上的第一个请求 = 实际操作，而不是检查。LinkedIn 的反欺诈是所有平台中最激进的（强制登出、密码重置、账户标记）。如果必须验证，请使用 wonda linkedin auth check --account <name> --via wab 通过账户现有的 WAB 会话路由。

# 身份验证设置（运行 `wonda linkedin auth --help` 了解详情）
wonda linkedin auth set --li-at-value <v> --jsessionid-value <v>
wonda linkedin auth set --account brand-A --li-at-value <...> --jsessionid-value <...>  # 多账户
wonda linkedin auth check                                              # 原始探测，见上方警告
wonda linkedin auth check --account <name> --via wab               # 安全：通过账户的 WAB 会话路由

# 读取
wonda linkedin me                                    # 你的身份
wonda linkedin search "data engineer" --type PEOPLE  # 搜索（类型：PEOPLE、COMPANIES、ALL）
wonda linkedin profile johndoe                       # 查看资料（虚荣名称或 URL）
wonda linkedin company google                        # 查看公司页面
wonda linkedin conversations                         # 列出消息线程
wonda linkedin messages <conversation-urn>           # 读取线程中的消息
wonda linkedin notifications -n 20                   # 最近通知
wonda linkedin connections                           # 你的连接
wonda linkedin connection-status johndoe janedoe     # 每个成员：connected / pending (in|out) / not_connected（仅 cookie）
wonda linkedin saves                                 # 你保存的帖子（My Items → Saved posts；--all、--enrich 用于点赞/评论）
wonda linkedin reactions <activity-id>               # 带反应者资料 + 类型的反应
wonda linkedin browser-bootstrap                     # 将存储的 cookie 注入 WAB 配置文件（一次性 + 轮换时）
wonda linkedin comments <activity-id> --account <name> --via wab  # 评论者带资料 + 虚荣名称（自动启动 WAB）
wonda linkedin search-posts "<keyword>" --date-range past-week --account <name>  # 关键词到近期帖子 + 作者资料（通过 WAB 的 DOM 抓取；用于社交监听，参见 content-skills/linkedin-social-listening.md）

# WAB 生命周期（参见 `wonda wab --help` 获取完整表面：start/stop/status/install/bind/sync-cookies/logs）
wonda linkedin enrich-engagers --activity-id <id>    # 抓取互动者 + 使用资料和当前雇主丰富每个（合并 JSON）

# 写入
wonda linkedin connect <vanity-name> --message "Hey!" # 发送附言连接请求
wonda linkedin connect <vanity-name> -m "Hey!" --account <name> --via wab  # 通过账户人设完全隐身
wonda linkedin comment <activity-id> --account <name> # 添加评论（仅 wab：需要 SDUI 渲染状态）
wonda linkedin like <activity-urn>                   # 点赞帖子
wonda linkedin unlike <activity-urn>                 # 取消点赞
wonda linkedin send-message <conversation-urn> "Hi!" # 发送消息
wonda linkedin post "Excited to announce..."         # 创建帖子
wonda linkedin delete-post <activity-id>             # 删除帖子

分页命令支持：-n <count>、--start、--all、--max-pages、--delay <ms>。

连接请求模式： connect 命令有两种传输方式：

• --via cookies（API）： Voyager REST API，带指纹缓解措施（个人资料访问、抽屉预热、连接）。快速（约 3 秒），支持通过 customMessage 添加附言。
• --via wab： 通过账户的人设 Chromium（自动启动）路由，实现 DOM 分发的完全隐身。零指纹风险。较慢（约 10 秒）但完全安全。当你需要额外保护时使用。Patchright + Chromium 通过 wonda wab install 一次性安装（约 315 MB，幂等）。人设在其 ~/.wonda/wab/personas/<persona>/profile 下重用持久配置文件。Cookie 保存在 ~/.wonda/linkedin-cookies/<account>.json，通过 account-bindings.json 绑定到人设；通过 wonda linkedin auth set --account <name> 轮换会将新 cookie 推送到正在运行的 Chromium（如果它正在运行）。

互动者丰富： wonda linkedin enrich-engagers --activity-id <id> 抓取反应者（以及通过 --comments 可选评论者），然后获取每个互动者的资料 + 当前雇主 + 公司页面，并输出单个合并的 JSON 文档，以虚荣名称为键，每个互动者包含 profile 和 currentEmployer（行业、员工人数、总部、描述、员工计数）块。使用 --max-profiles N 限制批次（敏感账户默认 25，硬上限 100），使用 --out file.json 写入磁盘。

有关帖子互动者的 ICP 资格，请参见 content-skills/linkedin-icp-qualify.md。

Instagram

一个一流平台，具有三种传输方式，由 --via 选择，与其他平台相同的合法性梯度：

• --via api — 通过你连接的 OAuth 账户（--connection）的官方 Graph API。ToS 安全，用于发布。
• --via cookies — 通过本地 cookie --account 的私有移动 API。用于读取（保存的帖子、评论）。
• --via wab — 通过账户的 Wonda 自动化浏览器人设的浏览器 DOM。用于 comment 写入（驱动 Reel 的内联评论编辑器，带有真实浏览器指纹，与 X reply / LinkedIn comment 使用的隐身路径相同）。

传输方式是特定于操作的：saved 和 comments 仅 cookie（没有 Graph 端点），post/carousel 仅 API，comment 仅 wab。两个身份是不同的：--account/--sessionid = 本地 cookie 身份；--connection = OAuth instagram_account UUID。对于 --via wab，人设从 --account 自动派生（或直接传递 --persona）；WAB 在启动时将绑定账户的 sessionid（+ ds_user_id）注入 Chromium cookie 存储。

⚠️ 与其他平台相同的反欺诈注意：不要探测刚粘贴的 cookie。 新的 sessionid 上的第一个请求应该是你想要的操作。Instagram 会将新 IP/进程对刚提供的会话的突发活动标记为异常。

# 身份验证设置 — 本地 cookie 身份（运行 `wonda instagram auth --help` 了解详情）
wonda instagram auth set --sessionid <value>                # 仅 sessionid cookie（最简单）
wonda instagram auth set --cookies "$(pbpaste)"             # 完整 DevTools cookie 头部（也捕获 ds_user_id）
wonda instagram auth set --account burner --sessionid <v>   # 多账户
wonda instagram auth set --account burner --sessionid <v> --persona burner  # 也绑定到 WAB 人设

# 读取（cookies）
wonda instagram saved                                       # 你保存的帖子（--all 遍历所有页面）
wonda instagram saved --jq '.posts[] | {authorHandle, url}' # 从结果中投影字段
wonda instagram comments https://instagram.com/reel/<code>/ # 帖子/reel 的评论（--all 遍历所有页面）
wonda instagram comments <code> --jq '.comments[] | {authorHandle, text}'  # 裸短码也有效

# 发布（--via api，默认 — 通过你连接的账户的官方 Graph API）
wonda instagram post --media <media-id> --caption "Hello"   # 单张图片/reel
wonda instagram post --media <id> --connection <ig-uuid>    # 明确选择连接的账户
wonda instagram carousel --media <id1> --media <id2>        # 2-10 张图片轮播

# 评论 Reel（仅 --via wab — 通过 WAB 驱动内联编辑器）
wonda instagram comment https://instagram.com/reel/<code>/ "Great reel!" --persona my-account
wonda instagram comment <code> "Love this" --persona my-account   # 裸短码也有效

--account 选择 ~/.wonda/instagram-cookies/<account>.json 下的 cookie 文件。对于 saved，轮播贡献每个子项的媒体 URL（视频优先于图像作为每个项目的 URL）；分页使用 max_id 光标（--cursor、--all、--max-pages、--delay <ms>）。comments 接受 /p/<code>/ 或 /reel/<code>/ URL（或裸短码），在本地解码为数字媒体 ID，然后使用相同的 max_id 光标分页；结果携带每条评论的 id、text、authorHandle、authorName、createdAt、likeCount、replyCount 加上父媒体的总 commentCount。对于发布，wonda instagram post --via api 和 wonda publish instagram 共享相同的 Graph-API 路径。comment（写入）接受 /reel/<code>/ 或 /p/<code>/ URL（或裸短码）加上文本，仅 wab：它会根据需要自动启动人设的 WAB，输入到内联编辑器，提交，并将 comment 审计行写入 ~/.wonda/wab/audit.jsonl（失败会触发 wab_action_failed 遥测并生成失败包）。

Reddit

Reddit 的传输方式针对每种命令类型是固定的，因此 --via 在这里大多数情况下不是你能选择的：

• 读取（search、subreddit、feed、user、user-posts、user-comments、post、trending、home、saved）通过 Chrome 指纹化的 Go HTTP 客户端直接运行（快速，约 700ms p50）。仅 cookie。--via wab 对读取不可用，会报错。
• 写入（vote、comment、subscribe、save、unsave、delete 和 subreddit submit）通过账户的 Wonda 自动化浏览器分发，以便 shreddit GraphQL 突变携带真实浏览器信号。仅 WAB。在这些命令上 --via cookies 会报错。
• 向个人资料提交自我帖子（u_<handle> / u/<handle>）或链接帖子 仅通过 tls-client（cookie）进行。--via wab 对这些不可用（没有 DOM 提交 URL），因此 --dry-run（仅 DOM）也不适用于它们。

--account 选择 ~/.wonda/reddit-cookies/ 下的 cookie 文件（对于写入，还选择账户的自动派生人设）。你不在此处传递人设。

⚠️ 关于刚粘贴的 cookie 的反欺诈注意。 wonda reddit auth check 是安全的（它仅在本地解码 JWT 过期时间），但你在新 cookie 上发起的第一个读取或写入会从你的 IP/进程访问 Reddit 的 API。如果这些 cookie 上次在其他地方使用过（不同的机器、不同的国家），Reddit 的反欺诈会触发会话盗窃启发式检测，并可能强制登出这些 cookie。模式：粘贴 cookie，直接执行用户想要的操作。永远不要先做“让我检查一下这能否工作”的往返。

# 身份验证设置（运行 `wonda reddit auth --help` 了解详情）
wonda reddit auth set --cookies "$(pbpaste)"                         # 粘贴完整 DevTools cookie 头部
wonda reddit auth set --account burner-1 --cookies "$(pbpaste)"      # 多账户
wonda reddit auth set --account burner-1 --from-keychain             # 选择加入：从浏览器钥匙串读取
wonda reddit auth check

# 读取（直接 tls-client，--account 为登录视图选择会话）
wonda reddit search "AI video" --sort top --time week   # 搜索帖子（排序：relevance、hot、top、new、comments）
wonda reddit subreddit marketing                        # Subreddit 信息
wonda reddit feed marketing --sort hot                  # Subreddit 帖子（排序：hot、new、top、rising）
wonda reddit user spez                                  # 用户资料
wonda reddit user-posts spez --sort top                 # 用户的帖子
wonda reddit user-comments spez                         # 用户的评论
wonda reddit post <id-or-url> -n 50                     # 带评论的帖子
wonda reddit trending --sort hot                        # 热门/趋势帖子
wonda reddit home --sort best                           # 你的首页时间线（需要身份验证）
wonda reddit saved                                      # 你保存的帖子 + 评论（需要身份验证；--all 遍历所有页面）

# 写入（通过账户人设仅 wab；--account 选择身份）
wonda reddit submit marketing --title "Great tool" --text "Check this..." --account burner-1   # Subreddit 文本帖子（DOM）
wonda reddit submit u_<your-handle> --title "..." --text "..." --account burner-1               # 个人资料自我帖子（tls-client / 仅 cookie）
wonda reddit submit marketing --title "..." --url "https://..." --account burner-1              # 链接帖子（tls-client / 仅 cookie）
wonda reddit comment t3_<post-id> --text "Nice post!" --account burner-1
wonda reddit comment t1_<comment-id> --text "..." --post-id t3_<post-id> --account burner-1 # 嵌套回复（需要父帖子 ID）
wonda reddit vote <fullname> --up --account burner-1     # 点赞（--down、--unvote）
wonda reddit vote t1_<comment-id> --up --post-id t3_<post-id> --account burner-1
wonda reddit subscribe marketing --account burner-1      # 订阅（--unsub 取消订阅）
wonda reddit save <fullname> --account burner-1          # 保存帖子或评论（t1_* 需要 --post-id）
wonda reddit unsave <fullname> --account burner-1
wonda reddit delete <fullname> --account burner-1        # 删除自己的帖子或评论

在 subreddit comment 或 submit 上添加 --dry-run 以输入到编辑器但不点击发布（用于审查）。它仅 DOM，因此不适用于个人资料自我帖子或链接帖子。

分页命令支持：-n <count>、--after <cursor>、--all、--max-pages、--delay <ms>。

Reddit 聊天 / 私信

通过 Matrix 协议的直接消息。需要单独的聊天令牌。

# 身份验证设置（运行 `wonda reddit chat auth-set --help` 了解详情）
wonda reddit chat auth-set

# 读取
wonda reddit chat inbox                                  # 列出带最新消息的私信对话
wonda reddit chat messages <room-id> -n 50               # 从房间获取消息
wonda reddit chat all-rooms                              # 列出所有已加入的房间（不限于同步窗口）

# 写入
wonda reddit chat send <room-id> --text "Hey!"           # 发送私信（模拟浏览器输入行为）

# 管理
wonda reddit chat accept-all                             # 接受所有待处理的聊天请求
wonda reddit chat refresh                                # 强制刷新 Matrix 聊天令牌

重要：聊天令牌约每 24 小时过期。CLI 在使用时自动刷新，但如果完全过期，重新运行 auth-set。将私信发送速率限制为每天 15-20 条，并变化文本以避免检测。send 命令包含输入延迟（1-5 秒）以模拟人类行为。

云端数字分身（wonda twin）

管理在移动代理后面运行的云端托管社交角色。会话是服务器端的；计划表驱动定期任务（保存内容同步、互动、代理运行），基于 cron。

# 会话
wonda twin list                                          # 列出分身会话
wonda twin show <persona>                                # 显示一个会话
wonda twin provision <persona> --region GB               # 配置（标志：--provenance、--spend-cap <microdollars>、--allow <cmd>（可重复））
wonda twin pause <persona>                               # 暂停会话
wonda twin resume <persona>                              # 恢复暂停的会话
wonda twin needs-auth <persona>                          # 将会话标记为需要重新认证

# 计划表
wonda twin schedule list --persona <persona>             # 列出计划（--persona 可选）
wonda twin schedule add <persona> --cron "0 9 * * *" --kind saved_sync   # 添加（--kind：saved_sync|engage|agent；--command、--prompt、--mode deterministic|agent）
                                                         # --jitter-window-seconds N：在 cron 时间后的 N 秒内（cron 标记窗口开始），每天在随机时间触发一次；0/省略 = 精确在 cron 分钟触发
                                                         # --output-webhook <url>：将每次运行的捕获命令 stdout 发送到你的 HTTPS webhook（负载包含短期 TTL 的签名下载 URL）；--output-webhook-secret <s>：通过 X-Wonda-Signature 头部对正文进行 HMAC-SHA256 签名的密钥
wonda twin schedule enable <id>                          # 启用计划
wonda twin schedule disable <id>                         # 禁用计划
wonda twin schedule rm <id>                              # 删除计划

# 运行
wonda twin runs --persona <persona> --limit 20           # 最近运行
wonda twin run-now <persona> --command <cmd>             # 立即触发运行
wonda twin output <runId>                                # 获取运行的捕获命令输出（--url 仅打印短期 TTL 的签名下载 URL）

工作流与发现

品牌提取（brand extract）

将网站的设计系统（颜色、排版、圆角、阴影、间距、字体、徽标、英雄装饰、CSS 图案背景、虚线/点状边框处理、:root 自定义属性、标题强调模式、胶片颗粒/噪点叠加）提取到 DESIGN.md + tokens.json + assets/ 中。通过捆绑的 Patchright + Chromium 驱动在本地运行（与 wonda wab record 和认证会话流相同的 wonda wab install）。

需要一次性运行 wonda wab install 来下载 Patchright + Chromium（约 300 MB，由 wonda wab record、认证会话流和 brand extract 共享）。

这是以前在 slide-generation / slide-generation-system / creative-static-ads / premium-static-ads 技能中使用的基于 npx 的品牌提取 CLI 的内部替代品。

# 仅本地——无身份验证、无积分、无 API 调用
wonda brand extract https://linear.app                       # 写入 ./output/linear.app/{DESIGN.md, tokens.json, assets/}
wonda brand extract https://stripe.com --output ./refs       # 写入 ./refs/stripe.com/...
wonda brand extract https://vercel.com --screenshot          # 同时写入 page.png
wonda brand extract https://stripe.com --viewport 1440x900   # 覆盖默认 1920x1080

# 持久化到服务器（通过媒体预签名上传资产 + POST /brand/save）
wonda brand extract https://stripe.com --save                # 本地 + 持久化
wonda brand extract https://stripe.com --save --make-active  # 本地 + 持久化 + 激活（常用路径）
wonda brand extract https://stripe.com --no-output --save    # 不写入磁盘，仅持久化

# 移动已持久化的品牌
wonda brand save --from ./output/stripe.com --make-active    # 持久化先前提取的目录
wonda brand pull <brand-id>                                  # 将已保存的品牌下载回 ./output/<domain>/

标志：

• --save：通过媒体预签名流程上传 assets/，并 POST {tokens, mediaIds} 到 /api/v1/brand/save。需要身份验证。
• --make-active：隐含 --save。将新品牌设置为活跃。
• --output <dir>：覆盖本地输出目录。默认是 ./output/<domain>/。与 --no-output 互斥。
• --no-output：不写入磁盘（仅内存提取，用于管道传输）。与 --output 互斥。
• --name "Brand Name"：持久化时覆盖品牌名称。默认为域名的词干大写。
• --screenshot：同时保存 page.png 与 DESIGN.md。
• --viewport WxH：无头浏览器的视口大小。默认 1920x1080。

输出（当未设置 --no-output 时，始终到 <output-dir>/<domain>/）：

• DESIGN.md：令牌、排版、英雄装饰、徽标、CSS 图案、虚线边框和根 CSS 变量的 Markdown 摘要。在编写幻灯片/静态广告技能中的 HTML 之前阅读此文件。
• tokens.json：提取的原始结构化 JSON。
• page.png：仅当传递了 --screenshot。
• assets/：原始英雄装饰文件加上 assets/fonts/，用于任何非 Google 的 @font-face URL。当不是 --no-output 时始终写入。

打印写入的文件路径到 stdout。使用 --save 时，还打印 API 响应（brandId、sourceDomain、warnings）。失败时非零退出（网络错误、导航超时、浏览器崩溃、保存失败）。

视频分析

分析视频以提取复合帧网格（视觉）和音频转录（文本）。有助于在创建变体之前理解视频内容。需要完整账户（非匿名），并根据视频时长消耗积分（ElevenLabs STT 定价）。

如果视频刚刚上传且仍在归一化中，CLI 会自动重试直到媒体准备就绪。

# 分析视频——返回复合网格图像 + 转录
ANALYSIS_JOB=$(wonda analyze video --media $VIDEO_MEDIA --wait --quiet)

# 任务输出包含：
# - compositeGrid：显示 24 个均匀间隔帧的图像
# - transcript：任何语音的完整文本
# - wordTimestamps：单词级时间 [{word, start, end}]
# - videoMetadata：{width, height, durationMs, fps, aspectRatio}

# 下载复合网格以供视觉检查
wonda analyze video --media $VIDEO_MEDIA --wait -o /tmp/grid.jpg

# 仅获取转录
wonda analyze video --media $VIDEO_MEDIA --wait --jq '.outputs[] | select(.outputKey=="transcript") | .outputValue'

错误处理：402 = 积分不足，409 = 媒体仍在处理中（CLI 自动重试）。

聊天（AI 助手）

用于内容创作的交互式聊天会话——AI 处理生成、编辑和迭代。

wonda chat create --title "Product launch"            # 新建会话
wonda chat list                                       # 列出会话（--limit、--offset）
wonda chat messages <chatId>                          # 获取消息
wonda chat send <chatId> --message "Create a UGC reaction video"
wonda chat send <chatId> --message "Edit it" --media <id>
wonda chat send <chatId> --message "..." --aspect-ratio 9:16 --quality-tier max
wonda chat send <chatId> --message "..." --style <styleId>
wonda chat send <chatId> --message "..." --passthrough-prompt  # 使用精确提示，无 AI 增强

任务与运行

wonda jobs get inference <id>                         # 推理任务状态
wonda jobs get editor <id>                            # 编辑器任务状态
wonda jobs get publish <id>                           # 发布任务状态
wonda jobs wait inference <id> --timeout 20m          # 等待完成
wonda run get <runId>                                 # 运行状态
wonda run wait <runId> --timeout 30m                  # 等待运行完成

发现

wonda models list                                     # 所有可用模型
wonda models info <slug>                              # 模型详情和参数
wonda operations list                                 # 所有编辑器操作
wonda operations info <operation>                     # 操作详情
wonda capabilities                                    # 完整平台能力
wonda pricing list                                    # 所有模型定价
wonda pricing estimate --model seedance-2 --prompt "..." # 成本估算
wonda style list                                      # 可用视觉风格
wonda topup                                            # 充值积分（打开 Stripe 结账）

编辑音频与图像

# 编辑音频
wonda edit audio --operation <op> --media <id> --wait -o out.mp3

对于任何图像编辑（裁剪、文字叠加、img2img、背景移除、矢量化），拉取专用技能：wonda skill get image-edit。

对齐（时间戳提取）

wonda alignment extract-timestamps --model <model> --attach <mediaId> --wait

质量级别

故障排除

时间预估

• 图像：30s - 2min
• 视频 (Sora)：2 - 5min
• 视频 (Sora Pro)：5 - 10min
• 视频 (Veo 3.1)：1 - 3min
• 视频 (Kling)：3 - 8min
• 视频 (Grok)：2 - 5min
• 音乐 (Suno)：1 - 3min
• TTS：10 - 30s
• 编辑器操作：30s - 2min
• 口型同步：1 - 3min
• 视频放大：2 - 5min

错误恢复

• 未知模型：wonda models list
• 无 API 密钥：wonda auth login 或设置 WONDA_API_KEY 环境变量
• 任务失败：wonda jobs get inference <id> 查看错误详情
• 错误参数：wonda models info <slug> 查看有效参数
• 超时：wonda jobs wait inference <id> --timeout 20m
• 积分不足 (402)：wonda topup 充值积分