# Creative Tagger

> Structured creative intelligence API for performance marketing. Analyzes any creative — video, image, carousel, landing page, email — and returns classification across a human-readable taxonomy with naming conventions.

## API

Base URL: https://api.creativetagger.ai
Docs: https://api.creativetagger.ai/docs

### POST /analyze
Upload any creative format and get structured classification.

Accepts multipart form data:
- `file` — file upload (image or video)
- `file_url` — direct URL to image/video
- `page_url` — landing page URL
- `html_content` — raw HTML for email analysis
- `brand_name` (required) — brand name for naming conventions

Returns JSON with taxonomy v2 attributes:
- asset_type, visual_format, visual_style, talent
- audience (dynamic), messaging_angle (dynamic)
- hook_type, hook_text, cta, emotion
- audio_type, voiceover_tone
- seasonality, offer_type
- 4 naming conventions: standard, full, compact, reporting

### Authentication
Pass API key via `X-API-Key` header. Get a free key at POST /auth/signup.

## Taxonomy v2

### Visual
- Asset Type: UGC, Lifestyle, Product Shot, Studio, High Production, Screen Recording, Stock, AI Generated, Animation, Mixed Media
- Visual Format: Talking Head, Testimonial, Before After, Unboxing, Problem Agitate, Listicle, Text Overlay, Mashup, Demo, Social Proof, Founder Story, Comparison, Tutorial, Meme, Scroll Stopper, Skit, Podcast Clip, Green Screen, Slideshow, Carousel, Static Image
- Visual Style: Minimal, Bold, Organic, Dark, Bright, Editorial, Lo-Fi, Hi-Fi, Native Feel, Branded, Retro, Clean

### Talent
- No Talent, Creator, Model, Founder, Customer, Voiceover Only, Hands Only, Employee, Expert, Influencer

### Persona
- Audience: dynamic (AI-generated per brand)
- Messaging Angle: dynamic (AI-generated per brand)

### Hook
- Hook Type: Question, Bold Claim, Callout, Contrarian, Confession, If Then, Statistic, Urgency, Curiosity Gap, Social Proof, Pain Point, Transformation, Challenge, Story Open, Pattern Interrupt

### CTA
- Shop Now, Learn More, Sign Up, Get Offer, Book Now, Download, Subscribe, Watch More, Swipe Up, Try Free, No CTA

### Audio
- Audio Type: Voiceover + Music, Voiceover Only, Music Only, Trending Sound, Native Audio, Silent
- Voiceover Tone: Conversational, Urgent, Authoritative, Friendly, Whispery, Energetic, Calm, None

### Emotion
- Urgency, Curiosity, Trust, Fear, Desire, Humor, Aspiration, Relief, Belonging, Neutral

### Metadata
- Seasonality: Evergreen, Black Friday, Cyber Monday, Holiday, New Year, Valentines, Mothers Day, Fathers Day, Back To School, Summer, Spring, Fall, Prime Day, Launch, Flash Sale
- Offer Type: No Offer, Percent Off, Dollar Off, Free Shipping, BOGO, Bundle, Free Gift, Subscribe Save, Limited Time, Clearance
- Aspect Ratio: 1x1, 4x5, 9x16, 16x9, 1.91x1
- Duration: 6s, 15s, 30s, 60s, 90s+

## Naming Templates
- Standard: Brand_AssetType_Format_Talent_Hook_CTA_Ratio_V1
- Full: all dimensions
- Compact: Brand_Format_Talent_CTA_Ratio_V1
- Reporting: Brand_AssetType_Format_Audience_Angle_Hook_Season_V1

## Integration
- MCP Server: pip install creative-tagger-mcp
- Python SDK: pip install creative-tagger
- OpenAPI spec: https://api.creativetagger.ai/openapi.json