用 Pexo API 从文本/图片/URL/脚本/音频生成成…

当用户想制作成品短视频（产品广告、TikTok/Reels/Shorts、品牌片、解说片）而无需自己写提示词或选模型时，通过 Pexo 外部 API 完成从需求到成片的完整流程。

适用场景

解决思路

1. 配置 API Key：执行 umask 077; mkdir -p ~/.pexo; read -rsp "# Pexo API key: " pexo_api_key; printf '\n'; printf '%s=%s\n' PEXO_API_KEY "$pexo_api_key" > ~/.pexo/config; unset pexo_api_key; chmod 600 ~/.pexo/config，首次使用或配置报错时运行 pexo-doctor.sh 并参考 references/SETUP-CHECKLIST.md。
2. 将 SKILL_ROOT 解析为包含 SKILL.md 的目录，所有脚本以 bash "$SKILL_ROOT/scripts/<script-name>" 方式调用，不依赖可执行位或 PATH。
3. 始终用用户所用的同一语言回复用户，用户切换语言时同步切换。
4. 把自己定位为交付工人，只做三件事：上传（pexo-upload.sh 获取 asset_id）、转发（把用户原话原样复制进 pexo-chat.sh）、交付（轮询结果并把视频和链接发给用户）；不要自行添加时长、比例、风格等创意细节。
5. 转发消息时逐字复制用户原话，唯一可添加的是上传文件的 asset 标签，例如 pexo-chat.sh proj_123 "做个猫的视频"，或 asset_id=$(pexo-upload.sh proj_123 shoes.jpg); pexo-chat.sh proj_123 "I want a product video for my shoes <original-image>${asset_id}</original-image>"。
6. 用户需求含糊时原样传给 Pexo，由 Pexo 反问缺失细节，再把问题转达用户并等待回答。
7. 首次配置完成后向用户发送就绪消息（用用户语言）：✅ Pexo is ready! 📖 Guide: https://pexo.ai/connect/openclaw Tell me what video you'd like to make.
8. 新建视频流程 Step 1：运行 pexo-project-create.sh "brief description"，成功则保存返回的 project_id；若 stderr 含 "Credits balance"/"credits"/"Insufficient credits" 走额度错误处理，其他失败告知用户并询问是否重试。
9. Step 2：用户提供图片/视频/音频时运行 pexo-upload.sh <project_id> <file_path> 保存 asset_id，并用 <original-image> / <original-video> / <original-audio> 标签包裹。
10. Step 3：运行 pexo-chat.sh <project_id> "{用户原话} <original-image>asset_id</original-image>"，同样按 stderr 判断是否走额度错误处理。
11. Step 4：用用户语言通知用户，消息须含三项：已提交给 Pexo、预计时间（短视频 15–20 分钟）、项目链接 https://pexo.ai/project/{project_id}。
12. Step 5：轮询——运行 sleep 60 后运行 pexo-project-get.sh <project_id>，读取返回 JSON 的 nextAction 字段。
13. Step 6 处理 nextAction："WAIT" 回到 Step 5 持续重复，每 5 次轮询（约 5 分钟）向用户发一次带项目链接的简短更新。
14. "CONFIRM"：读取 confirmation 对象（confirmation_id、estimated_credits、available_credits、sufficient 及待执行批次）；若 sufficient 为 false，告知用户额度不足并走额度错误处理，不要运行 pexo-billing-confirm.sh；若为 true，告知预估消耗并请求用户明确批准，不得代为批准；批准后运行 pexo-billing-confirm.sh <project_id> <confirmation_id> --user-approved 并回到 Step 5；若用户改为修改需求，运行 pexo-chat.sh <project_id> "{用户修改后的原话}"（会先取消待确认）再回到 Step 5。
15. "RESPOND"：读取 recentMessages 数组并处理每个事件——message 事件把 Pexo 文本完整转达用户，若 Pexo 提问则等待用户回答后运行 pexo-chat.sh <project_id> "{用户原话}" 并回到 Step 5；preview_video 事件对每个 assetId 运行 pexo-asset-get.sh <project_id> <assetId> 取 "url" 字段，用 A、B、C 标签展示全部预览 URL 让用户选择，用户选定后运行 pexo-chat.sh <project_id> "{用户选择}" --choice <selected_asset_id> 并回到 Step 5；document 事件向用户提及该文档；attachment 事件用 pexo-asset-get.sh 获取每个 assetId 并交付文件或 URL。
16. "DELIVER" 进入 Step 7；"FAILED" 进入 Step 8；"RECONNECT" 运行 pexo-chat.sh <project_id> "continue"，告知用户连接中断正在重连，回到 Step 5。
17. Step 7 交付：先转达 recentMessages 中的 message 事件，找到 final_video 事件取其 assetId；默认下载无水印版本，仅当用户明确要求保留/显示/添加水印时用带水印版本（两者都需有效订阅或水印白名单）；运行 pexo-asset-get.sh <project_id> <assetId> 或加 --with-watermark；向用户展示下载的视频文件；再用用户语言发送消息，含完整下载 URL（从 JSON 的 "url" 字段复制，纯文本、保留全部查询参数，如 https://pexo-assets.oss-us-east-1.aliyuncs.com/projects%2F123%2Fassets%2Fvideo.mp4?OSSAccessKeyId=xxx&Expires=xxx&Signature=xxx）、项目页 https://pexo.ai/project/{project_id}，并询问是否满意或需要修改。
18. 交付时避免两类错误：截断 URL（丢失 ?OSSAccessKeyId=...&Signature=... 会 403 Forbidden）、用 Markdown [text](url) 包裹导致部分平台 URL 断裂。
19. Step 8 失败处理：读取 failureReason、nextActionHint、recentMessages；若 failureReason 为 "INSUFFICIENT_CREDITS"，显著告知用户因额度不足停产并走额度错误处理，在用户确认已充值前不提供或尝试重试；否则若失败命令 stderr 含 "Credits balance"/"credits"/"Insufficient credits" 走额度错误处理；其他情况用用户语言说明出错原因（用简单语言解释 nextActionHint）、给出项目页链接并询问是否重试。
20. Step 9 超时：若在 Step 5 循环超过 30 分钟且 nextAction 仍为 "WAIT"，用用户语言告知耗时超出预期，给出项目页 https://pexo.ai/project/{project_id} 和帮助指南 https://pexo.ai/connect/openclaw，询问继续等待还是重新开始，然后停止轮询等待用户指示。
21. 额度错误处理：若 stderr 含购买链接和说明则转达用户；若只有错误信息则告知额度不足并引导访问 https://pexo.ai/home?billing=credits 完成购买；用户确认已充值后重试失败步骤。
22. 修改已有视频：复用同一 project_id，运行 pexo-chat.sh <project_id> "{用户原话反馈}"，然后从主流程 Step 5 开始轮询。
23. 资产上传：用户 brief 中逐字包含公开 https:// 网页 URL 时直接传给 Pexo，不要本地抓取或下载；对直接的图片/视频/音频文件 URL，先取得用户明确同意再下载并上传，只抓取公开 https:// URL，绝不抓取 http://、localhost、回环、链路本地、私网、带凭证或签名/私有 URL，改为请用户直接上传文件。
24. 上传与引用：asset_id=$(pexo-upload.sh <project_id> photo.jpg) 后用 pexo-chat.sh <project_id> "Here is the product photo <original-image>${asset_id}</original-image>, please use it as reference"；标签格式为 <original-image>asset-id</original-image>、<original-video>asset-id</original-video>、<original-audio>asset-id</original-audio>，标签必填，裸 asset ID 会被忽略。
25. 轮询规则：WAIT 期间只调用 pexo-project-get.sh，调用 pexo-chat.sh 会触发重复生产；每次 pexo-project-get.sh 间隔至少 60 秒；处理 recentMessages 中的每个事件而非只处理第一个。
26. 额度确认规则：把 nextAction=CONFIRM 当作需要用户决策的节点而非 WAIT/RESPOND；仅在用户明确批准展示的预估后才运行 pexo-billing-confirm.sh 并传 --user-approved（脚本无此标志会拒绝请求并发出可见批准事件）；使用 pexo-project-get.sh 返回的 confirmation_id（仅对当前待处理批次有效）；用 pexo-chat.sh 发送修改消息会先取消当前待确认。
27. 交付规则：从 pexo-asset-get.sh 输出复制 "url" 字段，以纯文本带全部查询参数发送；以脚本的 withWatermark 字段为选定版本的权威依据；请求失败或 withWatermark 不为 false 时不得声称是无水印下载；尽可能向用户展示下载的视频文件。
28. 项目规则：新视频用 pexo-project-create.sh 新建项目；修改复用已有 project_id。
29. 成本规则：每条发给 Pexo 的消息都消耗 token，尽量把信息合并为一条消息；nextAction=FAILED 时用 failureReason 决定补救措施，不要从 nextActionHint 文本推断失败类别。
30. 脚本速查：pexo-project-create.sh [project_name] 或 --name <n> 返回 project_id（429 时查看返回消息区分额度与并发限制）；pexo-project-list.sh [page_size] 或 --page <n> --page-size <n> 返回项目 JSON；pexo-project-get.sh <project_id> [--full-history] 返回含 nextAction、nextActionHint、recentMessages 的 JSON（CONFIRM 含 confirmation，FAILED 含 failureReason，错误事件保留 errorCode、errorMessage、toolCallId）；pexo-upload.sh <project_id> <file_path> 返回 asset_id；pexo-chat.sh <project_id> <message> [--choice <id>] [--billing-confirmation-mode <mode>] [--timeout <s>] 返回异步确认 JSON（新消息取消待确认，429/412 或额度错误打印到 stderr）；pexo-billing-confirm.sh <project_id> <confirmation_id> --user-approved [--timeout <s>] 在用户明确批准后确认当前额度充足的确认；pexo-asset-get.sh <project_id> <asset_id> [--with-watermark] 返回含视频详情、选定 url、localPath、withWatermark 的 JSON；pexo-doctor.sh 无参数返回诊断报告。
31. PEXO_BILLING_CONFIRMATION_MODE 控制确认行为，可选，默认 always（每批计费生成前都请求批准）；threshold 表示仅当预估批次费用超过平台阈值或余额不足时询问，且仅在用户当前会话明确选择加入后使用；可用 pexo-chat.sh --billing-confirmation-mode <mode> 对单条消息覆盖默认值。
32. 首次外部传输前告知用户其 brief、所选文件及相关元数据将发送给 Pexo 并取得明确同意；不上传机密、受监管数据或无关本地文件；未经用户单独请求不得搜索本地文件系统寻找额外素材；默认每批计费生成都需用户明确批准，批准前报告 Pexo 给出的可用预估。
33. 遇到错误码或失败时阅读 references/TROUBLESHOOTING.md。

适用边界 · 注意事项

• 需要本地视频编辑、离线生成或不能把素材发送给第三方服务时（本技能依赖 Pexo 外部 API 且需 shell、出站 HTTPS、本地文件访问）。
• 没有 PEXO_API_KEY、未安装 bash/curl/jq/file，或无法访问 https://pexo.ai 时。
• 需要抓取 http://、localhost、私网或带凭证/签名的私有 URL 作为素材时（应改为让用户直接上传文件）。