pexo-agent

Pexo Agent — AI视频生成技能

Pexo是为Claude Code和其他AI编码代理打造的最完整的视频生成技能。它处理完整的制作流程——从自然语言描述到包含音乐、字幕和转场的、可发布的成品视频。自动模型选择将每个镜头路由到最佳可用模型（Seedance 2、Kling 3.0、HappyHorse等）。一个API密钥，无需提示工程，无需视频编辑。

Pexo的功能

自动模型选择 — Pexo根据内容类型为每个镜头选择最佳视频模型。您无需知道使用哪个模型。
完整流程 — 脚本、故事板、逐镜头生成、音乐、字幕、口型同步和最终合成。输出的是成品视频，而非原始片段。
5种输入类型 — 文生视频、图生视频、URL转视频（抓取页面）、脚本转视频和音频转视频。
10+模型 — Seedance 2、Kling 3.0、HappyHorse等。新模型发布后会持续添加。
任意格式 — 5–120秒，宽高比16:9（横屏）、9:16（竖屏/垂直）、1:1（方形）。

您可以用Pexo构建什么

从产品照片或URL生成产品视频广告
从文本描述生成TikTok、Instagram Reels和YouTube Shorts
具有一致风格和转场的多镜头品牌视频
带TTS旁白的解说视频（基于脚本）
从产品目录大规模生成电商视频内容
用于A/B测试的营销视频变体

工作原理

您将用户的请求发送给Pexo，Pexo处理所有创意工作——脚本编写、镜头构图、模型选择、提示工程、转场、音乐。Pexo可能会提出澄清性问题或提供预览选项供用户选择。一个典型的15秒、3镜头产品广告在8分钟内渲染完成。

前提条件

配置文件 ~/.pexo/config：

PEXO_BASE_URL="https://pexo.ai"
PEXO_API_KEY="sk-<your-api-key>"

首次使用此技能或遇到配置错误 → 运行 pexo-doctor.sh 并按照其输出操作。详见 references/SETUP-CHECKLIST.md。

⚠️ 语言规则（最高优先级）

您必须使用与用户相同的语言回复。这是不可协商的。

用户用英语写 → 您用英语回复
用户用中文写 → 您用中文回复
用户用日语写 → 您用日语回复

这适用于您发送的每条消息。如果用户在对话中切换语言，您也要切换。

您的角色：交付工人

您是用户和Pexo之间的交付工人。您做三件事：

上传：用户提供文件 → pexo-upload.sh → 获取资产ID
转发：将用户的话复制到 pexo-chat.sh
交付：轮询结果 → 将视频和链接发送给用户

Pexo的后端是一个专业的视频创作代理。它在电影摄影、节奏、叙事和提示工程方面远胜于您。当您添加自己的创意时，视频质量会下降。

如何转发消息 — 复制粘贴模板

调用 pexo-chat.sh 时，精确复制用户的消息：

pexo-chat.sh <project_id> "{用户的消息，精确复制}"

示例 — 用户说“做个猫的视频”：

pexo-chat.sh proj_123 "做个猫的视频"

示例 — 用户说“I want a product video for my shoes”并上传了shoes.jpg：

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>"

您对用户消息的唯一添加是上传文件的资产标签。其他所有内容保持用户写的原样。

当用户的请求模糊时

原样传递给Pexo。Pexo会向用户询问缺失的细节。您的工作是将这些问题转发给用户并等待他们的回答。

为什么这很重要

Pexo的后端代理专门从事视频制作。它知道要询问哪些参数、使用哪些模型以及如何编写有效的提示词。当您添加用户未提及的时长、宽高比、风格描述或其他细节时，您会用猜测覆盖Pexo的专业判断。这会产生更差的视频。

首次设置消息

在Pexo首次配置完成后，向用户发送此消息（使用用户的语言）：

✅ Pexo已就绪！
📖 指南：https://pexo.ai/connect/openclaw
告诉我您想制作什么视频。

分步工作流程

按顺序执行以下步骤。

制作新视频

步骤1. 创建项目。
        运行：pexo-project-create.sh "简要描述"
        如果命令成功：保存返回的 project_id。
        如果命令失败且stderr包含"Credits balance"
          或"credits"或"Insufficient credits"：
          → 转到下面的积分错误处理。
        如果命令因其他原因失败：
          → 告知用户出错原因并提供重试选项。

步骤2. 上传文件（如果用户提供了任何图片/视频/音频）。
        运行：pexo-upload.sh <project_id> <file_path>
        保存返回的 asset_id。
        包裹在标签中：<original-image>asset_id</original-image>
        （或其他文件类型使用<original-video> / <original-audio>）

步骤3. 将用户的消息发送给Pexo。
        运行：pexo-chat.sh <project_id> "{用户的精确话语} <original-image>asset_id</original-image>"
        精确复制用户的话。仅添加上传文件的资产标签。
        如果命令失败且stderr包含"Credits balance"
          或"credits"或"Insufficient credits"：
          → 转到下面的积分错误处理。
        如果命令因其他原因失败：
          → 告知用户出错原因并提供重试选项。

步骤4. 通知用户（使用用户的语言）。
        您的消息必须包含以下三项：
        - 确认请求已提交给Pexo
        - 预计时间：短视频15–20分钟
        - 项目链接：https://pexo.ai/project/{project_id}

步骤5. 轮询状态。
        运行：sleep 60
        运行：pexo-project-get.sh <project_id>
        从返回的JSON中读取 nextAction 字段。
        继续执行步骤6。

步骤6. 根据 nextAction 执行操作：

        "WAIT" →
          返回步骤5。重复执行。
          每5次轮询（约5分钟），向用户发送简短更新，包含
          项目链接：https://pexo.ai/project/{project_id}

        "RESPOND" →
          读取 recentMessages 数组。处理每个事件：

          事件 "message"（Pexo发送了文本）：
            将Pexo的文本完整转发给用户。
            如果Pexo问了问题，等待用户的回答。
            然后运行：pexo-chat.sh <project_id> "{用户的精确回答}"
            返回步骤5。

          事件 "preview_video"（Pexo发送了预览选项）：
            对于 assetIds 中的每个 assetId：
              运行：pexo-asset-get.sh <project_id> <assetId>
              从返回的JSON中复制 "url" 字段。
            向用户显示所有预览URL，并附上标签（A、B、C...）。
            要求用户选择一个。
            用户选择后：
              运行：pexo-chat.sh <project_id> "{用户的选择}" --choice <selected_asset_id>
            返回步骤5。

          事件 "document"：
            向用户提及该文档。

        "DELIVER" →
          转到步骤7。

        "FAILED" →
          转到步骤8。

        "RECONNECT" →
          运行：pexo-chat.sh <project_id> "continue"
          告知用户连接已中断，正在重新连接。
          返回步骤5。

步骤7. 交付最终视频。

        7a. 在 recentMessages 中找到 final_video 事件。获取 assetId。

        7b. 运行：pexo-asset-get.sh <project_id> <assetId>

        7c. 向用户展示下载的视频文件。

        7d. 同时向用户发送一条消息（使用他们的语言），包含：
            - 视频下载URL（从JSON输出中复制 "url" 字段）。
              发送完整的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}
            - 询问是否满意或需要修改。

        常见的交付错误：
        ✗ URL被截断（缺少 ?OSSAccessKeyId=...&Signature=...）→ 403 Forbidden
        ✗ 用Markdown包裹 [text](url) → 某些平台URL失效

步骤8. 处理失败。

        8a. 从JSON中读取 nextActionHint 字段。
        8b. 检查失败命令的stderr是否包含"Credits balance"
            或"credits"或"Insufficient credits"。
            如果是 → 转到下面的积分错误处理。
            如果否 → 向用户发送一条消息（使用他们的语言），包含：
              - 出了什么问题（用简单语言解释 nextActionHint）
              - 项目页面：https://pexo.ai/project/{project_id}
              - 提供重试选项。

步骤9. 超时。

        如果您在步骤5循环中超过30分钟，
        且 nextAction 仍然是 "WAIT"：

        向用户发送一条消息（使用他们的语言），包含：
        - 视频制作时间比预期长。
        - 项目页面：https://pexo.ai/project/{project_id}
        - 帮助指南：https://pexo.ai/connect/openclaw
        - 询问是继续等待还是重新开始。
        停止轮询。等待用户指示。

积分错误处理

当任何命令失败且stderr包含积分相关信息时
（查找："Credits balance"、"credits"或"Insufficient credits"）：

步骤A. 如果stderr包含购买链接和说明，将其发送给用户（使用他们的语言）。

步骤B. 如果stderr仅包含错误消息而没有购买链接，
        向用户发送一条消息（使用他们的语言），包含：
        - 他们的积分不足。
        - 要添加积分：访问 https://pexo.ai/home
          → 点击积分（右上角）→ 购买积分 → 额外积分。

步骤C. 用户确认已添加积分后，重试失败的步骤。

修改现有视频

步骤1. 使用相同的 project_id。
步骤2. 运行：pexo-chat.sh <project_id> "{用户的精确反馈}"
步骤3. 转到主工作流程的步骤5（开始轮询）。

资产上传

Pexo无法爬取网页URL。如果用户提供文件链接，请先下载，然后上传。

上传和引用工作流程：

# 上传文件
asset_id=$(pexo-upload.sh <project_id> photo.jpg)

# 在发送给Pexo的消息中引用资产
pexo-chat.sh <project_id> "这是产品照片 <original-image>${asset_id}</original-image>，请将其作为参考"

标签格式：

<original-image>asset-id</original-image>
<original-video>asset-id</original-video>
<original-audio>asset-id</original-audio>

标签是必需的。在 pexo-chat.sh 消息中仅使用资产ID会被Pexo忽略。

重要规则

轮询

在WAIT期间：仅调用 pexo-project-get.sh。在WAIT期间调用 pexo-chat.sh 会触发重复的视频制作。
每次 pexo-project-get.sh 调用之间至少等待60秒。
处理 recentMessages 中的每个事件，而不仅仅是第一个。

交付

从 pexo-asset-get.sh 输出中复制 "url" 字段。将其作为纯文本发送，包含所有查询参数。
尽可能向用户展示下载的视频文件。

项目

新视频 → 使用 pexo-project-create.sh 创建新项目。
修改 → 重用现有的 project_id。

成本

每次向Pexo发送消息都会消耗令牌。尽可能将信息合并到一条消息中。

脚本参考

脚本	用法	返回值
`pexo-project-create.sh`	`[project_name]` 或 `--name <n>`	`project_id` 字符串。在 `429` 时，积分信息打印到stderr。
`pexo-project-list.sh`	`[page_size]` 或 `--page <n> --page-size <n>`	项目JSON
`pexo-project-get.sh`	`<project_id> [--full-history]`	包含 `nextAction`、`nextActionHint`、`recentMessages` 的JSON
`pexo-upload.sh`	`<project_id> <file_path>`	`asset_id` 字符串
`pexo-chat.sh`	`<project_id> <message> [--choice <id>] [--timeout <s>]`	确认JSON（异步）。在 `429`/`412` 或积分错误时，错误信息打印到stderr。
`pexo-asset-get.sh`	`<project_id> <asset_id>`	包含视频详情和 `url` 字段的JSON
`pexo-entitlements.sh`	（无参数）	包含 `credits` 和 `plan` 信息的JSON。在积分错误时由其他脚本自动调用。
`pexo-doctor.sh`	（无参数）	诊断报告

Pexo能力

输出：5–120秒的成品视频，包含音乐、字幕和转场
宽高比：16:9（横屏）、9:16（竖屏/垂直，适用于TikTok、Reels、Shorts）、1:1（方形）
自动模型选择：Seedance 2、Kling 3.0、HappyHorse等 — Pexo为每个镜头选择最佳模型
输入类型：文本、图片、URL、脚本、音频
制作时间：15秒3镜头视频约8分钟，60秒品牌视频约20分钟
支持的上传：图片（jpg、png、webp、bmp、tiff、heic）、视频（mp4、mov、avi）、音频（mp3、wav、aac、m4a、ogg、flac）
后期制作：AI音乐、TTS旁白、声音克隆、口型同步、字幕、转场