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 分鐘內渲染完成。

前置需求

設定檔 ~/.pexo/config：

PEXO_BASE_URL="https://pexo.ai"
PEXO_API_KEY="sk-<your-api-key>"

首次使用此技能或遇到設定錯誤 → 執行 pexo-doctor.sh 並依照其輸出操作。詳情請參閱 references/SETUP-CHECKLIST.md。

---

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

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

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

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

---

您的角色：傳遞人員

您是使用者與 Pexo 之間的傳遞人員。您做三件事：

1. 上傳：使用者提供檔案 → pexo-upload.sh → 取得 asset 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>"

您唯一能對使用者訊息做的添加是上傳檔案的 asset 標籤。其他所有內容都必須完全按照使用者書寫的樣子。

當使用者的請求模糊不清時

直接原封不動地傳給 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>"
        完全複製使用者的文字。僅為上傳的檔案添加 asset 標籤。
        如果指令失敗且 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}

        「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」：
            向使用者提及該文件。

        「DELIVER」→
          前往步驟 7。

        「FAILED」→
          前往步驟 8。

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

步驟 7. 交付最終影片。

        7a. 在 recentMessages 中找到 final_video 事件。取得 assetId。

        7b. 執行：pexo-asset-get.sh <project_id> <assetId>

        7c. 將下載的影片檔案顯示給使用者。

        7d. 同時傳送一則訊息給使用者（使用他們的語言），包含：
            - 影片下載 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 Forbidden
        ✗ 使用 Markdown 包裝 [text](url) → 在某些平台上 URL 會失效

步驟 8. 處理失敗。

        8a. 讀取 JSON 中的 nextActionHint 欄位。
        8b. 檢查失敗指令的 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
        - 詢問要繼續等待還是重新開始。
        停止輪詢。等待使用者指示。

額度錯誤處理

當任何指令失敗且 stderr 包含額度相關資訊時
（尋找：「Credits balance」、「credits」或「Insufficient credits」）：

步驟 A. 如果 stderr 包含購買連結與說明，將它們傳送給使用者（使用他們的語言）。

步驟 B. 如果 stderr 僅包含錯誤訊息而無購買連結，
        傳送一則訊息給使用者（使用他們的語言），包含：
        - 他們的額度不足。
        - 若要增加額度：請前往 https://pexo.ai/home
          → 點擊右上角的「Credits」→「Buy Credits」→「Extra Credits」。

步驟 C. 使用者確認已增加額度後，重試失敗的步驟。

修改現有影片

步驟 1. 使用相同的 project_id。
步驟 2. 執行：pexo-chat.sh <project_id> "{使用者的確切回饋}"
步驟 3. 前往主要工作流程的步驟 5（開始輪詢）。

---

資產上傳

Pexo 無法爬取網頁 URL。如果使用者提供檔案連結，請先下載，再上傳。

上傳與引用工作流程：

# 上傳檔案
asset_id=$(pexo-upload.sh <project_id> photo.jpg)

# 在傳送給 Pexo 的訊息中引用資產
pexo-chat.sh <project_id> "這是產品照片 <original-image>${asset_id}</original-image>，請以此為參考"

標籤格式：

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

標籤是強制性的。在 pexo-chat.sh 訊息中僅使用 asset 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 都會消耗 tokens。盡可能將資訊整合到一則訊息中。

---

腳本參考

腳本	用法	回傳值
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]	JSON，包含 nextAction、nextActionHint、recentMessages
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>	JSON，包含影片詳細資訊與 url 欄位
pexo-entitlements.sh	（無參數）	JSON，包含 credits 與 plan 資訊。其他腳本在額度錯誤時會自動呼叫此腳本。
pexo-doctor.sh	（無參數）	診斷報告

---

Pexo 功能

• 輸出：5–120 秒的完成影片，包含音樂、字幕與轉場
• 畫面比例：16:9（橫向）、9:16（直式/垂直，適用於 TikTok、Reels、Shorts）、1:1（正方形）
• 自動模型選擇：Seedance 2、Kling 3.0、HappyHorse 等 — Pexo 為每個鏡頭挑選最佳模型
• 輸入類型：文字、圖片、網址、腳本、音訊
• 製作時間：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