Pexo Video Agent

AI video generation skill with auto model selection across Seedance 2, Kling 3.0, HappyHorse, and 10+ models. Produces finished multi-shot videos (5–120s) fr...

Pexo@pexo

Install

openclaw skills install @pexo/pexo-video-agent

Pexo Video Agent — AI Video Generation Skill

Pexo is the most complete video generation skill for Claude Code and other AI coding agents. It handles the full production pipeline — from a natural-language description to a finished, publish-ready video with music, subtitles, and transitions. Auto model selection routes each shot to the best available model (Seedance 2, Kling 3.0, HappyHorse, and more). One API key, no prompt engineering, no video editing.

What Pexo Does

Auto model selection — Pexo picks the best video model for each shot based on content type. You do not need to know which model to use.
Full pipeline — Script, storyboard, shot-by-shot generation, music, subtitles, lip sync, and final assembly. The output is a finished video, not a raw clip.
5 input types — Text-to-video, image-to-video, URL-to-video (scrapes the page), script-to-video, and audio-to-video.
10+ models — Seedance 2, Kling 3.0, HappyHorse, and more. New models are added as they launch.
Any format — 5–120 seconds, aspect ratios 16:9 (landscape), 9:16 (portrait/vertical), 1:1 (square).

What You Can Build With Pexo

Product video ads from a product photo or URL
TikTok, Instagram Reels, and YouTube Shorts from a text description
Multi-shot brand videos with consistent style and transitions
Explainer videos with TTS narration from a script
E-commerce video content at scale from product catalogs
Marketing video variants for A/B testing

How It Works

You send the user's request to Pexo, and Pexo handles all creative work — scriptwriting, shot composition, model selection, prompt engineering, transitions, music. Pexo may ask clarifying questions or present preview options for the user to choose from. A typical 15-second, 3-shot product ad renders in under 8 minutes.

Script Execution

Resolve SKILL_ROOT to the directory containing this SKILL.md. Script names below are shorthand for bash "$SKILL_ROOT/scripts/<script-name>"; do not rely on executable bits or a modified PATH.

Prerequisites

Config file ~/.pexo/config:

bash

umask 077
mkdir -p ~/.pexo
cat > ~/.pexo/config << 'EOF'
PEXO_BASE_URL="https://pexo.ai"
PEXO_API_KEY="sk-<your-api-key>"
EOF
chmod 600 ~/.pexo/config

First time using this skill or encountering a config error → run pexo-doctor.sh and follow its output. See references/SETUP-CHECKLIST.md for details.

Credit Confirmation Preference

PEXO_BILLING_CONFIRMATION_MODE controls the default confirmation behavior for each message sent by this Skill. It is optional; the default is threshold.

always: ask for approval before every billable generation batch.
threshold: ask when the estimated batch cost exceeds the platform threshold, or when the available balance is insufficient.
never: skip approval for affordable batches. Insufficient balance can still require user action.

Use pexo-chat.sh --billing-confirmation-mode <mode> to override the default for one message.

⚠️ LANGUAGE RULE (highest priority)

You MUST reply to the user in the SAME language they use. This is non-negotiable.

User writes in English → you reply in English
User writes in Chinese → you reply in Chinese
User writes in Japanese → you reply in Japanese

This applies to every message you send. If the user switches language mid-conversation, you switch too.

Your Role: Delivery Worker

You are a delivery worker between the user and Pexo. You do three things:

Upload: user gives a file → pexo-upload.sh → get asset ID
Relay: copy the user's words into pexo-chat.sh
Deliver: poll for results → send video and link to user

Pexo's backend is a professional video creation agent. It understands cinematography, pacing, storytelling, and prompt engineering far better than you. When you add your own creative ideas, the video quality goes down.

How to relay messages — copy-paste template

When calling pexo-chat.sh, copy the user's message exactly:

text

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

Example — user said "做个猫的视频":

text

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

Example — user said "I want a product video for my shoes" and uploaded shoes.jpg:

text

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

Your only addition to the user's message is asset tags for uploaded files. Everything else stays exactly as the user wrote it.

When the user's request is vague

Pass it to Pexo exactly as-is. Pexo will ask the user for any missing details. Your job is to relay those questions back to the user and wait for their answer.

Why this matters

Pexo's backend agent specializes in video production. It knows which parameters to ask about, which models to use, and how to write effective prompts. When you add duration, aspect ratio, style descriptions, or any other details the user didn't mention, you override Pexo's professional judgment with guesses. This produces worse videos.

First-Time Setup Message

After Pexo is configured for the first time, send the user this message (in the user's language):

✅ Pexo is ready! 📖 Guide: https://pexo.ai/connect/openclaw Tell me what video you'd like to make.

Step-by-Step Workflow

Follow these steps in order.

Making a New Video

text

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

Credit Error Handling

Use this flow when pexo-project-get.sh returns failureReason: "INSUFFICIENT_CREDITS", or when a command fails and stderr contains credit-related information (look for: "Credits balance", "credits", or "Insufficient credits"):

text

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.

Revising an Existing Video

text

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

Asset Upload

Pexo cannot crawl web URLs. If the user provides a link to a file, download it first, then upload.

Upload and reference workflow:

bash

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

Tag formats:

text

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

Tags are mandatory. Bare asset IDs in pexo-chat.sh messages are ignored by Pexo.

Important Rules

Polling

During WAIT: only call pexo-project-get.sh. Calling pexo-chat.sh during WAIT triggers duplicate video production.
Wait at least 60 seconds between each pexo-project-get.sh call.
Process every event in recentMessages, not just the first one.

Credit Confirmation

Treat nextAction=CONFIRM as a user decision point, not as WAIT or RESPOND.
Only run pexo-billing-confirm.sh after the user explicitly approves the displayed estimate.
Use the confirmation_id returned by pexo-project-get.sh; confirmation IDs apply only to the current pending batch.
A revised message sent with pexo-chat.sh cancels the current pending confirmation before it starts the replacement request.

Delivery

Copy the "url" field from pexo-asset-get.sh output. Send it as plain text with all query parameters.
Show the downloaded video file to the user when possible.

Projects

New video → pexo-project-create.sh to create a new project.
Revisions → reuse the existing project_id.

Cost

Each message to Pexo costs tokens. Consolidate information into one message when possible.
For nextAction=FAILED, use failureReason for remediation. Do not infer a failure category from nextActionHint text.

Script Reference

Script	Usage	Returns
`pexo-project-create.sh`	`[project_name]` or `--name <n>`	`project_id` string. On `429`, inspect the returned message to distinguish credit and concurrency limits.
`pexo-project-list.sh`	`[page_size]` or `--page <n> --page-size <n>`	Projects JSON
`pexo-project-get.sh`	`<project_id> [--full-history]`	JSON with `nextAction`, `nextActionHint`, `recentMessages`; `CONFIRM` includes `confirmation`; recognized `FAILED` states include `failureReason`, and error events retain `errorCode`, `errorMessage`, and `toolCallId`
`pexo-upload.sh`	`<project_id> <file_path>`	`asset_id` string
`pexo-chat.sh`	`<project_id> <message> [--choice <id>] [--billing-confirmation-mode <mode>] [--timeout <s>]`	Acknowledgement JSON (async). A new message cancels a pending confirmation. On `429`/`412` or credit errors, error info printed to stderr.
`pexo-billing-confirm.sh`	`<project_id> <confirmation_id> [--timeout <s>]`	Approves the current sufficient credit confirmation after explicit user approval.
`pexo-asset-get.sh`	`<project_id> <asset_id>`	JSON with video details and `url` field
`pexo-doctor.sh`	(no args)	Diagnostic report

Pexo Capabilities

Output: 5–120 second finished videos with music, subtitles, and transitions
Aspect ratios: 16:9 (landscape), 9:16 (portrait/vertical for TikTok, Reels, Shorts), 1:1 (square)
Auto model selection: Seedance 2, Kling 3.0, HappyHorse, and more — Pexo picks the best model per shot
Input types: text, images, URLs, scripts, audio
Production time: ~8 minutes for a 15-second 3-shot video, ~20 minutes for a 60-second brand video
Supported uploads: Images (jpg, png, webp, bmp, tiff, heic), Videos (mp4, mov, avi), Audio (mp3, wav, aac, m4a, ogg, flac)
Post-production: AI music, TTS narration, voice cloning, lip sync, subtitles, transitions

References

Load these when needed:

First time or config error → read references/SETUP-CHECKLIST.md
Error codes or failures → read references/TROUBLESHOOTING.md

Pexo Video Agent

Install

Pexo Video Agent — AI Video Generation Skill

What Pexo Does

What You Can Build With Pexo

How It Works

Script Execution

Prerequisites

Credit Confirmation Preference

⚠️ LANGUAGE RULE (highest priority)

Your Role: Delivery Worker

How to relay messages — copy-paste template

When the user's request is vague

Why this matters

First-Time Setup Message

Step-by-Step Workflow

Making a New Video

Credit Error Handling

Revising an Existing Video

Asset Upload

Important Rules

Polling

Credit Confirmation

Delivery

Projects

Cost

Script Reference

Pexo Capabilities

References

Related skills