arcads-ai-video-agent

# Arcads AI Video Agent > Skill by [ara.so](https://ara.so) — Claude Code Skills collection. This skill enables AI agents to create marketing videos and images using the [Arcads](https://arcads.ai/?via=claude-code) platform. It supports the full creative stack: **Seedance 2.0** (flagship video), **Sora 2**, **Veo 3.1**, **Kling 3.0**, **Grok Video**, **Nano Banana 2/Pro/Edit**, **ChatGPT Image 2**, **OmniHuman**, and **Audio-driven** models, plus 37 validated static Meta image-ad templates and multi-step pipelines for Pixar-style and claymation animated ads. ## Prerequisites - Python 3.10+ - Arcads API key from [app.arcads.ai/settings/api](https://app.arcads.ai/settings/api) - Optional tools for advanced workflows: - `ffmpeg` (video stitching, chroma-key) - `jq` (JSON parsing in bash scripts) - Node.js + `npx hyperframes` (caption burn-in) - `openai-whisper` (transcription: `pip install openai-whisper`) ## Installation ```bash # Clone the repository git clone https://github.com/krusemediallc/arcads-claude-code.git cd arcads-claude-code # Run setup script ./scripts/setup.sh ``` The setup script will: 1. Prompt for your Arcads API key 2. Create `.env` file with `ARCADS_API_KEY=your_key_here` 3. Verify API connection 4. Create `MASTER_CONTEXT.md` workspace file **Manual setup** (if you skip the script): ```bash # Create .env file echo "ARCADS_API_KEY=your_api_key_here" > .env ``` ## Core API Patterns All Arcads API calls follow this pattern: ```python import os import requests import time from dotenv import load_dotenv load_dotenv() BASE_URL = "https://api.arcads.ai" API_KEY = os.getenv("ARCADS_API_KEY") headers = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json" } ``` ### Standard Generation Flow 1. **Submit job** → get `jobId` 2. **Poll status** until `completed` or `failed` 3. **Download result** ```python def submit_job(endpoint, payload): """Submit a generation job to Arcads API""" response = requests.post( f"{BASE_URL}{endpoint}", headers=headers, json=payload ) response.raise_for_status() return response.json()["jobId"] def poll_status(job_id, timeout=600, interval=10): """Poll job status until complete""" start_time = time.time() while time.time() - start_time < timeout: response = requests.get( f"{BASE_URL}/v1/jobs/{job_id}", headers=headers ) data = response.json() status = data["status"] if status == "completed": return data["result"] elif status == "failed": raise Exception(f"Job failed: {data.get('error')}") time.sleep(interval) raise TimeoutError(f"Job {job_id} timed out after {timeout}s") def download_file(url, output_path): """Download generated asset""" response = requests.get(url, stream=True) response.raise_for_status() with open(output_path, 'wb') as f: for chunk in response.iter_content(chunk_size=8192): f.write(chunk) ``` ## Video Generation ### Seedance 2.0 (Flagship Model) **Best for:** UGC videos, product reveals, hero shots, lookbooks, feature demos (4-15s) ```python def generate_seedance_video(prompt, duration=10, style="ugc"): """Generate Seedance 2.0 video with prompt engineering""" # UGC formula (9-layer structure) if style == "ugc": full_prompt = f""" [PERSON] Woman, late 20s, natural makeup, casual kitchen setting [OPENER] Direct camera eye contact, authentic energy, "Hey guys!" [HOOK] Attention-grabbing statement about {prompt} [PROBLEM] Relatable pain point, conversational tone [SOLUTION] Product introduction, natural hand gestures [DEMO] Show product in use, realistic interaction [BENEFIT] Key value prop, maintains eye contact [SOCIAL_PROOF] Brief testimonial feel [CTA] Natural call to action, warm energy [STYLE] iPhone selfie aesthetic, natural lighting, slight camera shake """ else: full_prompt = prompt payload = { "prompt": full_prompt, "duration": duration, "aspectRatio": "9:16" # or "16:9", "1:1" } job_id = submit_job("/v2/videos/generate", payload) print(f"Seedance job submitted: {job_id}") result = poll_status(job_id) video_url = result["videoUrl"] download_file(video_url, f"output/seedance_{job_id}.mp4") return video_url ``` **Example usage:** ```python # UGC product review video = generate_seedance_video( "skin serum that reduced dark circles in 2 weeks", duration=12, style="ugc" ) # Premium product reveal payload = { "prompt": """ [SCENE] Dark void, single spotlight [PRODUCT] Luxury perfume bottle materializes [MOTION] Slow 360° rotation, golden light rays [TEXT] Overlay: "Crafted for those who dare" [AESTHETIC] High-contrast, cinematic, no human presence """, "duration": 8, "aspectRatio": "9:16" } job_id = submit_job("/v2/videos/generate", payload) ``` ### Veo 3.1 (Image-to-Video with Dialogue) **Best for:** Animating Nano Banana stills into talking UGC videos ```python def animate_with_veo(image_path, dialogue, duration=8): """Animate a still image with Veo 3.1 + dialogue""" import base64 # Load and encode starting frame with open(image_path, "rb") as f: image_b64 = base64.b64encode(f.read()).decode() payload = { "startFrame": image_b64, "prompt": f""" Natural human motion, authentic energy, person speaks: "{dialogue}" Maintain character likeness from starting frame. iPhone selfie aesthetic, slight head movement, natural eye contact. """, "dialogue": dialogue, # MANDATORY for dialogue videos "duration": duration, "aspectRatio": "9:16" } job_id = submit_job("/v1/veo3-1/video", payload) result = poll_status(job_id, timeout=900) # Veo takes longer download_file(result["videoUrl"], f"output/veo_{job_id}.mp4") return result["videoUrl"] ``` ### Sora 2 (Text-to-Video, Longer Durations) **Best for:** Cinematic scenes, B-roll, up to 20s ```python def generate_sora_video(prompt, duration=16): """Generate Sora 2 video (supports longer durations)""" payload = { "prompt": prompt, "duration": duration, # Auto-calculated from word count if omitted "aspectRatio": "16:9" } # Optional: add style reference image # payload["styleReference"] = base64_encoded_image job_id = submit_job("/v1/sora2/video", payload) result = poll_status(job_id, timeout=1200) download_file(result["videoUrl"], f"output/sora_{job_id}.mp4") return result["videoUrl"] ``` ### Kling 3.0 (B-Roll & Scenes) **Best for:** Scene generation, environmental b-roll ```python def generate_broll(scene_description): """Generate b-roll clip with Kling 3.0""" payload = { "prompt": scene_description, "duration": 5 } job_id = submit_job("/v1/b-roll", payload) result = poll_status(job_id) download_file(result["videoUrl"], f"output/broll_{job_id}.mp4") return result["videoUrl"] # Example generate_broll("Golden hour beach waves, slow motion, cinematic") ``` ## Image Generation ### Nano Banana (Character Creation & Product Stills) **Best for:** AI influencers, UGC stills, photoreal product shots ```python def create_nano_banana_image(prompt, reference_images=None, model="nano-banana-2"): """ Generate image with Nano Banana model options: "nano-banana-2" (default), "nano-banana" (Pro), "nano-banana-edit" """ payload = { "prompt": prompt, "model": model, "aspectRatio": "9:16" } # Add reference images for character consistency if reference_images: import base64 refs = [] for img_path in reference_images: with open(img_path, "rb") as f: refs.append(base64.b64encode(f.read()).decode()) payload["referenceImages"] = refs job_id = submit_job("/v1/nano-banana/image", payload) result = poll_status(job_id) download_file(result["imageUrl"], f"output/nano_{job_id}.png") return result["imageUrl"] ``` **Example: Create AI Influencer (10-image character sheet)** ```python def create_ai_influencer(description): """Generate 10-angle character sheet for AI influencer""" # Step 1: Generate hero front portrait hero_prompt = f""" {description} Front-facing portrait, natural expression, golden hour lighting. Photoreal skin texture, freckles, pores visible. Soft focus background, kitchen setting. """ hero_url = create_nano_banana_image(hero_prompt) print(f"Hero portrait: {hero_url}") print("Review and approve hero before generating remaining 9 angles.") # Step 2: Generate 9 additional angles using hero as reference angles = [ "3/4 view left, slight smile", "3/4 view right, natural expression", "Profile left, looking away", "Profile right, looking forward", "Close-up, eyes focused on camera", "Full body, standing casual pose", "Laughing, animated expression", "Serious expression, direct gaze", "Lifestyle shot, holding coffee mug" ] results = [] for angle in angles: prompt = f"{description}\n{angle}\nMaintain exact character likeness." url = create_nano_banana_image( prompt, reference_images=["output/hero_portrait.png"], model="nano-banana" # Use Pro for tighter identity lock ) results.append(url) return results ``` ### ChatGPT Image 2 (Typography & UI-Heavy Ads) **Best for:** Apple Notes lists, fake Slack threads, editorial layouts, comparison tables ```python def generate_chatgpt_image(prompt, aspect_ratio="1:1"): """Generate image with ChatGPT Image 2 (gpt-image-2)""" payload = { "prompt": prompt, "model": "gpt-image-2", "aspectRatio": aspect_ratio # "1:1", "4:5", "16:9" } job_id = submit_job("/v1/image/generate", payload) result = poll_status(job_id) download_file(result["imageUrl"], f"output/chatgpt_{job_id}.png") return result["imageUrl"] ``` ## Static Meta Image Ad Templates (37-Template Library) The repo includes **37 validated prompt templates** for static Meta image ads. Use the specialized skills: ```python # Apple Notes-style list ad def generate_apple_notes_ad(product, benefits): """Generate Apple Notes-style ad (ChatGPT Image 2)""" prompt = f""" iPhone Notes app interface, cream background. Title: "why i switched to {product}" Bulleted list: {chr(10).join(f'• {b}' for b in benefits)} Footer: handwritten-style signature. Clean iOS typography, authentic spacing, no visible phone edges. """ return generate_chatgpt_image(prompt, aspect_ratio="4:5") # Photoreal UGC selfie ad def generate_ugc_selfie_ad(influencer_ref, product_ref): """Generate UGC selfie with product (Nano Banana)""" prompt = """ iPhone selfie, natural bedroom lighting. [influencer] holding [product], casual smile. Authentic skin texture, slight motion blur. Visible pores, flyaway hairs, iPhone camera imperfections. Product visible and recognizable, natural hand position. """ return create_nano_banana_image( prompt, reference_images=[influencer_ref, product_ref], model="nano-banana-2" ) ``` **Template categories** (see `shared/skills/image-ad-prompting/library/` for full list):