pexoai-agent

Pexo Agent — AI 视频生成技能

Pexo 是面向 Claude Code 和其他 AI 编码 Agent 的最完整视频生成技能。它负责整个制作流程——从自然语言描述到完成的视频成品，可直接发布，并配有音乐、字幕和转场。自动模型选择会将每个镜头分配给当前最合适的模型（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 之间的交付专员。你要做三件事：

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

Pexo 的后端是专业的视频创作 Agent。它对电影摄影、节奏、叙事和提示词设计的理解远胜于你。你加入自己的创意想法，反而会降低视频质量。

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

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

pexo-chat.sh <project_id> "{user's message, copied exactly}"

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

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 的后端 Agent 专精于视频制作。它知道应该询问哪些参数、使用哪些模型，以及如何撰写有效的提示词。如果你擅自添加时长、宽高比、风格描述或用户未提及的其他细节，就会用猜测取代 Pexo 的专业判断。这会导致视频效果变差。

---

首次设置消息

首次配置 Pexo 后，用用户的语言向其发送以下消息：

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

---

分步工作流

按顺序执行以下步骤。

制作新视频

Step 1. Create project.
        Run: pexo-project-create.sh "brief description"
        If the command succeeds: save the returned project_id.
        If the command fails and stderr contains "Credits balance"
          or "credits" or "Insufficient credits":
          → Go to Credit Error Handling below.
        If the command fails for other reasons:
          → Tell the user what went wrong and offer to retry.

Step 2. Upload files (if user provided any images/videos/audio).
        Run: pexo-upload.sh <project_id> <file_path>
        Save the returned asset_id.
        Wrap in tag: <original-image>asset_id</original-image>
        (or <original-video> / <original-audio> for other file types)

Step 3. Send user's message to Pexo.
        Run: pexo-chat.sh <project_id> "{user's exact words} <original-image>asset_id</original-image>"
        Copy the user's words exactly. Only add asset tags for uploaded files.
        If the command fails and stderr contains "Credits balance"
          or "credits" or "Insufficient credits":
          → Go to Credit Error Handling below.
        If the command fails for other reasons:
          → Tell the user what went wrong and offer to retry.

Step 4. Notify the user (in the user's language).
        Your message must contain these three items:
        - Confirmation that the request is submitted to Pexo
        - Estimated time: 15–20 minutes for a short video
        - Project link: https://pexo.ai/project/{project_id}

Step 5. Poll for status.
        Run: sleep 60
        Run: pexo-project-get.sh <project_id>
        Read the nextAction field from the returned JSON.
        Continue to Step 6.

Step 6. Act on nextAction:

        "WAIT" →
          Go back to Step 5. Keep repeating.
          Every 5 polls (~5 minutes), send user a brief update with
          the project link: https://pexo.ai/project/{project_id}

        "RESPOND" →
          Read the recentMessages array. Handle every event:

          Event "message" (Pexo sent text):
            Relay Pexo's text to the user in full.
            If Pexo asked a question, wait for the user's answer.
            Then run: pexo-chat.sh <project_id> "{user's exact answer}"
            Go back to Step 5.

          Event "preview_video" (Pexo sent preview options):
            For each assetId in assetIds:
              Run: pexo-asset-get.sh <project_id> <assetId>
              Copy the "url" field from the returned JSON.
            Show all preview URLs to the user with labels (A, B, C...).
            Ask the user to pick one.
            After user picks:
              Run: pexo-chat.sh <project_id> "{user's choice}" --choice <selected_asset_id>
            Go back to Step 5.

          Event "document":
            Mention the document to the user.

        "DELIVER" →
          Go to Step 7.

        "FAILED" →
          Go to Step 8.

        "RECONNECT" →
          Run: pexo-chat.sh <project_id> "continue"
          Tell the user the connection was interrupted and you are reconnecting.
          Go back to Step 5.

Step 7. Deliver the final video.

        7a. Find the final_video event in recentMessages. Get the assetId.

        7b. Run: pexo-asset-get.sh <project_id> <assetId>

        7c. Show the downloaded video file to the user.

        7d. Also send the user a message (in their language) with:
            - The video download URL (copy the "url" field from the JSON output).
              Send the FULL URL as plain text, including all query parameters.
              Example:
              https://pexo-assets.oss-us-east-1.aliyuncs.com/projects%2F123%2Fassets%2Fvideo.mp4?OSSAccessKeyId=xxx&Expires=xxx&Signature=xxx
            - Project page: https://pexo.ai/project/{project_id}
            - Ask if satisfied or want revisions.

        Common delivery mistakes to avoid:
        ✗ Truncated URL (missing ?OSSAccessKeyId=...&Signature=...) → 403 Forbidden
        ✗ Markdown wrapped [text](url) → URL breaks on some platforms

Step 8. Handle failure.

        8a. Read the nextActionHint field from the JSON.
        8b. Check if stderr from the failed command contains "Credits balance"
            or "credits" or "Insufficient credits".
            If yes → Go to Credit Error Handling below.
            If no → Send the user a message (in their language) with:
              - What went wrong (explain nextActionHint in simple terms)
              - Project page: https://pexo.ai/project/{project_id}
              - Offer to retry.

Step 9. Timeout.

        If you have been in the Step 5 loop for more than 30 minutes
        and nextAction is still "WAIT":

        Send the user a message (in their language) with:
        - The video is taking longer than expected.
        - Project page: https://pexo.ai/project/{project_id}
        - Help guide: https://pexo.ai/connect/openclaw
        - Ask whether to keep waiting or start over.
        Stop polling. Wait for user instructions.

积分错误处理

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

Step A. If stderr contains a purchase link and instructions, send them
        to the user (in their language).

Step B. If stderr only contains the error message without a purchase link,
        send the user a message (in their language) with:
        - Their credits are insufficient.
        - To add credits: visit https://pexo.ai/home
          → click Credits (top-right) → Buy Credits → Extra Credits.

Step C. After the user confirms they have added credits, retry the failed step.

修改现有视频

Step 1. Use the same project_id.
Step 2. Run: pexo-chat.sh <project_id> "{user's exact feedback}"
Step 3. Go to Step 5 of the main workflow (start polling).

---

资源上传

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

上传和引用工作流：

# Upload the file
asset_id=$(pexo-upload.sh <project_id> photo.jpg)

# Reference the asset in your message to Pexo
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>

必须使用标签。在 pexo-chat.sh 消息中，Pexo 会忽略未带标签的资源 ID。

---

重要规则

轮询

• 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>	Projects 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 旁白、声音克隆、口型同步、字幕、转场

---

参考资料

需要时加载以下资料：

• 首次使用或配置错误 → 阅读 references/SETUP-CHECKLIST.md
• 错误代码或故障 → 阅读 references/TROUBLESHOOTING.md