arcads-video-agent

# Arcads Video Agent Skill > Skill by [ara.so](https://ara.so) — Claude Code Skills collection. This skill provides AI agent capabilities for the **Arcads Claude Code** project — a comprehensive toolkit for generating AI marketing videos and images using your Arcads account. 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 static Meta image-ad templates and multi-step pipelines for Pixar-style and claymation animated ads. ## What This Project Does Arcads Claude Code is an agent skill pack that transforms natural language requests into production-ready video and image ads through: - **Video Generation**: UGC selfies, product reveals, b-roll, scene animations (4-20s clips) - **Image Generation**: AI influencer creation, product showcases, UGC stills, photoreal composites - **Static Ad Library**: 37 validated Meta image-ad templates (Apple Notes, Forbes editorial, comparison tables, fake UI screenshots) - **Multi-Step Pipelines**: Pixar-style 3D animation, claymation ads, caption burn-in workflows - **API Orchestration**: Automated polling, cost confirmation, file organization, prompt engineering ## Installation ### Prerequisites ```bash # Required for everything python3 --version # Must be 3.10+ # Optional dependencies (install only if using specific workflows) brew install ffmpeg # For Pixar/claymation/caption workflows brew install jq # For bash pipeline scripts brew install node # For caption burn-in (hyperframes) pip install openai-whisper # For transcription ``` ### Setup ```bash # Clone the repository git clone https://github.com/krusemediallc/arcads-claude-code.git cd arcads-claude-code # Run interactive setup ./scripts/setup.sh ``` The setup script will: 1. Prompt for Arcads API key (get from [app.arcads.ai/settings/api](https://app.arcads.ai/settings/api)) 2. Create `.env` file with credentials 3. Create `MASTER_CONTEXT.md` workspace file 4. Verify API connection ### Configuration Create or verify `.env` in project root: ```bash ARCADS_API_KEY=your_api_key_here ``` ## Core API Usage ### Python API Client Pattern ```python import os import requests import json import time # Load API key from environment API_KEY = os.getenv('ARCADS_API_KEY') BASE_URL = 'https://api.arcads.ai' def make_request(endpoint, method='POST', payload=None): """Standard API request with error handling.""" headers = { 'Authorization': f'Bearer {API_KEY}', 'Content-Type': 'application/json' } url = f'{BASE_URL}{endpoint}' if method == 'POST': response = requests.post(url, headers=headers, json=payload) elif method == 'GET': response = requests.get(url, headers=headers) response.raise_for_status() return response.json() def poll_until_complete(job_id, endpoint='/v1/jobs'): """Poll job status until completion.""" while True: status = make_request(f'{endpoint}/{job_id}', method='GET') if status['status'] in ['completed', 'failed']: return status print(f"Status: {status['status']} - {status.get('progress', 0)}%") time.sleep(5) ``` ## Video Generation Workflows ### Seedance 2.0 — UGC Selfie-Style Product Review ```python def generate_seedance_ugc(product_name, competitor_name, duration=12): """ Generate UGC selfie-style video using 9-layer Seedance prompt formula. See: skills/arcads-external-api/prompting/prompt-library/seedance-2-ugc.md """ payload = { "model": "seedance-2", "duration": duration, "prompt": f""" iPhone selfie POV. Woman in modern kitchen, natural window light. She looks at camera, holds up {product_name} product. "I used to buy {competitor_name} until I found this." She examines the product, reads label, nods approvingly. Direct eye contact: "It's actually cheaper and works better." She sets product on counter, natural smile. Shot style: Handheld iPhone 15 Pro, 0.5x selfie lens. Authentic home lighting, slight motion blur. Real person aesthetic — pores, natural makeup, casual delivery. """, "aspectRatio": "9:16" } # Submit job response = make_request('/v1/seedance2/video', payload=payload) job_id = response['jobId'] print(f"Seedance job submitted: {job_id}") print(f"Estimated cost: ${response.get('estimatedCost', 0)}") # Poll until complete result = poll_until_complete(job_id) if result['status'] == 'completed': video_url = result['videoUrl'] print(f"Video ready: {video_url}") return video_url else: raise Exception(f"Generation failed: {result.get('error')}") ``` ### Veo 3.1 — Image to Video with Dialogue ```python def animate_still_with_veo(image_path, dialogue_script, duration=8): """ Animate a Nano Banana still into video with embedded dialogue. Uses startFrame for exact image match + natural motion. """ import base64 # Load and encode image with open(image_path, 'rb') as f: image_b64 = base64.b64encode(f.read()).decode('utf-8') payload = { "model": "veo-3.1", "duration": duration, "startFrame": image_b64, "prompt": f""" Natural human motion and expression from starting frame. Person speaks: "{dialogue_script}" Subtle head movement, natural blinking, lip sync to dialogue. Hands stay in frame, minimal camera shake. Indoor lighting maintains original atmosphere. """, "dialogue": dialogue_script, # MANDATORY for Veo with speech "aspectRatio": "9:16" } response = make_request('/v1/veo3.1/video', payload=payload) job_id = response['jobId'] result = poll_until_complete(job_id) return result['videoUrl'] ``` ### Sora 2 — Text to Video (Longer Durations) ```python def generate_sora_scene(scene_description, duration=16): """ Generate text-to-video with Sora 2 (up to 20s). Auto-selects duration from script word count (~2.5 words/sec). """ payload = { "model": "sora-2", "duration": duration, "prompt": scene_description, "aspectRatio": "16:9" # Sora works well for landscape } response = make_request('/v1/sora2/video', payload=payload) return poll_until_complete(response['jobId']) ``` ### Kling 3.0 — B-Roll and Scene Generation ```python def generate_broll(scene_description, duration=5): """B-roll clip generation via dedicated endpoint.""" payload = { "prompt": scene_description, "duration": duration, "aspectRatio": "16:9" } response = make_request('/v1/b-roll', payload=payload) return poll_until_complete(response['jobId']) def generate_scene(environment_description, duration=8): """Scene generation via dedicated endpoint.""" payload = { "prompt": environment_description, "duration": duration, "aspectRatio": "16:9" } response = make_request('/v1/scene', payload=payload) return poll_until_complete(response['jobId']) ``` ## Image Generation Workflows ### Create AI Influencer Character Sheet (10 Images) ```python import os def create_ai_influencer(description, name, output_dir='references/influencers'): """ Two-pass workflow: 1. Generate hero front portrait 2. Generate 9 additional angles using hero as reference """ os.makedirs(f'{output_dir}/{name}', exist_ok=True) # Phase 1: Hero portrait hero_payload = { "model": "nano-banana-2", "prompt": f""" Front-facing portrait: {description} Direct eye contact, neutral expression, even lighting. Sharp focus, professional photo quality. """, "aspectRatio": "1:1" } hero_response = make_request('/v1/nano-banana/image', payload=hero_payload) hero_result = poll_until_complete(hero_response['jobId']) hero_url = hero_result['imageUrl'] print(f"Hero portrait generated: {hero_url}") print("Review and approve before generating additional angles? (y/n)") # Download hero import requests hero_img = requests.get(hero_url).content with open(f'{output_dir}/{name}/00_hero.png', 'wb') as f: f.write(hero_img) # Phase 2: Generate 9 additional angles import base64 hero_b64 = base64.b64encode(hero_img).decode('utf-8') angles = [ "3/4 profile, looking slightly left", "3/4 profile, looking slightly right", "Full side profile, looking left", "Close-up, slight smile", "Close-up, neutral expression", "Torso shot, arms crossed", "Full body, standing casual", "Candid laugh, natural", "Thoughtful expression, hand on chin" ] for idx, angle_desc in enumerate(angles, start=1): payload = { "model": "nano-banana-2", "prompt": f"{description}. Angle: {angle_desc}", "referenceImages": [hero_b64], "aspectRatio": "1:1" } response = make_request('/v1/nano-banana/image', payload=payload) result = poll_until_complete(response['jobId']) # Download and save img_data = requests.get(result['imageUrl']).content with open(f'{output_dir}/{name}/{idx:02d}_{angle_desc[:20]}.png', 'wb') as f: f.write(img_data) print(f"Generated angle {idx}/9: {angle_desc}") print(f"\n✓ Character sheet complete: {output_dir}/{name}/") ``` ### UGC Product Selfie Still ```python def generate_ugc_selfie(character_ref_path, product_ref_path, scene_desc): """ Combine character + product + UGC aesthetic refs into authentic selfie. Includes skin realism and camera imperfections. """ import base64 # Load references with open(character_ref_path, 'rb') as f: char_b64 = base64.b64encode(f.read()).decode('utf-8') with open(product_ref_path, 'rb') as f: prod_b64 = base64.b64encode(f.read()).decode('utf-8') # Load UGC aesthetic references (up to 5 total) ugc_refs = [] for ref_file in ['ugc-lighting-1.jpg', 'ugc-composition-1.jpg']: ref_path = f'references/aesthetics/ugc-selfie/{ref_file}' if os.path.exists(ref_path): with open(ref_path, 'rb') as f: ugc_refs.append(base64.b64encode(f.read()).decode('utf-8')) all_refs = [char_b64, prod_b64] + ugc_refs[:3] # Max 5 refs payload = { "model": "nano-banana-2", "prompt": f""" iPhone 15 Pro selfie, 0.5x front camera. {scene_desc} Person holds product naturally, slight motion blur on hand. Window light from left, natural shadows on face. Realistic skin texture: pores visible, slight blemishes, natural makeup. Camera imperfections: slight lens distortion, auto-focus hunting. Authentic home environment, visible mess in background. Casual clothing, natural expression (not model pose). """, "referenceImages": all_refs, "aspectRatio": "9:16" } response = make_request('/v1/nano-banana/image', payload=payload) result = poll_until_complete(response['jobId']) return result['imageUrl'] ``` ### Nano Banana Model Selection ```python def generate_nano_banana(prompt, model="nano-banana-2", reference_images=None): """ Generate image with Nano Banana model selection: - nano-banana-2: Default, balanced quality/speed - nano-banana: Nano Banana Pro (Gemini 3 Pro Image) — higher fidelity - nano-banana-edit: Inpainting/editing workflow """ payload = { "model": model, "prompt": prompt, "aspectRatio": "1:1" } if reference_images: payload["referenceImages"] = reference_images response = make_request('/v1/nano-banana/image', payload=payload) return poll_until_complete(response['jobId']) ```