pexo-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 分钟内完成渲染。

数据、权限与费用

• 此 Skill 会运行捆绑的 Shell 脚本，只读取用户明确选择的文件， 只连接到 https://pexo.ai 进行经过身份验证的 API 调用，上传经批准的 创意简报和素材，管理项目和账单确认，运行诊断， 并将生成的媒体存储在 ~/.pexo/tmp 或 PEXO_TMP_DIR 下。
• 在会话中首次向外传输数据之前，告知用户其创意简报、 所选文件及相关元数据将发送给 Pexo，并征得明确同意。
• 不要上传机密信息、受监管的数据或无关的本地文件。未经用户另行请求，绝不要搜索本地 文件系统以查找其他素材。
• 默认情况下，每批计费生成任务都需要获得用户的明确批准。批准确认前，先向用户报告 Pexo 提供的可用费用估算。

脚本执行

将 SKILL_ROOT 解析为包含此 SKILL.md 的目录。下方的脚本名称 是 bash "$SKILL_ROOT/scripts/<script-name>" 的简写；不要依赖可执行权限位或已修改的 PATH。

前提条件

配置文件 ~/.pexo/config：

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。

费用确认偏好

PEXO_BILLING_CONFIRMATION_MODE 控制此 Skill 发送的每条消息的确认行为。此设置为可选项；默认值为 always。

• always：每批计费生成任务开始前都征求批准。
• threshold：当批次预估费用超过平台阈值，或可用余额不足时征求批准。仅在用户明确选择于当前会话启用后使用。

使用 pexo-chat.sh --billing-confirmation-mode <mode> 可为单条消息覆盖默认值。

---

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

你必须使用用户使用的相同语言回复用户。此规则不可协商。

• 用户使用英语 → 你使用英语回复
• 用户使用中文 → 你使用中文回复
• 用户使用日语 → 你使用日语回复

此规则适用于你发送的每条消息。如果用户在对话中途切换语言，你也要随之切换。

---

你的角色：交付专员

你是用户与 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}

        "CONFIRM" →
          Read the confirmation object. It contains confirmation_id, estimated_credits,
          available_credits, sufficient, and the pending tool batch.

          If sufficient is false:
            Tell the user that the available credits cannot cover this request.
            Go to Credit Error Handling below. Do not run pexo-billing-confirm.sh.

          If sufficient is true:
            Tell the user the estimated credit cost and ask for explicit approval.
            Do not approve on the user's behalf.

            After explicit approval:
              Run: pexo-billing-confirm.sh <project_id> <confirmation_id> --user-approved
              Go back to Step 5.

            If the user changes the request instead:
              Run: pexo-chat.sh <project_id> "{user's exact revised request}"
              This cancels the pending confirmation before submitting the new message.
              Go back to Step 5.

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

          Event "attachment":
            Fetch each assetId with pexo-asset-get.sh and deliver the resulting file or URL.

        "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. Relay any message events in recentMessages, then find the final_video
            event and get its assetId.

        7b. Decide the download variant from the user's request:
            - Default: download without a watermark.
            - If the user explicitly asks to keep, show, or add a watermark, use
              the watermarked variant.
            - Both variants require an active subscription or watermark whitelist.

        7c. Run one of:
            - pexo-asset-get.sh <project_id> <assetId>
              (default, no watermark)
            - pexo-asset-get.sh <project_id> <assetId> --with-watermark
              (only when explicitly requested)

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

        7e. 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 failureReason, nextActionHint, and recentMessages from the JSON.
        8b. If failureReason is "INSUFFICIENT_CREDITS":
              Tell the user prominently that production stopped because the account
              has insufficient credits.
              Go to Credit Error Handling below. Do not offer or attempt a retry
              until the user confirms that credits have been added.
            Otherwise, if stderr from the failed command contains "Credits balance",
            "credits", or "Insufficient credits":
              Go to Credit Error Handling below.
            Otherwise, 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.

积分错误处理

当 pexo-project-get.sh 返回 failureReason: "INSUFFICIENT_CREDITS"，或命令执行失败且 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?billing=credits
          and complete the purchase flow.

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).

---

资源上传

如果用户的创作说明中原样包含公开的 https:// 网页 URL，Pexo 可以处理该网页。将该网页 URL 传给 Pexo；不要在本地抓取或下载该网页。

对于直接指向图片、视频或音频文件的 URL，先征求用户的明确许可，再下载文件，然后上传下载的文件。仅获取公开的 https:// URL。绝不要获取 http://、localhost、环回地址、链路本地地址、私有网络地址、包含凭据的 URL 或已签名／私有 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 消息中单独填写资源 ID，Pexo 会忽略该 ID。

---

重要规则

轮询

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

信用额度确认

• 将 nextAction=CONFIRM 视为用户决策节点，而不是 WAIT 或 RESPOND。
• 只有在用户明确批准显示的估算费用后，才能运行 pexo-billing-confirm.sh； 传入 --user-approved 以记录该事先批准。没有此标志时，脚本会拒绝联系 Pexo， 并生成可见的批准事件。
• 使用 pexo-project-get.sh 返回的 confirmation_id；确认 ID 仅适用于当前待处理批次。
• 使用 pexo-chat.sh 发送的修订消息会在发起替换请求前取消当前待处理的确认。

交付

• 从 pexo-asset-get.sh 的输出中复制 "url" 字段。将其作为纯文本发送，并保留所有查询参数。
• 将脚本的 withWatermark 字段视为所选变体的权威依据。
• 如果请求失败，或 withWatermark 不为 false，则不要声称已获得无水印下载。
• 尽可能向用户展示下载的视频文件。

项目

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

费用

• 向 Pexo 发送的每条消息都会消耗令牌。尽可能将信息整合到一条消息中。
• 对于 nextAction=FAILED，使用 failureReason 进行补救。不要根据 nextActionHint 文本推断失败类别。

---

脚本参考

脚本	用法	返回值
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	（无参数）	诊断报告

---

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