krusemediallc/arcads-claude-code

Arcads external API: agent skills, prompting library, and Cursor/Claude workspace

此儲存庫的功能

Arcads AI Video – Agent Skill Pack 是一套可立即執行的 Claude Code（及 Cursor）「技能」集合，讓您能使用 Arcads 生成式媒體平台來生成以廣告為重點的圖片與短影片。它整合了以下功能：

影片模型 – Seedance 2.0、Sora 2、Veo 3.1、Kling 3.0、Grok Video、OmniHuman、音訊驅動 – 每個模型都透過一個小型 CLI 風格的技能公開，處理提示詞、API 呼叫、輪詢、成本確認與檔案儲存。
圖片模型 – Nano Banana 2/Pro/Edit 與 ChatGPT Image 2 – 用於網紅角色設定表、產品靜態圖以及 37 種 Meta 靜態廣告模板庫。
多步驟流程 – 例如：分鏡腳本生成 → Seedance 影片 → ffmpeg 拼接 → 字幕燒錄，或 Pixar 風格 3D 廣告、黏土動畫風格廣告、YouTube 縮圖批次處理等。
Meta 廣告發布 – 一個 meta-ad-builder 技能，可將完成的素材上傳至 Meta Marketing API 作為暫停狀態的廣告。

所有這些都封裝為一組 Claude Code 技能（同時支援 Cursor），並附帶少量 Bash/Node 輔助腳本。本儲存庫不包含 Arcads 服務本身；您需要一個 Arcads 帳號與 API 金鑰，一次性的 setup.sh 腳本會將其儲存在本地的 .env 檔案中。

適用對象

媒體採購 / 成效行銷人員，希望自動化 Facebook/Meta 廣告的創意製作。
自由廣告創作者，尋求可重複的工作流程來生成網紅風格影片、UGC 風格短片或高影響力的靜態圖片廣告。
開發人員，希望獲得一個具體範例，了解如何在單一端到端流程中編排多個生成式 AI 模型（影片、圖片、音訊）。

如何開始（快速入門步驟）

複製並執行安裝程式
```
git clone https://github.com/krusemediallc/arcads-claude-code.git
cd arcads-claude-code
./scripts/setup.sh
```
腳本會提示輸入您的 Arcads API 金鑰，將其寫入 .env，驗證連線，並建立個人化的 MASTER_CONTEXT.md 工作區檔案。
在 Claude Code（或 Cursor）中開啟資料夾 – 編輯器會執行 SessionStart 掛鉤，顯示可用的技能以及您的環境是否就緒。
選擇工作流程 – README 列出了現成的提示詞，例如：
- Seedance 2.0 UGC selfie – 12 秒的產品評論影片。
- generate-youtube-thumbnail – 五種高點擊率 (CTR) 縮圖公式。
- pixar-style-ad – 分鏡腳本 → Seedance 影片 → ffmpeg 拼接。
執行技能 – 透過 Claude Code 的 UI 或呼叫對應的 Bash/Node 腳本。代理程式將會：
- 詢問任何缺失的參數（產品名稱、參考圖片等），
- 顯示預估的點數成本，以及
- 發起 Arcads API 呼叫，輪詢完成狀態，並將輸出檔案寫入 outputs/ 資料夾。
(選用) 發布 – 使用 meta-ad-builder 技能搭配您的 Meta 存取權杖，將素材以上傳為暫停狀態的廣告。

關鍵技術細節

領域	儲存庫提供的內容
核心語言	用於 Arcads API 封裝的純 Python 3.10+；大多數圖片廣告腳本僅使用標準函式庫（無外部套件）。
CLI 輔助工具	Bash 腳本 (`setup.sh`, `check-arcads-env.sh`, `sync-skill.sh`) 以及少量 Node 步驟 (`npx hyperframes` 用於字幕燒錄)。
外部工具	`ffmpeg` (影片拼接、去背字幕疊加), `jq` (JSON 處理), `whisper` (音訊轉錄), Node.js (HyperFrames)。
技能組織	每個功能位於 `skills/…` 下（例如 `skills/arcads-external-api/`, `skills/generate-youtube-thumbnail/`）。共享工具與提示詞庫位於 `shared/skills/`。
提示詞庫	針對每個影片模型（Seedance, Sora, Veo 等）及 37 種靜態廣告模板的現成 Markdown 提示詞模板。
成本追蹤	每次 API 呼叫都會記錄到 `logs/arcads-api.jsonl` 並包含 `creditsCharged`；代理程式會讀取此檔案以在生成前提供準確的成本估算。
參考素材	`references/` (git-ignored) 存放網紅照片、產品照與風格參考資料夾，代理程式會在需要時自動放大這些素材。
狀態化工作區	`MASTER_CONTEXT.md` 作為持久記憶檔案 – 代理程式會讀取/寫入產品預設值、品牌語氣、點數總額與工作階段筆記。

適用場景與不適用場景

如果您已經擁有 Arcads 帳號，並且想要一種「隨插即用」的方式從本地開發環境驅動其影片/圖片模型（特別是針對廣告創意製作），請使用此儲存庫。

若符合以下情況，請跳過：

需要一個通用的、與模型無關的生成式 AI 框架（此儲存庫與 Arcads 緊密耦合）。
想要一個無需任何本地設定的完全託管 SaaS 解決方案（您應該直接使用 Arcads 的 UI）。
正在尋找一個沒有 Claude Code 技能腳手架的純 Python 函式庫。

主要支援模型快速參考

模型	類型	典型用途
Seedance 2.0	影片 (4-15 秒)	旗艦廣告短片 – UGC 自拍、高級產品展示、英雄鏡頭、型錄、功能演示。
Sora 2	影片 (最長 20 秒)	較長的文字轉影片敘事；可混搭現有素材。
Veo 3.1	影片 (~8 秒)	將單幀網紅靜態圖動畫化為短片。
Kling 3.0	影片 (5-10 秒)	B-roll 或通用場景生成。
Grok Video	影片	xAI 的文字轉影片模型。
Nano Banana 2 / Pro	圖片	網紅角色設定表、產品靜態圖、靜態廣告素材。
ChatGPT Image 2	圖片	UI 風格、文字密集的靜態 Meta 廣告。
OmniHuman / 音訊驅動	影片	說話頭像或口型同步影片。

總結

arcads-claude-code 是一個真實、功能齊全的工具包，它將一系列生成式 AI 模型（影片、圖片、音訊）串聯成生產就緒的廣告流程，並透過 Claude Code/Cursor 技能進行編排。如果您是一位熟悉終端機操作的行銷人員或開發人員，並希望自動化 Meta 廣告活動的創意部分，此儲存庫為您提供了一個完整且具備文件說明的起點。