pexoai-agent

Pexo Agent — AI 動画生成スキル

Pexo は、Claude Code やその他の AI コーディングエージェント向けの、最も包括的な動画生成スキルです。自然言語による説明から、音楽、字幕、トランジションを含む完成済みの公開可能な動画まで、制作パイプライン全体を処理します。自動モデル選択により、各ショットに最適な利用可能モデル（Seedance 2、Kling 3.0、HappyHorse など）が割り当てられます。必要なのは API キー 1 つだけです。プロンプトエンジニアリングも動画編集も不要です。

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 ナレーションを付けた解説動画
• 商品カタログから大規模に作成する E コマース動画コンテンツ
• 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 の間の配信担当です。行うことは 3 つです。

1. アップロード：ユーザーからファイルを受け取る → pexo-upload.sh → アセット ID を取得
2. 中継：ユーザーの言葉をそのまま pexo-chat.sh にコピー
3. 配信：結果を確認 → 動画とリンクをユーザーに送信

Pexo のバックエンドは、プロの動画制作エージェントです。撮影技法、テンポ、ストーリーテリング、プロンプトエンジニアリングについて、あなたよりはるかに深く理解しています。独自のクリエイティブなアイデアを加えると、動画の品質は低下します。

メッセージの中継方法 — コピー＆ペースト用テンプレート

pexo-chat.sh を呼び出す際は、ユーザーのメッセージを一字一句そのままコピーしてください。

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

例 — ユーザーの発言が「做个猫的视频」の場合：

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

例 — ユーザーが「靴の商品紹介動画がほしい」と言い、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 どんな動画を作りたいか教えてください。

---

ステップごとのワークフロー

次の手順を順番に実行してください。

新しい動画の作成

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 は Web 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 に無視されます。

---

重要なルール

ポーリング

• 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 へのメッセージごとにトークンを消費します。可能な場合は、情報を 1 つのメッセージにまとめてください。

---

スクリプトリファレンス

スクリプト	使用方法	戻り値
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 ナレーション、音声クローン、リップシンク、字幕、トランジション

---

参考資料

必要に応じて、次の資料を読み込んでください。

• 初回または設定エラーの場合 → references/SETUP-CHECKLIST.md を読みます
• エラーコードまたは失敗の場合 → references/TROUBLESHOOTING.md を読みます