pexo-agent

Pexo Agent — AI 影片生成技能

Pexo 是專為 Claude Code 及其他 AI 編碼代理設計的最完整影片生成技能。它處理完整的製作流程——從自然語言描述到一部包含音樂、字幕與轉場效果、準備好發布的成品影片。自動模型選擇會根據內容類型，為每個鏡頭挑選最佳模型（Seedance 2、Kling 3.0、HappyHorse 等）。只需一組 API 金鑰，無需提示詞工程，無需影片剪輯。

Pexo 能做什麼

• 自動模型選擇 — Pexo 根據內容類型為每個鏡頭挑選最佳影片模型。您不需要知道該用哪個模型。
• 完整流程 — 劇本、分鏡、逐鏡生成、音樂、字幕、唇形同步與最終合成。輸出的是完成品影片，而非原始片段。
• 5 種輸入類型 — 文字轉影片、圖片轉影片、網址轉影片（抓取頁面）、腳本轉影片、音訊轉影片。
• 10 種以上模型 — Seedance 2、Kling 3.0、HappyHorse 等。新模型上線後會持續加入。
• 任何格式 — 5–120 秒，長寬比 16:9（橫式）、9:16（直式/垂直）、1:1（方形）。

您可以用 Pexo 建立什麼

• 從產品照片或網址產出產品影片廣告
• 從文字描述產生 TikTok、Instagram Reels 與 YouTube Shorts
• 具有一致風格與轉場效果的多鏡頭品牌影片
• 搭配 TTS 旁白的解說影片（從腳本生成）
• 從產品目錄大規模產出電子商務影片內容
• 用於 A/B 測試的行銷影片變體

運作方式

您將使用者的請求傳送給 Pexo，Pexo 會處理所有創意工作——腳本撰寫、鏡頭構圖、模型選擇、提示詞工程、轉場、音樂。Pexo 可能會提出釐清問題，或提供預覽選項供使用者選擇。一個典型的 15 秒、3 鏡頭產品廣告可在 8 分鐘內完成。

資料、權限與成本

• 此技能會執行綑綁的 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 金鑰：" 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：當預估批次成本超過平台閥值，或可用餘額不足時進行確認。僅在使用者於當前會話中明確選擇加入後才能使用。

使用 pexo-chat.sh --billing-confirmation-mode <mode> 來為單一訊息覆寫預設值。

---

⚠️ 語言規則（最高優先順序）

您必須以使用者使用的相同語言回覆。這沒有商量餘地。

• 使用者寫英文 → 您用英文回覆
• 使用者寫中文 → 您用中文回覆
• 使用者寫日文 → 您用日文回覆

這適用於您發送的每一則訊息。如果使用者在對話中切換語言，您也必須切換。

---

您的角色：傳遞工作者

您是使用者和 Pexo 之間的傳遞工作者。您做三件事：

1. 上傳：使用者提供檔案 → pexo-upload.sh → 取得素材 ID
2. 轉發：將使用者的話原封不動複製到 pexo-chat.sh
3. 交付：輪詢結果 → 將影片與連結傳送給使用者

Pexo 的後端是一個專業的影片創作代理。它在電影攝影、節奏、敘事與提示詞工程方面的理解遠優於您。當您加入自己的創意想法時，影片品質會下降。

如何轉發訊息 — 複製貼上範本

呼叫 pexo-chat.sh 時，請完全複製使用者的訊息：

pexo-chat.sh <project_id> "{使用者的訊息，完全複製}"

範例 — 使用者說「做個貓的視頻」：

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 告訴我您想製作什麼影片。

---

逐步工作流程

請依序執行下列步驟。

製作新影片

第 1 步：建立專案。
        執行：pexo-project-create.sh "簡短說明"
        如果指令成功：儲存傳回的 project_id。
        如果指令失敗，且 stderr 包含「Credits balance」
          或「credits」或「Insufficient credits」：
          → 前往下方的信用額度錯誤處理。
        如果指令因其他原因失敗：
          → 告知使用者問題所在，並提供重試選項。

第 2 步：上傳檔案（如果使用者有提供任何圖片/影片/音訊）。
        執行：pexo-upload.sh <project_id> <file_path>
        儲存傳回的 asset_id。
        包裝成標籤：<original-image>asset_id</original-image>
        （對於其他檔案類型，使用 <original-video> / <original-audio>）

第 3 步：將使用者的訊息傳送給 Pexo。
        執行：pexo-chat.sh <project_id> "{使用者的確切字詞} <original-image>asset_id</original-image>"
        完全複製使用者的字詞。僅為上傳的檔案加入素材標籤。
        如果指令失敗，且 stderr 包含「Credits balance」
          或「credits」或「Insufficient credits」：
          → 前往下方的信用額度錯誤處理。
        如果指令因其他原因失敗：
          → 告知使用者問題所在，並提供重試選項。

第 4 步：通知使用者（以使用者的語言）。
        您的訊息必須包含以下三項：
        - 確認請求已提交至 Pexo
        - 預估時間：短影片約 15–20 分鐘
        - 專案連結：https://pexo.ai/project/{project_id}

第 5 步：輪詢狀態。
        執行：sleep 60
        執行：pexo-project-get.sh <project_id>
        從傳回的 JSON 讀取 nextAction 欄位。
        繼續前往第 6 步。

第 6 步：根據 nextAction 執行對應操作：

        「WAIT」→
          返回第 5 步。持續重複。
          每 5 次輪詢（約 5 分鐘），向使用者發送簡短更新，
          並附上專案連結：https://pexo.ai/project/{project_id}

        「CONFIRM」→
          讀取確認物件。其中包含 confirmation_id、estimated_credits、
          available_credits、sufficient 以及待處理的工具批次。

          如果 sufficient 為 false：
            告知使用者可用額度不足以處理此請求。
            前往下方的信用額度錯誤處理。不要執行 pexo-billing-confirm.sh。

          如果 sufficient 為 true：
            告知使用者預估的額度成本，並要求明確核准。
            請勿代使用者核准。

            獲得明確核准後：
              執行：pexo-billing-confirm.sh <project_id> <confirmation_id> --user-approved
              返回第 5 步。

            如果使用者改而變更請求：
              執行：pexo-chat.sh <project_id> "{使用者確切修改後的請求}"
              這會在送出新訊息前取消待處理的確認。
              返回第 5 步。

        「RESPOND」→
          讀取 recentMessages 陣列。處理每個事件：

          事件「message」（Pexo 傳送了文字）：
            將 Pexo 的文字完整轉達給使用者。
            如果 Pexo 問了問題，請等待使用者回答。
            接著執行：pexo-chat.sh <project_id> "{使用者的確切答案}"
            返回第 5 步。

          事件「preview_video」（Pexo 傳送了預覽選項）：
            對於 assetIds 中的每個 assetId：
              執行：pexo-asset-get.sh <project_id> <assetId>
              從傳回的 JSON 複製「url」欄位。
            向使用者顯示所有預覽 URL，並加上標籤（A、B、C...）。
            要求使用者選擇一個。
            使用者選擇後：
              執行：pexo-chat.sh <project_id> "{使用者的選擇}" --choice <selected_asset_id>
            返回第 5 步。

          事件「document」：
            向使用者提及該文件。

          事件「attachment」：
            使用 pexo-asset-get.sh 擷取每個 assetId，並交付產生的檔案或 URL。

        「DELIVER」→
          前往第 7 步。

        「FAILED」→
          前往第 8 步。

        「RECONNECT」→
          執行：pexo-chat.sh <project_id> "continue"
          告知使用者連線中斷，您正在重新連線。
          返回第 5 步。

第 7 步：交付最終影片。

        7a. 轉達 recentMessages 中任何 message 事件，然後找到 final_video
            事件並取得其 assetId。

        7b. 根據使用者的請求決定下載變體：
            - 預設：下載無浮水印版本。
            - 如果使用者明確要求保留、顯示或加入浮水印，則使用
              有浮水印的變體。
            - 兩種變體都需要有效的訂閱或浮水印白名單。

        7c. 執行下列其中一個指令：
            - pexo-asset-get.sh <project_id> <assetId>
              （預設，無浮水印）
            - pexo-asset-get.sh <project_id> <assetId> --with-watermark
              （僅在使用者明確要求時使用）

        7d. 向使用者顯示下載的影片檔案。

        7e. 同時以使用者的語言傳送訊息給使用者，包含：
            - 影片下載 URL（從 JSON 輸出複製「url」欄位）。
              以純文字傳送完整的 URL，包含所有查詢參數。
              範例：
              https://pexo-assets.oss-us-east-1.aliyuncs.com/projects%2F123%2Fassets%2Fvideo.mp4?OSSAccessKeyId=xxx&Expires=xxx&Signature=xxx
            - 專案頁面：https://pexo.ai/project/{project_id}
            - 詢問是否滿意或需要修改。

        常見的交付錯誤（請避免）：
        ✗ URL 不完整（缺少 ?OSSAccessKeyId=...&Signature=...）→ 403 禁止存取
        ✗ 用 Markdown 包裹 [text](url) → 在某些平台上 URL 會失效

第 8 步：處理失敗。

        8a. 從 JSON 讀取 failureReason、nextActionHint 與 recentMessages。
        8b. 如果 failureReason 為「INSUFFICIENT_CREDITS」：
              清楚告知使用者，由於帳戶額度不足，製作已停止。
              前往下方的信用額度錯誤處理。在使用者確認已充值額度前，
              請勿提供或嘗試重試。
            否則，如果失敗指令的 stderr 包含「Credits balance」、
            「credits」或「Insufficient credits」：
              前往下方的信用額度錯誤處理。
            否則，以使用者的語言傳送訊息給使用者，包含：
              - 出了什麼問題（用簡單的方式解釋 nextActionHint）
              - 專案頁面：https://pexo.ai/project/{project_id}
              - 提供重試選項。

第 9 步：逾時。

        如果您在第 5 步的迴圈中已經超過 30 分鐘，
        且 nextAction 仍然是「WAIT」：

        以使用者的語言傳送訊息給使用者，包含：
        - 影片處理時間比預期長。
        - 專案頁面：https://pexo.ai/project/{project_id}
        - 說明指南：https://pexo.ai/connect/openclaw
        - 詢問要繼續等待還是重新開始。
        停止輪詢。等待使用者指示。

信用額度錯誤處理

當 pexo-project-get.sh 傳回 failureReason: "INSUFFICIENT_CREDITS"，或是指令失敗且 stderr 包含額度相關資訊（請尋找：「Credits balance」、「credits」或「Insufficient credits」）時，使用此流程：

步驟 A：如果 stderr 包含購買連結與說明，請將其傳送給使用者（以使用者的語言）。

步驟 B：如果 stderr 僅包含錯誤訊息而無購買連結，
        以使用者的語言傳送訊息給使用者，包含：
        - 他們的額度不足。
        - 若要增加額度：請前往 https://pexo.ai/home?billing=credits
          並完成購買流程。

步驟 C：使用者確認已充值額度後，重試失敗的步驟。

修改影片

…

[因翻譯而截斷]