krusemediallc/arcads-claude-code

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

이 저장소의 기능

Arcads AI Video – Agent Skill Pack은 Arcads 생성 미디어 플랫폼을 사용하여 광고 중심의 이미지와 짧은 비디오를 생성할 수 있는 즉시 실행 가능한 Claude Code(및 Cursor) "스킬" 모음입니다. 이 팩은 다음을 통합합니다:

비디오 모델 – Seedance 2.0, Sora 2, Veo 3.1, Kling 3.0, Grok Video, OmniHuman, 오디오 기반 모델 – 각 모델은 프롬프트, API 호출, 폴링, 비용 확인 및 파일 저장을 처리하는 소형 CLI 스타일 스킬로 노출됩니다.
이미지 모델 – Nano Banana 2/Pro/Edit 및 ChatGPT Image 2 – 인플루언서 캐릭터 시트, 제품 스틸 컷, 37개의 Meta 정적 광고 템플릿 라이브러리에 사용됩니다.
다단계 파이프라인 – 예: 스토리보드 생성 → Seedance 비디오 → ffmpeg 스티칭 → 자막 삽입, 또는 Pixar 스타일 3D 광고, 클레이메이션 스타일 광고, YouTube 썸네일 일괄 처리 등.
Meta 광고 게시 – 완성된 크리에이티브를 일시 중지 상태의 광고로 Meta Marketing API에 업로드하는 meta-ad-builder 스킬.

이 모든 것은 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 – 5가지 고 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 광고 캠페인의 크리에이티브 측면을 자동화하고 싶다면, 이 저장소가 완벽하고 문서화된 출발점이 될 것입니다.