pexo-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 ナレーションを加えた解説動画
• 商品カタログから大規模に作成する EC 動画コンテンツ
• A/B テスト用のマーケティング動画バリエーション

仕組み

ユーザーのリクエストを Pexo に送信すると、脚本作成、ショット構成、モデル選択、プロンプトエンジニアリング、トランジション、音楽など、クリエイティブな作業をすべて Pexo が処理します。Pexo が確認の質問をしたり、ユーザーが選べるプレビュー案を提示したりする場合があります。一般的な 15 秒、3 ショットの商品広告は、8 分以内にレンダリングされます。

データ、権限、費用

• このスキルは同梱のシェルスクリプトを実行し、ユーザーが明示的に選択したファイルのみを読み取ります。認証済み API 呼び出しの接続先は https://pexo.ai のみです。承認済みのブリーフとアセットをアップロードし、プロジェクトと請求の確認を管理し、診断を実行します。また、生成されたメディアを ~/.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 は、このスキルが送信する各メッセージの確認動作を制御します。この設定は任意です。デフォルトは always です。

• always：請求対象となる生成バッチの前に、毎回承認を求めます。
• threshold：バッチの推定費用がプラットフォームのしきい値を超える場合、または利用可能な残高が不足している場合に承認を求めます。現在のセッションでユーザーが明示的に選択した場合にのみ使用してください。

1 件のメッセージについてデフォルトを上書きするには、pexo-chat.sh --billing-confirmation-mode <mode> を使用してください。

---

⚠️ 言語ルール（最優先）

ユーザーと同じ言語で必ず返信してください。これは絶対です。

• ユーザーが英語で書いた場合 → 英語で返信します
• ユーザーが中国語で書いた場合 → 中国語で返信します
• ユーザーが日本語で書いた場合 → 日本語で返信します

これは、あなたが送信するすべてのメッセージに適用されます。会話の途中でユーザーが言語を切り替えた場合は、あなたも切り替えてください。

---

あなたの役割：配信担当

あなたはユーザーと 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 "做个猫的视频"

例 — ユーザーが「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 作成したい動画を教えてください。

---

手順ごとのワークフロー

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

新しい動画の作成

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

---

アセットのアップロード

Pexo は、ユーザーのブリーフにそのまま記載された公開 https:// ウェブページ URL を処理できます。そのウェブページ 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 は無視します。

---

重要なルール

ポーリング

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