{ "name": "FrameThrower API", "version": "v1", "description": "Cinematography reference search engine. Search curated film frames by concept, color, mood, composition, or image similarity. Returns metadata, thumbnails, AI prompts, and deep links — never raw image bytes. Built for agents, creative tools, and production pipelines.", "docs": "https://framethrower.ai/developers", "openapi": "https://framethrower.ai/api/v1/openapi.json", "base_url": "https://framethrower.ai/api/v1", "auth": { "type": "bearer", "header": "Authorization: Bearer ft_YOUR_TOKEN", "how_to_get_token": "Sign up at https://framethrower.ai/?signin=1 (free, no card), then create a token at https://framethrower.ai/settings?tab=api" }, "pricing": { "model": "usage-based credits, no rate limits and no subscription required", "free_on_signup": "200 credits, no card", "rate": "$1 = 1,000 credits", "cost_per_call": { "/search": 2, "/search/color": 2, "/search/image": 10, "/similar": 2, "/browse": 2, "/films": 2, "/films/:slug": 2, "/films/frames": 2, "/frames": 2, "/frames/random": 2, "/suggest": 0 }, "in_plain_terms": "$1 buys 500 searches, or 100 image searches. /suggest is free — it is an in-memory prefix match and costs us nothing to serve.", "commercials_cost_per_call": { "/commercials/search": 2, "/commercials/spots": 2, "/commercials/spots/:id": 2, "/commercials/spots/:id/similar": 2, "/commercials/shots/search": 2, "/commercials/shots/image": 10, "/commercials/shots/similar": 2, "/commercials/shots/:id": 2, "/commercials/stats": 2, "/commercials/profile/:kind/:name": 2, "/commercials/suggest": 0, "/commercials/vocabulary": 0 }, "commercials_cost_with_clips": 8, "animation_cost_per_call": { "/animation/frames/search": 4, "/animation/frames/similar": 2, "/animation/titles/search": 2, "/animation/titles/:slug": 2, "/animation/frames/:id/sequence": 2, "/animation/vocabulary": 0 }, "animation_cost_with_clips": 8, "animation_cost_with_image": 10, "response_headers": { "X-Credits-Cost": "credits this call cost", "X-Credits-Remaining": "balance after this call" }, "out_of_credits": "HTTP 402 with {code: \"insufficient_credits\", cost, balance, buy_credits}", "buy_credits": "https://framethrower.ai/settings?tab=billing" }, "endpoints": [ { "method": "POST", "path": "/search", "description": "Text search — describe a mood, scene, or visual concept in natural language.", "parameters": { "query": { "type": "string", "required": true, "description": "Natural language search query" }, "limit": { "type": "integer", "default": 20, "min": 1, "max": 50 }, "enhance": { "type": "boolean", "default": true, "description": "Smart search (default on): rewrites short or fragmentary queries into the descriptive language the frames were indexed with, like the website does. Send false to search your exact text. The rewrite comes back as meta.enhancedQuery." }, "mode": { "type": "string", "default": "hybrid", "enum": [ "hybrid", "description" ], "description": "hybrid (default, use this) fuses the image embedding with the scene-description embedding via reciprocal rank fusion; description ranks on the written scene descriptions only — better when the query is about story, action, or named objects" } }, "example": { "query": "neon-lit rainy street at night", "limit": 5 } }, { "method": "POST", "path": "/search/image", "description": "Image search — find frames matching a reference image by visual similarity, color, and semantic meaning.", "parameters": { "imageUrl": { "type": "string", "required": true, "description": "URL of a reference image" }, "limit": { "type": "integer", "default": 20, "min": 1, "max": 50 } }, "example": { "imageUrl": "https://example.com/reference.jpg", "limit": 10 } }, { "method": "POST", "path": "/search/color", "description": "Color search — find frames dominated by specific hex colors or a palette.", "parameters": { "color": { "type": "string", "description": "Single hex color (e.g. \"#e94560\"). Use color OR colors, not both." }, "colors": { "type": "array", "description": "Array of up to 6 hex colors blended together." }, "limit": { "type": "integer", "default": 20, "min": 1, "max": 50 } }, "example": { "colors": [ "#e94560", "#1a1a2e", "#16213e" ], "limit": 10 } }, { "method": "POST", "path": "/browse", "description": "Browse by craft — filter frames by cinematography attributes. No text query needed. Combine any filters. Closed-vocabulary values are listed in `enum`; common spellings (\"close-up\", \"magic hour\") are normalized for you, and anything unrecognised comes back in meta.hint rather than as a silent empty result.", "parameters": { "shot_type": { "type": "string", "enum": [ "medium", "closeup", "wide", "fullbody", "establishing" ] }, "lens_character": { "type": "string", "enum": [ "anamorphic", "spherical", "vintage_soft" ] }, "setting": { "type": "string", "enum": [ "interior", "exterior", "both" ] }, "time_of_day": { "type": "string", "enum": [ "night", "day", "interior_indeterminate", "golden_hour", "dusk", "blue_hour", "dawn", "overcast" ] }, "camera_angle": { "type": "string", "enum": [ "eye_level", "high_angle", "low_angle", "top_down", "overhead", "worms_eye", "dutch_angle", "pov", "birds_eye" ] }, "visual_style": { "type": "string", "enum": [ "live_action", "cg_stylized", "anime", "cg_photorealistic", "cartoon_2d", "stop_motion", "mixed_media", "rotoscope", "noir", "watercolor", "minimalist", "documentary", "expressionist", "painterly", "surreal" ] }, "director": { "type": "string", "description": "Director name — free text, e.g. \"Ridley Scott\"" }, "genre": { "type": "string", "description": "Genre name — free text, e.g. \"Science Fiction\"" }, "era": { "type": "string", "description": "Depicted era, e.g. \"1980s\", \"near_future\", \"medieval\"" }, "year_min": { "type": "integer", "description": "Release year lower bound" }, "year_max": { "type": "integer", "description": "Release year upper bound" }, "limit": { "type": "integer", "default": 20, "min": 1, "max": 50 } }, "example": { "shot_type": "closeup", "lens_character": "anamorphic", "time_of_day": "night", "limit": 10 } }, { "method": "POST", "path": "/similar", "description": "Find frames similar to a reference frame or the centroid of multiple frames.", "parameters": { "frameId": { "type": "string", "description": "Single frame ID. Use frameId OR frameIds, not both." }, "frameIds": { "type": "array", "description": "Array of frame IDs to average (find centroid)." }, "mode": { "type": "string", "default": "semantic", "enum": [ "semantic", "visual", "color" ] }, "limit": { "type": "integer", "default": 20, "min": 1, "max": 50 } }, "example": { "frameId": "abc123", "mode": "visual", "limit": 5 } }, { "method": "GET", "path": "/frames?id=FRAME_ID", "description": "Frame detail — full metadata, AI image prompt, film info, cinematography attributes for a single frame.", "parameters": { "id": { "type": "string", "required": true, "description": "Frame ID (from search results)" } } }, { "method": "GET", "path": "/frames/random?limit=20", "description": "Random diverse sample of frames. Useful for inspiration or seeding a UI.", "parameters": { "limit": { "type": "integer", "default": 20, "min": 1, "max": 50 } } }, { "method": "GET", "path": "/suggest?q=QUERY", "description": "Autocomplete — fuzzy-match film titles and director/DP names.", "parameters": { "q": { "type": "string", "required": true, "description": "Search prefix (min 2 chars)", "min_length": 2 } } }, { "method": "GET", "path": "/films?page=1&per_page=50&q=kubrick&sort=frames", "description": "Paginated film catalog with poster art. Every entry carries `slug`, `frameCount`, and a ready-made `framesUrl` — list films, then pull their frames.", "parameters": { "page": { "type": "integer", "default": 1 }, "per_page": { "type": "integer", "default": 50, "max": 100 }, "q": { "type": "string", "description": "Filter by film title, director, or cinematographer name" }, "sort": { "type": "string", "default": "title", "enum": [ "title", "frames", "year" ], "description": "frames = most frames first, the best-covered films" }, "min_frames": { "type": "integer", "description": "Only films with at least this many frames" } }, "example": { "q": "kubrick", "sort": "frames" } }, { "method": "GET", "path": "/films/:slug", "description": "Film detail — plot, runtime, MPAA rating, dominant colors, sample frames.", "parameters": { "slug": { "type": "string", "required": true, "description": "Film slug from the catalog (e.g. \"blade-runner-2049-2017\")" } } }, { "method": "GET", "path": "/films/frames?slug=SLUG&page=1&per_page=100", "description": "Every frame we hold for one film, paginated. meta.total is the full frame count for the film, so page 1 tells you the whole size.", "parameters": { "slug": { "type": "string", "required": true, "description": "Film slug from /films or from any frame's film.slug" }, "page": { "type": "integer", "default": 1 }, "per_page": { "type": "integer", "default": 100, "max": 200 } }, "example": { "slug": "blade-runner-2049-2017", "per_page": 24 } } ], "commercials": { "description": "The commercials library: award-winning and everyday TV / online spots with credits for every role, awards, story, script and every shot tagged — at two levels, whole spots (/commercials/search, /spots) and shots inside them (/commercials/shots/*). Stills are URLs; add clips: true to any shot call (or a spot with its shot list) and each shot comes with its clip_url too, on every plan — that call costs 8 credits instead of 2 (image search stays 10); the full-spot video file is never served — each result links to watch it on FrameThrower. The same account also reaches the film library (/search, /browse, /similar…), and on framethrower.ai the animation library, the moodboard / lookbook builder and the canvas — commercial, film and animation references side by side, the whole treatment in one place.", "endpoints": [ { "method": "POST", "path": "/commercials/search", "description": "Whole commercials by idea or story (\"two rival neighbours outdo each other at Christmas\") and/or any filter — brand, every credit role, award show and level, year, industry, market, tone, genre, structure, season. Without `query` it lists matches, award winners first (Grand Prix → Gold → Silver → Bronze → shortlist, then the rest newest first). Each spot: brand, title, year, credits, best award, logline, tones, tropes, a still and a watch link.", "cost": 2, "parameters": { "query": { "type": "string", "description": "The idea / story in plain words (optional)" }, "brand": { "type": "string", "description": "Advertiser, e.g. \"Nike\". Comma-separate for several." }, "not_brand": { "type": "string", "description": "Leave these advertisers out" }, "director": { "type": "string", "description": "Credited director — a name" }, "agency": { "type": "string", "description": "Credited agency — a name" }, "production": { "type": "string", "description": "Credited production — a name" }, "dp": { "type": "string", "description": "Credited dp — a name" }, "editor": { "type": "string", "description": "Credited editor — a name" }, "edit_house": { "type": "string", "description": "Credited edit house — a name" }, "post": { "type": "string", "description": "Credited post — a name" }, "music": { "type": "string", "description": "Credited music — a name" }, "sound": { "type": "string", "description": "Credited sound — a name" }, "vfx": { "type": "string", "description": "Credited vfx — a name" }, "person": { "type": "string", "description": "Anyone credited, in any role" }, "industry": { "type": "string", "description": "Ad category: Auto, Beer, Spirits, Drinks, Food & QSR, Retail, Tech, Telecom, Finance & Insurance, Fashion & Luxury, Beauty & Personal care, Sport, Travel, Gaming, Health & Pharma, Media & Entertainment, Public service & NGO, Home, FMCG (plain words work: \"cars\", \"banks\")" }, "market": { "type": "string", "description": "Country code: US, UK, FR, DE, BR, JP…" }, "language": { "type": "string", "description": "Spoken language code: en, es, fr…" }, "genre": { "type": "string", "description": "comedy, drama, documentary…" }, "structure": { "type": "string", "description": "narrative, montage, vignettes, problem_solution, demo…" }, "format": { "type": "string", "description": "live_action, animation_2d, animation_3d, stop_motion, cgi, motion_graphics, mixed" }, "tone": { "type": "string", "description": "funny, heartwarming, epic, emotional, absurd, dark, inspiring…" }, "trope": { "type": "string", "description": "A trope in plain words" }, "season": { "type": "string", "description": "A calendar moment: halloween, christmas, black friday, thanksgiving, new year, valentines, easter, mothers day, fathers day, back to school, summer, spring, pride, super bowl" }, "year_min": { "type": "integer", "description": "Spot year from" }, "year_max": { "type": "integer", "description": "Spot year to" }, "min_duration": { "type": "integer", "description": "Seconds" }, "max_duration": { "type": "integer", "description": "Seconds" }, "awarded": { "type": "boolean", "description": "true = won or was shortlisted at an award show" }, "award_show": { "type": "string", "description": "Award show", "enum": [ "Cannes Lions", "Clio Awards", "D&AD", "Epica", "AICP Awards", "London International Awards", "British Arrows", "The One Show", "El Ojo de Iberoamérica", "Eurobest", "Creative Circle", "Effie Awards", "Ciclope", "Spikes Asia", "ANDY Awards", "ADC Awards", "DGA Awards", "Kinsale Sharks", "shots Awards", "New York Festivals", "Webby Awards", "Emmy (Outstanding Commercial)", "IPA Effectiveness Awards", "AdFest", "Dubai Lynx", "ADC Europe", "Young Director Award" ] }, "min_award": { "type": "string", "description": "Best award at least this level", "enum": [ "grand_prix", "gold", "silver", "bronze", "shortlist" ] }, "award_year": { "type": "integer", "description": "Year of the award" }, "celebrity": { "type": "boolean", "description": "true = a recognizable person appears" }, "sort": { "type": "string", "description": "relevance (with query) | awards | newest | oldest" }, "limit": { "type": "integer", "description": "1–50", "default": 12 }, "offset": { "type": "integer", "description": "Paging offset", "default": 0 } }, "example": { "query": "a product demo told as a heist", "industry": "Auto", "min_award": "gold", "limit": 5 } }, { "method": "GET", "path": "/commercials/spots", "description": "The same as POST /commercials/search, as a GET with query parameters — for links and caches.", "cost": 2, "parameters": { "brand": { "type": "string", "description": "Advertiser, e.g. \"Nike\". Comma-separate for several." }, "not_brand": { "type": "string", "description": "Leave these advertisers out" }, "director": { "type": "string", "description": "Credited director — a name" }, "agency": { "type": "string", "description": "Credited agency — a name" }, "production": { "type": "string", "description": "Credited production — a name" }, "dp": { "type": "string", "description": "Credited dp — a name" }, "editor": { "type": "string", "description": "Credited editor — a name" }, "edit_house": { "type": "string", "description": "Credited edit house — a name" }, "post": { "type": "string", "description": "Credited post — a name" }, "music": { "type": "string", "description": "Credited music — a name" }, "sound": { "type": "string", "description": "Credited sound — a name" }, "vfx": { "type": "string", "description": "Credited vfx — a name" }, "person": { "type": "string", "description": "Anyone credited, in any role" }, "industry": { "type": "string", "description": "Ad category: Auto, Beer, Spirits, Drinks, Food & QSR, Retail, Tech, Telecom, Finance & Insurance, Fashion & Luxury, Beauty & Personal care, Sport, Travel, Gaming, Health & Pharma, Media & Entertainment, Public service & NGO, Home, FMCG (plain words work: \"cars\", \"banks\")" }, "market": { "type": "string", "description": "Country code: US, UK, FR, DE, BR, JP…" }, "language": { "type": "string", "description": "Spoken language code: en, es, fr…" }, "genre": { "type": "string", "description": "comedy, drama, documentary…" }, "structure": { "type": "string", "description": "narrative, montage, vignettes, problem_solution, demo…" }, "format": { "type": "string", "description": "live_action, animation_2d, animation_3d, stop_motion, cgi, motion_graphics, mixed" }, "tone": { "type": "string", "description": "funny, heartwarming, epic, emotional, absurd, dark, inspiring…" }, "trope": { "type": "string", "description": "A trope in plain words" }, "season": { "type": "string", "description": "A calendar moment: halloween, christmas, black friday, thanksgiving, new year, valentines, easter, mothers day, fathers day, back to school, summer, spring, pride, super bowl" }, "year_min": { "type": "integer", "description": "Spot year from" }, "year_max": { "type": "integer", "description": "Spot year to" }, "min_duration": { "type": "integer", "description": "Seconds" }, "max_duration": { "type": "integer", "description": "Seconds" }, "awarded": { "type": "boolean", "description": "true = won or was shortlisted at an award show" }, "award_show": { "type": "string", "description": "Award show", "enum": [ "Cannes Lions", "Clio Awards", "D&AD", "Epica", "AICP Awards", "London International Awards", "British Arrows", "The One Show", "El Ojo de Iberoamérica", "Eurobest", "Creative Circle", "Effie Awards", "Ciclope", "Spikes Asia", "ANDY Awards", "ADC Awards", "DGA Awards", "Kinsale Sharks", "shots Awards", "New York Festivals", "Webby Awards", "Emmy (Outstanding Commercial)", "IPA Effectiveness Awards", "AdFest", "Dubai Lynx", "ADC Europe", "Young Director Award" ] }, "min_award": { "type": "string", "description": "Best award at least this level", "enum": [ "grand_prix", "gold", "silver", "bronze", "shortlist" ] }, "award_year": { "type": "integer", "description": "Year of the award" }, "celebrity": { "type": "boolean", "description": "true = a recognizable person appears" }, "sort": { "type": "string", "description": "awards | newest | oldest" }, "limit": { "type": "integer", "description": "1–50", "default": 12 }, "offset": { "type": "integer", "description": "Paging offset", "default": 0 } }, "example": { "director": "Jonathan Glazer", "sort": "awards" } }, { "method": "GET", "path": "/commercials/spots/:id", "description": "Everything about one spot: idea, logline, tagline, product, audience, talent; credits by role (director, agency, production, DP, editor, edit house, post, music, sound, VFX); every award (show, year, level, category); craft numbers (shots, average shot length, cuts per minute, when the product / brand / emotional peak / end card land); the script with timings; and the shot list — caption, tags, palette, first / middle / last frame and the clip of each shot, with its shot id.", "cost": 2, "parameters": { "id": { "type": "string", "description": "Commercial id, e.g. AD-0505", "required": true }, "words": { "type": "boolean", "description": "Add word-level timings to the script" }, "shots": { "type": "boolean", "description": "false = leave out the shot list" }, "clips": { "type": "boolean", "description": "true = include each shot's clip_url — the call then costs 8 credits (image search stays 10)" } } }, { "method": "GET", "path": "/commercials/spots/:id/similar", "description": "Commercials like this one — by=story (idea, tropes, tone) or by=look (their shots look alike; each result names the matching shot). Takes any spot filter to narrow.", "cost": 2, "parameters": { "id": { "type": "string", "description": "Commercial id", "required": true }, "by": { "type": "string", "description": "story | look", "default": "story" }, "limit": { "type": "integer", "description": "1–30", "default": 8 }, "brand": { "type": "string", "description": "Advertiser, e.g. \"Nike\". Comma-separate for several." }, "not_brand": { "type": "string", "description": "Leave these advertisers out" }, "director": { "type": "string", "description": "Credited director — a name" }, "agency": { "type": "string", "description": "Credited agency — a name" }, "production": { "type": "string", "description": "Credited production — a name" }, "dp": { "type": "string", "description": "Credited dp — a name" }, "editor": { "type": "string", "description": "Credited editor — a name" }, "edit_house": { "type": "string", "description": "Credited edit house — a name" }, "post": { "type": "string", "description": "Credited post — a name" }, "music": { "type": "string", "description": "Credited music — a name" }, "sound": { "type": "string", "description": "Credited sound — a name" }, "vfx": { "type": "string", "description": "Credited vfx — a name" }, "person": { "type": "string", "description": "Anyone credited, in any role" }, "industry": { "type": "string", "description": "Ad category: Auto, Beer, Spirits, Drinks, Food & QSR, Retail, Tech, Telecom, Finance & Insurance, Fashion & Luxury, Beauty & Personal care, Sport, Travel, Gaming, Health & Pharma, Media & Entertainment, Public service & NGO, Home, FMCG (plain words work: \"cars\", \"banks\")" }, "market": { "type": "string", "description": "Country code: US, UK, FR, DE, BR, JP…" }, "language": { "type": "string", "description": "Spoken language code: en, es, fr…" }, "genre": { "type": "string", "description": "comedy, drama, documentary…" }, "structure": { "type": "string", "description": "narrative, montage, vignettes, problem_solution, demo…" }, "format": { "type": "string", "description": "live_action, animation_2d, animation_3d, stop_motion, cgi, motion_graphics, mixed" }, "tone": { "type": "string", "description": "funny, heartwarming, epic, emotional, absurd, dark, inspiring…" }, "trope": { "type": "string", "description": "A trope in plain words" }, "season": { "type": "string", "description": "A calendar moment: halloween, christmas, black friday, thanksgiving, new year, valentines, easter, mothers day, fathers day, back to school, summer, spring, pride, super bowl" }, "year_min": { "type": "integer", "description": "Spot year from" }, "year_max": { "type": "integer", "description": "Spot year to" }, "min_duration": { "type": "integer", "description": "Seconds" }, "max_duration": { "type": "integer", "description": "Seconds" }, "awarded": { "type": "boolean", "description": "true = won or was shortlisted at an award show" }, "award_show": { "type": "string", "description": "Award show", "enum": [ "Cannes Lions", "Clio Awards", "D&AD", "Epica", "AICP Awards", "London International Awards", "British Arrows", "The One Show", "El Ojo de Iberoamérica", "Eurobest", "Creative Circle", "Effie Awards", "Ciclope", "Spikes Asia", "ANDY Awards", "ADC Awards", "DGA Awards", "Kinsale Sharks", "shots Awards", "New York Festivals", "Webby Awards", "Emmy (Outstanding Commercial)", "IPA Effectiveness Awards", "AdFest", "Dubai Lynx", "ADC Europe", "Young Director Award" ] }, "min_award": { "type": "string", "description": "Best award at least this level", "enum": [ "grand_prix", "gold", "silver", "bronze", "shortlist" ] }, "award_year": { "type": "integer", "description": "Year of the award" }, "celebrity": { "type": "boolean", "description": "true = a recognizable person appears" }, "clips": { "type": "boolean", "description": "true = include each shot's clip_url — the call then costs 8 credits (image search stays 10)" } } }, { "method": "POST", "path": "/commercials/shots/search", "description": "Individual shots by what is in frame (\"hand pouring beer in slow motion\"), with shot tags and any commercial-level filter (brand, director, agency, award show, year…). Look-alike copies of one shot (cutdowns, re-uploads) are skipped and counted in meta.look_alikes_hidden. The query is rewritten into the register the shots were described in (benchmarked precision@12 0.68 → 0.83); send enhance:false for the raw words.", "cost": 2, "parameters": { "query": { "type": "string", "description": "What the shot shows", "required": true }, "shot_size": { "type": "string", "description": "extreme_closeup, closeup, medium_closeup, medium, medium_wide, full, wide, extreme_wide, insert" }, "camera_angle": { "type": "string", "description": "eye_level, low_angle, high_angle, overhead, aerial, pov, worms_eye, dutch" }, "setting": { "type": "string", "description": "interior | exterior | studio_void | virtual_cg" }, "time_of_day": { "type": "string", "description": "day, night, golden_hour, dusk, dawn…" }, "lighting": { "type": "string", "description": "natural, high_key, low_key, silhouette, chiaroscuro" }, "mood": { "type": "string", "description": "A mood tag" }, "place": { "type": "string", "description": "Place type, e.g. \"kitchen\"" }, "people": { "type": "string", "description": "women, men, kids, teens, adults, seniors — comma = all of them" }, "product_visible": { "type": "boolean", "description": "The product is in frame" }, "logo_visible": { "type": "boolean", "description": "The brand logo is in frame" }, "text_on_screen": { "type": "boolean", "description": "Text on screen" }, "black_and_white": { "type": "boolean", "description": "Black-and-white shot" }, "brand": { "type": "string", "description": "Advertiser, e.g. \"Nike\". Comma-separate for several." }, "not_brand": { "type": "string", "description": "Leave these advertisers out" }, "director": { "type": "string", "description": "Credited director — a name" }, "agency": { "type": "string", "description": "Credited agency — a name" }, "production": { "type": "string", "description": "Credited production — a name" }, "dp": { "type": "string", "description": "Credited dp — a name" }, "editor": { "type": "string", "description": "Credited editor — a name" }, "edit_house": { "type": "string", "description": "Credited edit house — a name" }, "post": { "type": "string", "description": "Credited post — a name" }, "music": { "type": "string", "description": "Credited music — a name" }, "sound": { "type": "string", "description": "Credited sound — a name" }, "vfx": { "type": "string", "description": "Credited vfx — a name" }, "person": { "type": "string", "description": "Anyone credited, in any role" }, "industry": { "type": "string", "description": "Ad category: Auto, Beer, Spirits, Drinks, Food & QSR, Retail, Tech, Telecom, Finance & Insurance, Fashion & Luxury, Beauty & Personal care, Sport, Travel, Gaming, Health & Pharma, Media & Entertainment, Public service & NGO, Home, FMCG (plain words work: \"cars\", \"banks\")" }, "market": { "type": "string", "description": "Country code: US, UK, FR, DE, BR, JP…" }, "language": { "type": "string", "description": "Spoken language code: en, es, fr…" }, "genre": { "type": "string", "description": "comedy, drama, documentary…" }, "structure": { "type": "string", "description": "narrative, montage, vignettes, problem_solution, demo…" }, "format": { "type": "string", "description": "live_action, animation_2d, animation_3d, stop_motion, cgi, motion_graphics, mixed" }, "tone": { "type": "string", "description": "funny, heartwarming, epic, emotional, absurd, dark, inspiring…" }, "trope": { "type": "string", "description": "A trope in plain words" }, "season": { "type": "string", "description": "A calendar moment: halloween, christmas, black friday, thanksgiving, new year, valentines, easter, mothers day, fathers day, back to school, summer, spring, pride, super bowl" }, "year_min": { "type": "integer", "description": "Spot year from" }, "year_max": { "type": "integer", "description": "Spot year to" }, "min_duration": { "type": "integer", "description": "Seconds" }, "max_duration": { "type": "integer", "description": "Seconds" }, "awarded": { "type": "boolean", "description": "true = won or was shortlisted at an award show" }, "award_show": { "type": "string", "description": "Award show", "enum": [ "Cannes Lions", "Clio Awards", "D&AD", "Epica", "AICP Awards", "London International Awards", "British Arrows", "The One Show", "El Ojo de Iberoamérica", "Eurobest", "Creative Circle", "Effie Awards", "Ciclope", "Spikes Asia", "ANDY Awards", "ADC Awards", "DGA Awards", "Kinsale Sharks", "shots Awards", "New York Festivals", "Webby Awards", "Emmy (Outstanding Commercial)", "IPA Effectiveness Awards", "AdFest", "Dubai Lynx", "ADC Europe", "Young Director Award" ] }, "min_award": { "type": "string", "description": "Best award at least this level", "enum": [ "grand_prix", "gold", "silver", "bronze", "shortlist" ] }, "award_year": { "type": "integer", "description": "Year of the award" }, "celebrity": { "type": "boolean", "description": "true = a recognizable person appears" }, "spot": { "type": "string", "description": "Only inside this commercial (id)" }, "per_spot": { "type": "integer", "description": "Max shots from one commercial", "default": 3 }, "enhance": { "type": "boolean", "description": "Rewrite the query first (default true)" }, "limit": { "type": "integer", "description": "1–50", "default": 20 }, "offset": { "type": "integer", "description": "≤150", "default": 0 }, "clips": { "type": "boolean", "description": "true = include each shot's clip_url — the call then costs 8 credits (image search stays 10)" } }, "example": { "query": "car drifting at night in the rain", "industry": "Auto", "time_of_day": "night", "limit": 10 } }, { "method": "POST", "path": "/commercials/shots/image", "description": "Shots that look like a reference image (an http(s) URL or a data: URL, ≤ 8 MB). The image is embedded in the same space as the shots' stills. Takes shot tags and spot filters.", "cost": 10, "parameters": { "imageUrl": { "type": "string", "description": "http(s) or data: URL", "required": true }, "shot_size": { "type": "string", "description": "extreme_closeup, closeup, medium_closeup, medium, medium_wide, full, wide, extreme_wide, insert" }, "camera_angle": { "type": "string", "description": "eye_level, low_angle, high_angle, overhead, aerial, pov, worms_eye, dutch" }, "setting": { "type": "string", "description": "interior | exterior | studio_void | virtual_cg" }, "time_of_day": { "type": "string", "description": "day, night, golden_hour, dusk, dawn…" }, "lighting": { "type": "string", "description": "natural, high_key, low_key, silhouette, chiaroscuro" }, "mood": { "type": "string", "description": "A mood tag" }, "place": { "type": "string", "description": "Place type, e.g. \"kitchen\"" }, "people": { "type": "string", "description": "women, men, kids, teens, adults, seniors — comma = all of them" }, "product_visible": { "type": "boolean", "description": "The product is in frame" }, "logo_visible": { "type": "boolean", "description": "The brand logo is in frame" }, "text_on_screen": { "type": "boolean", "description": "Text on screen" }, "black_and_white": { "type": "boolean", "description": "Black-and-white shot" }, "brand": { "type": "string", "description": "Advertiser, e.g. \"Nike\". Comma-separate for several." }, "not_brand": { "type": "string", "description": "Leave these advertisers out" }, "director": { "type": "string", "description": "Credited director — a name" }, "agency": { "type": "string", "description": "Credited agency — a name" }, "production": { "type": "string", "description": "Credited production — a name" }, "dp": { "type": "string", "description": "Credited dp — a name" }, "editor": { "type": "string", "description": "Credited editor — a name" }, "edit_house": { "type": "string", "description": "Credited edit house — a name" }, "post": { "type": "string", "description": "Credited post — a name" }, "music": { "type": "string", "description": "Credited music — a name" }, "sound": { "type": "string", "description": "Credited sound — a name" }, "vfx": { "type": "string", "description": "Credited vfx — a name" }, "person": { "type": "string", "description": "Anyone credited, in any role" }, "industry": { "type": "string", "description": "Ad category: Auto, Beer, Spirits, Drinks, Food & QSR, Retail, Tech, Telecom, Finance & Insurance, Fashion & Luxury, Beauty & Personal care, Sport, Travel, Gaming, Health & Pharma, Media & Entertainment, Public service & NGO, Home, FMCG (plain words work: \"cars\", \"banks\")" }, "market": { "type": "string", "description": "Country code: US, UK, FR, DE, BR, JP…" }, "language": { "type": "string", "description": "Spoken language code: en, es, fr…" }, "genre": { "type": "string", "description": "comedy, drama, documentary…" }, "structure": { "type": "string", "description": "narrative, montage, vignettes, problem_solution, demo…" }, "format": { "type": "string", "description": "live_action, animation_2d, animation_3d, stop_motion, cgi, motion_graphics, mixed" }, "tone": { "type": "string", "description": "funny, heartwarming, epic, emotional, absurd, dark, inspiring…" }, "trope": { "type": "string", "description": "A trope in plain words" }, "season": { "type": "string", "description": "A calendar moment: halloween, christmas, black friday, thanksgiving, new year, valentines, easter, mothers day, fathers day, back to school, summer, spring, pride, super bowl" }, "year_min": { "type": "integer", "description": "Spot year from" }, "year_max": { "type": "integer", "description": "Spot year to" }, "min_duration": { "type": "integer", "description": "Seconds" }, "max_duration": { "type": "integer", "description": "Seconds" }, "awarded": { "type": "boolean", "description": "true = won or was shortlisted at an award show" }, "award_show": { "type": "string", "description": "Award show", "enum": [ "Cannes Lions", "Clio Awards", "D&AD", "Epica", "AICP Awards", "London International Awards", "British Arrows", "The One Show", "El Ojo de Iberoamérica", "Eurobest", "Creative Circle", "Effie Awards", "Ciclope", "Spikes Asia", "ANDY Awards", "ADC Awards", "DGA Awards", "Kinsale Sharks", "shots Awards", "New York Festivals", "Webby Awards", "Emmy (Outstanding Commercial)", "IPA Effectiveness Awards", "AdFest", "Dubai Lynx", "ADC Europe", "Young Director Award" ] }, "min_award": { "type": "string", "description": "Best award at least this level", "enum": [ "grand_prix", "gold", "silver", "bronze", "shortlist" ] }, "award_year": { "type": "integer", "description": "Year of the award" }, "celebrity": { "type": "boolean", "description": "true = a recognizable person appears" }, "per_spot": { "type": "integer", "description": "Max shots from one commercial", "default": 2 }, "limit": { "type": "integer", "description": "1–50", "default": 20 }, "clips": { "type": "boolean", "description": "true = include each shot's clip_url — the call then costs 8 credits (image search stays 10)" } } }, { "method": "POST", "path": "/commercials/shots/similar", "description": "More shots that look like these shot ids (from a search or a shot list) — the \"more like #3\" refine loop. Takes shot tags and spot filters to steer.", "cost": 2, "parameters": { "shot_ids": { "type": "array", "items": { "type": "string" }, "description": "1–10 shot ids", "required": true }, "shot_size": { "type": "string", "description": "extreme_closeup, closeup, medium_closeup, medium, medium_wide, full, wide, extreme_wide, insert" }, "camera_angle": { "type": "string", "description": "eye_level, low_angle, high_angle, overhead, aerial, pov, worms_eye, dutch" }, "setting": { "type": "string", "description": "interior | exterior | studio_void | virtual_cg" }, "time_of_day": { "type": "string", "description": "day, night, golden_hour, dusk, dawn…" }, "lighting": { "type": "string", "description": "natural, high_key, low_key, silhouette, chiaroscuro" }, "mood": { "type": "string", "description": "A mood tag" }, "place": { "type": "string", "description": "Place type, e.g. \"kitchen\"" }, "people": { "type": "string", "description": "women, men, kids, teens, adults, seniors — comma = all of them" }, "product_visible": { "type": "boolean", "description": "The product is in frame" }, "logo_visible": { "type": "boolean", "description": "The brand logo is in frame" }, "text_on_screen": { "type": "boolean", "description": "Text on screen" }, "black_and_white": { "type": "boolean", "description": "Black-and-white shot" }, "brand": { "type": "string", "description": "Advertiser, e.g. \"Nike\". Comma-separate for several." }, "not_brand": { "type": "string", "description": "Leave these advertisers out" }, "director": { "type": "string", "description": "Credited director — a name" }, "agency": { "type": "string", "description": "Credited agency — a name" }, "production": { "type": "string", "description": "Credited production — a name" }, "dp": { "type": "string", "description": "Credited dp — a name" }, "editor": { "type": "string", "description": "Credited editor — a name" }, "edit_house": { "type": "string", "description": "Credited edit house — a name" }, "post": { "type": "string", "description": "Credited post — a name" }, "music": { "type": "string", "description": "Credited music — a name" }, "sound": { "type": "string", "description": "Credited sound — a name" }, "vfx": { "type": "string", "description": "Credited vfx — a name" }, "person": { "type": "string", "description": "Anyone credited, in any role" }, "industry": { "type": "string", "description": "Ad category: Auto, Beer, Spirits, Drinks, Food & QSR, Retail, Tech, Telecom, Finance & Insurance, Fashion & Luxury, Beauty & Personal care, Sport, Travel, Gaming, Health & Pharma, Media & Entertainment, Public service & NGO, Home, FMCG (plain words work: \"cars\", \"banks\")" }, "market": { "type": "string", "description": "Country code: US, UK, FR, DE, BR, JP…" }, "language": { "type": "string", "description": "Spoken language code: en, es, fr…" }, "genre": { "type": "string", "description": "comedy, drama, documentary…" }, "structure": { "type": "string", "description": "narrative, montage, vignettes, problem_solution, demo…" }, "format": { "type": "string", "description": "live_action, animation_2d, animation_3d, stop_motion, cgi, motion_graphics, mixed" }, "tone": { "type": "string", "description": "funny, heartwarming, epic, emotional, absurd, dark, inspiring…" }, "trope": { "type": "string", "description": "A trope in plain words" }, "season": { "type": "string", "description": "A calendar moment: halloween, christmas, black friday, thanksgiving, new year, valentines, easter, mothers day, fathers day, back to school, summer, spring, pride, super bowl" }, "year_min": { "type": "integer", "description": "Spot year from" }, "year_max": { "type": "integer", "description": "Spot year to" }, "min_duration": { "type": "integer", "description": "Seconds" }, "max_duration": { "type": "integer", "description": "Seconds" }, "awarded": { "type": "boolean", "description": "true = won or was shortlisted at an award show" }, "award_show": { "type": "string", "description": "Award show", "enum": [ "Cannes Lions", "Clio Awards", "D&AD", "Epica", "AICP Awards", "London International Awards", "British Arrows", "The One Show", "El Ojo de Iberoamérica", "Eurobest", "Creative Circle", "Effie Awards", "Ciclope", "Spikes Asia", "ANDY Awards", "ADC Awards", "DGA Awards", "Kinsale Sharks", "shots Awards", "New York Festivals", "Webby Awards", "Emmy (Outstanding Commercial)", "IPA Effectiveness Awards", "AdFest", "Dubai Lynx", "ADC Europe", "Young Director Award" ] }, "min_award": { "type": "string", "description": "Best award at least this level", "enum": [ "grand_prix", "gold", "silver", "bronze", "shortlist" ] }, "award_year": { "type": "integer", "description": "Year of the award" }, "celebrity": { "type": "boolean", "description": "true = a recognizable person appears" }, "per_spot": { "type": "integer", "description": "Max shots from one commercial", "default": 2 }, "limit": { "type": "integer", "description": "1–50", "default": 20 }, "clips": { "type": "boolean", "description": "true = include each shot's clip_url — the call then costs 8 credits (image search stays 10)" } } }, { "method": "GET", "path": "/commercials/shots/:id", "description": "One shot: caption, tags, palette, still, timing and its commercial — and its clip with clips=true.", "cost": 2, "parameters": { "id": { "type": "string", "description": "Shot id (UUID)", "required": true }, "clips": { "type": "boolean", "description": "true = include each shot's clip_url — the call then costs 8 credits (image search stays 10)" } } }, { "method": "GET", "path": "/commercials/stats", "description": "How many commercials match a filter, broken down by up to 6 fields — e.g. which agencies won most at Cannes Lions for car ads since 2015: fields=agency&award_show=Cannes Lions&industry=Auto&year_min=2015. Fields: brand, director, agency, production, dp, editor, edit_house, post, music, sound, vfx, industry, market, language, year, genre, structure, format, tone, trope, award_show, award_year, season, collection.", "cost": 2, "parameters": { "fields": { "type": "string", "description": "Comma list", "required": true }, "brand": { "type": "string", "description": "Advertiser, e.g. \"Nike\". Comma-separate for several." }, "not_brand": { "type": "string", "description": "Leave these advertisers out" }, "director": { "type": "string", "description": "Credited director — a name" }, "agency": { "type": "string", "description": "Credited agency — a name" }, "production": { "type": "string", "description": "Credited production — a name" }, "dp": { "type": "string", "description": "Credited dp — a name" }, "editor": { "type": "string", "description": "Credited editor — a name" }, "edit_house": { "type": "string", "description": "Credited edit house — a name" }, "post": { "type": "string", "description": "Credited post — a name" }, "music": { "type": "string", "description": "Credited music — a name" }, "sound": { "type": "string", "description": "Credited sound — a name" }, "vfx": { "type": "string", "description": "Credited vfx — a name" }, "person": { "type": "string", "description": "Anyone credited, in any role" }, "industry": { "type": "string", "description": "Ad category: Auto, Beer, Spirits, Drinks, Food & QSR, Retail, Tech, Telecom, Finance & Insurance, Fashion & Luxury, Beauty & Personal care, Sport, Travel, Gaming, Health & Pharma, Media & Entertainment, Public service & NGO, Home, FMCG (plain words work: \"cars\", \"banks\")" }, "market": { "type": "string", "description": "Country code: US, UK, FR, DE, BR, JP…" }, "language": { "type": "string", "description": "Spoken language code: en, es, fr…" }, "genre": { "type": "string", "description": "comedy, drama, documentary…" }, "structure": { "type": "string", "description": "narrative, montage, vignettes, problem_solution, demo…" }, "format": { "type": "string", "description": "live_action, animation_2d, animation_3d, stop_motion, cgi, motion_graphics, mixed" }, "tone": { "type": "string", "description": "funny, heartwarming, epic, emotional, absurd, dark, inspiring…" }, "trope": { "type": "string", "description": "A trope in plain words" }, "season": { "type": "string", "description": "A calendar moment: halloween, christmas, black friday, thanksgiving, new year, valentines, easter, mothers day, fathers day, back to school, summer, spring, pride, super bowl" }, "year_min": { "type": "integer", "description": "Spot year from" }, "year_max": { "type": "integer", "description": "Spot year to" }, "min_duration": { "type": "integer", "description": "Seconds" }, "max_duration": { "type": "integer", "description": "Seconds" }, "awarded": { "type": "boolean", "description": "true = won or was shortlisted at an award show" }, "award_show": { "type": "string", "description": "Award show", "enum": [ "Cannes Lions", "Clio Awards", "D&AD", "Epica", "AICP Awards", "London International Awards", "British Arrows", "The One Show", "El Ojo de Iberoamérica", "Eurobest", "Creative Circle", "Effie Awards", "Ciclope", "Spikes Asia", "ANDY Awards", "ADC Awards", "DGA Awards", "Kinsale Sharks", "shots Awards", "New York Festivals", "Webby Awards", "Emmy (Outstanding Commercial)", "IPA Effectiveness Awards", "AdFest", "Dubai Lynx", "ADC Europe", "Young Director Award" ] }, "min_award": { "type": "string", "description": "Best award at least this level", "enum": [ "grand_prix", "gold", "silver", "bronze", "shortlist" ] }, "award_year": { "type": "integer", "description": "Year of the award" }, "celebrity": { "type": "boolean", "description": "true = a recognizable person appears" }, "limit": { "type": "integer", "description": "Rows per field, 1–100", "default": 15 } }, "example": { "fields": "agency,director", "award_show": "Cannes Lions", "industry": "Auto", "year_min": 2015 } }, { "method": "GET", "path": "/commercials/profile/:kind/:name", "description": "The track record of a brand, director, agency, production company, DP, editor, composer…: spots, years, per-year counts, who they work with, awards by show, tones and genres, best and most recent work. Directors, agencies and production companies with a public page also carry the researched profile (description, founded, HQ, website). An unknown name returns data:null with meta.did_you_mean.", "cost": 2, "parameters": { "kind": { "type": "string", "description": "brand | director | agency | production | dp | editor | edit_house | post | music | sound | vfx", "required": true }, "name": { "type": "string", "description": "URL-encoded name", "required": true } } }, { "method": "GET", "path": "/commercials/suggest", "description": "Typeahead over brands, directors, agencies, production companies, DPs, editors and music credits, ranked by number of spots. Free.", "cost": 0, "parameters": { "q": { "type": "string", "description": "At least 2 characters", "required": true }, "kind": { "type": "string", "description": "brand | director | agency | production | dp | editor | music" }, "limit": { "type": "integer", "description": "≤25", "default": 8 } } }, { "method": "GET", "path": "/commercials/vocabulary", "description": "The values that exist for every closed filter — industries, genres, structures, formats, tones, seasons, markets, languages, award shows, credit roles and the shot tags. Free; read it once and cache it.", "cost": 0, "parameters": {} } ] }, "animation": { "description": "The animation library: animated series and films (mostly anime, plus Western animation) — every frame of every title indexed with a caption of what is in it, plus look and colour fingerprints. Built for an AI-first creator whose model breaks a story into scenes: references per scene and per character (/animation/frames/search), more like a frame or ANY image by look, colour or content (/animation/frames/similar), which series and films fit the story (/animation/titles/search), one title in depth (/animation/titles/:slug), and a frame in its sequence (/animation/frames/:id/sequence). Stills are URLs — thumb_url (640px) to look at, still_url (full size) for the frames kept. Add clips: true to a frame call and each frame comes with its clip_url (run_url on a sequence), on every plan — that call costs 8 credits instead of 2 (an image call stays 10). Animation only — the film library is /search, /browse, /similar…", "endpoints": [ { "method": "POST", "also_as_get": true, "path": "/animation/frames/search", "description": "Frames from animated series and films (mostly anime, plus Western animation) for a scene, a moment or a CHARACTER LOOK in plain words (\"a girl on a rooftop at dusk watching the city lights\", \"a tall man with a scarred face and a long black coat, rain\") — the reference search for one scene or one character of a story. The query is expanded into the register the frames were captioned in and the candidates are reranked by reading each one; send enhance:false for the raw words. Narrow by title, genre, theme, style, studio, movie / series and year. At most 3 frames per title unless per_title says otherwise. Also as a GET with the same parameters.", "cost": 4, "parameters": { "query": { "type": "string", "description": "The scene, moment or character look in plain words, as a description of one frame", "required": true }, "title": { "type": "string", "description": "Only inside this series / film — a slug (\"akira-1988\") or a name (\"Your Name\"). An unknown name comes back in meta.warnings" }, "genre": { "type": "string", "description": "AniList genre: Action, Adventure, Comedy, Drama, Fantasy, Horror, Mecha, Mystery, Psychological, Romance, Sci-Fi, Slice of Life, Sports, Supernatural, Thriller… Comma = all of them" }, "theme": { "type": "string", "description": "AniList theme tag: Cyberpunk, Post-Apocalyptic, Iyashikei, Coming of Age, Time Travel, Magic, Space, Urban Fantasy…" }, "style": { "type": "string", "description": "The title's look, read off its frames — a closed list (GET /animation/vocabulary): hand-drawn cel, digital 2D, 3D CGI, cel-shaded 3D, stop motion, mixed 2D/3D, 70s look, 80s look, 90s look, 2000s look, modern look, pastel, muted, vivid, dark, warm, cool, monochrome, clean lines, thick outlines, sketchy lines, painterly, watercolour, flat minimal, detailed backgrounds, film grain, realistic proportions, moe big-eyed, chibi, western cartoon, gritty mature, bishonen, soft natural light, dramatic light rays, glow and bloom, neon, high-contrast shadows. Comma = all of them" }, "studio": { "type": "string", "description": "Animation studio, e.g. \"Studio Ghibli\", \"Madhouse\", \"Kyoto Animation\", \"MAPPA\"" }, "kind": { "type": "string", "description": "movie | series", "enum": [ "movie", "series" ] }, "year_min": { "type": "integer", "description": "Year from" }, "year_max": { "type": "integer", "description": "Year to" }, "exclude_titles": { "type": "array", "items": { "type": "string" }, "description": "Slugs to leave out (e.g. titles already used)" }, "nsfw": { "type": "boolean", "description": "false = leave out frames flagged as adult (they are included by default)" }, "per_title": { "type": "integer", "description": "Max frames from one title, 1–24 (ignored inside one title)", "default": 3 }, "limit": { "type": "integer", "description": "1–24", "default": 12 }, "offset": { "type": "integer", "description": "Paging offset, ≤200", "default": 0 }, "enhance": { "type": "boolean", "description": "Expand / rewrite the query first (default true); false = search the raw words" }, "clips": { "type": "boolean", "description": "true = include each frame's clip_url (and run_url on a sequence) — the call then costs 8 credits (an image call stays 10)" } }, "example": { "query": "a girl with short silver hair in a school uniform, standing in the rain", "style": "modern look", "limit": 12 } }, { "method": "POST", "path": "/animation/frames/similar", "description": "More frames like ones already found — frame ids from results (\"more like #2\") — or like ANY image: a generated frame on the canvas, an upload, a sketch (an http(s) URL or a data: URL). by = look (composition, drawing and rendering — the default), colour (the palette) or content (what is in it). Takes the title filters; other_titles: true keeps it to titles other than the seed frames'. Costs 2 credits with frame_ids, 10 with an image.", "cost": 2, "parameters": { "frame_ids": { "type": "array", "items": { "type": "string" }, "description": "1–10 frame ids from earlier results, or \"slug:label\"" }, "image": { "type": "string", "description": "Any image — an http(s) URL or a data: URL (e.g. data:image/png;base64,…). Give frame_ids or image" }, "by": { "type": "string", "description": "look | colour | content", "enum": [ "look", "colour", "content" ], "default": "look" }, "other_titles": { "type": "boolean", "description": "true = never from the seed frames' own titles (\"the same look, elsewhere\")" }, "title": { "type": "string", "description": "Only inside this series / film — a slug (\"akira-1988\") or a name (\"Your Name\"). An unknown name comes back in meta.warnings" }, "genre": { "type": "string", "description": "AniList genre: Action, Adventure, Comedy, Drama, Fantasy, Horror, Mecha, Mystery, Psychological, Romance, Sci-Fi, Slice of Life, Sports, Supernatural, Thriller… Comma = all of them" }, "theme": { "type": "string", "description": "AniList theme tag: Cyberpunk, Post-Apocalyptic, Iyashikei, Coming of Age, Time Travel, Magic, Space, Urban Fantasy…" }, "style": { "type": "string", "description": "The title's look, read off its frames — a closed list (GET /animation/vocabulary): hand-drawn cel, digital 2D, 3D CGI, cel-shaded 3D, stop motion, mixed 2D/3D, 70s look, 80s look, 90s look, 2000s look, modern look, pastel, muted, vivid, dark, warm, cool, monochrome, clean lines, thick outlines, sketchy lines, painterly, watercolour, flat minimal, detailed backgrounds, film grain, realistic proportions, moe big-eyed, chibi, western cartoon, gritty mature, bishonen, soft natural light, dramatic light rays, glow and bloom, neon, high-contrast shadows. Comma = all of them" }, "studio": { "type": "string", "description": "Animation studio, e.g. \"Studio Ghibli\", \"Madhouse\", \"Kyoto Animation\", \"MAPPA\"" }, "kind": { "type": "string", "description": "movie | series", "enum": [ "movie", "series" ] }, "year_min": { "type": "integer", "description": "Year from" }, "year_max": { "type": "integer", "description": "Year to" }, "exclude_titles": { "type": "array", "items": { "type": "string" }, "description": "Slugs to leave out (e.g. titles already used)" }, "nsfw": { "type": "boolean", "description": "false = leave out frames flagged as adult (they are included by default)" }, "per_title": { "type": "integer", "description": "Max frames from one title, 1–24", "default": 3 }, "limit": { "type": "integer", "description": "1–24", "default": 12 }, "clips": { "type": "boolean", "description": "true = include each frame's clip_url (and run_url on a sequence) — the call then costs 8 credits (an image call stays 10)" } }, "example": { "frame_ids": [ "akira-1988:0412" ], "by": "look", "other_titles": true, "limit": 12 } }, { "method": "POST", "also_as_get": true, "path": "/animation/titles/search", "description": "Which series and films fit what is being made — by a story brief in plain words (\"a quiet coming-of-age story about two sisters in a seaside town, bittersweet, summer\"), by a title it should be like, by a LOOK (an image or frame ids — titles whose frames look like it), and/or by the title filters alone. Signals combine. One card per franchise (its best entry), with the other entries under `also`; franchise: true keeps every entry. A look search names the frames that matched. Costs 2 credits, 10 with an image. Also as a GET with the same parameters.", "cost": 2, "parameters": { "brief": { "type": "string", "description": "The story, premise, mood or world in plain words" }, "like": { "type": "string", "description": "A title (name or slug) the results should be like in story" }, "image": { "type": "string", "description": "An http(s) or data: URL — titles that look like it" }, "frame_ids": { "type": "array", "items": { "type": "string" }, "description": "Up to 10 frame ids — titles that LOOK like them" }, "title": { "type": "string", "description": "Only inside this series / film — a slug (\"akira-1988\") or a name (\"Your Name\"). An unknown name comes back in meta.warnings" }, "genre": { "type": "string", "description": "AniList genre: Action, Adventure, Comedy, Drama, Fantasy, Horror, Mecha, Mystery, Psychological, Romance, Sci-Fi, Slice of Life, Sports, Supernatural, Thriller… Comma = all of them" }, "theme": { "type": "string", "description": "AniList theme tag: Cyberpunk, Post-Apocalyptic, Iyashikei, Coming of Age, Time Travel, Magic, Space, Urban Fantasy…" }, "style": { "type": "string", "description": "The title's look, read off its frames — a closed list (GET /animation/vocabulary): hand-drawn cel, digital 2D, 3D CGI, cel-shaded 3D, stop motion, mixed 2D/3D, 70s look, 80s look, 90s look, 2000s look, modern look, pastel, muted, vivid, dark, warm, cool, monochrome, clean lines, thick outlines, sketchy lines, painterly, watercolour, flat minimal, detailed backgrounds, film grain, realistic proportions, moe big-eyed, chibi, western cartoon, gritty mature, bishonen, soft natural light, dramatic light rays, glow and bloom, neon, high-contrast shadows. Comma = all of them" }, "studio": { "type": "string", "description": "Animation studio, e.g. \"Studio Ghibli\", \"Madhouse\", \"Kyoto Animation\", \"MAPPA\"" }, "kind": { "type": "string", "description": "movie | series", "enum": [ "movie", "series" ] }, "year_min": { "type": "integer", "description": "Year from" }, "year_max": { "type": "integer", "description": "Year to" }, "exclude_titles": { "type": "array", "items": { "type": "string" }, "description": "Slugs to leave out (e.g. titles already used)" }, "nsfw": { "type": "boolean", "description": "false = leave out frames flagged as adult (they are included by default)" }, "franchise": { "type": "boolean", "description": "true = keep every entry of a franchise (default: one card per franchise, the others under `also`)" }, "limit": { "type": "integer", "description": "1–20", "default": 8 }, "clips": { "type": "boolean", "description": "true = include each frame's clip_url (and run_url on a sequence) — the call then costs 8 credits (an image call stays 10)" } }, "example": { "brief": "a quiet coming-of-age story about two sisters in a seaside town, bittersweet, summer", "kind": "movie", "limit": 8 } }, { "method": "GET", "path": "/animation/titles/:slug", "description": "One series or film in depth, by slug or name: synopsis, studio and key credits, main characters, genres, themes, its look and style tags, the trailer, how many shots are indexed, titles with a similar look and a similar story, and sample frames spread across it.", "cost": 2, "parameters": { "slug": { "type": "string", "description": "Title slug (or name, URL-encoded), e.g. akira-1988", "required": true }, "frames": { "type": "integer", "description": "Sample frames, 0–24", "default": 6 }, "clips": { "type": "boolean", "description": "true = include each frame's clip_url (and run_url on a sequence) — the call then costs 8 credits (an image call stays 10)" } } }, { "method": "GET", "path": "/animation/frames/:id/sequence", "description": "A frame in context: the shots just before and after it in the same episode / film, in film order, each with its still and caption (the anchor carries anchor: true) — to see how a moment is built, or to lay a beat out across canvas panels. The library keeps picked shots, not every shot: gap_before_sec is the film time skipped since the previous one. With clips=true each shot's clip, plus `runs` — the continuous video that covers them (run_url, from_sec / to_sec).", "cost": 2, "parameters": { "id": { "type": "string", "description": "A frame id from results, or \"slug:label\"", "required": true }, "before": { "type": "integer", "description": "Shots before it, 0–8", "default": 2 }, "after": { "type": "integer", "description": "Shots after it, 0–8", "default": 2 }, "clips": { "type": "boolean", "description": "true = include each frame's clip_url (and run_url on a sequence) — the call then costs 8 credits (an image call stays 10)" } } }, { "method": "GET", "path": "/animation/vocabulary", "description": "The values the filters accept, with title counts — genres, themes, styles (and style_groups: medium, era, palette, rendering, characters, light), studios and kinds — plus the similar-frame modes. Free; read it once and cache it.", "cost": 0, "parameters": {} } ], "response_fields": { "frame": { "id": "Frame id — pass it to /frames/similar, /frames/:id/sequence or frame_ids", "title": "Series / film title", "slug": "Title slug", "year": "Year", "kind": "movie | series", "episode": "Episode number (series)", "label": "The frame's label inside its title (\"slug:label\" is also an id)", "caption": "What is in the frame", "setting": "Where", "action": "What happens", "thumb_url": "640px WebP (~13 KB) — what an LLM or a canvas tile should load", "still_url": "The full-size master still", "clip_url": "The shot's clip — only with clips=true", "url": "The frame on FrameThrower", "score": "Match score", "nsfw": "true = flagged as adult" }, "title": { "slug": "Title slug", "title": "Title", "year": "Year", "kind": "movie | series", "format": "TV, MOVIE, OVA…", "episodes": "Episode count (series)", "genres": "Genres", "themes": "Theme tags", "studios": "Studios", "director": "Director", "look": "One sentence on how it looks", "styles": "Style tags (the closed style list)", "synopsis": "Synopsis (shortened in lists, whole on /titles/:slug)", "poster_url": "Poster", "frames": "Frames indexed", "url": "The title on FrameThrower", "score": "Match score (searches)", "also": "Other entries of the same franchise (titles/search)", "matched_frames": "Frames that matched a look search" } } }, "response_format": { "description": "All responses return { data, meta }. Frames include: id, imageUrl (full-size), thumbUrl (1280px WebP thumbnail), deepLink (opens on FrameThrower), film (title, year, director, dp, genres), metadata (scene description, shot type, camera angle, lens, lighting, moods, colors). Frame detail also includes prompt (composed AI image prompt).", "errors": "{ \"error\": \"message\" } with HTTP status 400/401/403/404/500." }, "use_cases": [ "Script → visual references: search by scene description, then find similar frames to refine", "Color palette matching: pass brand colors or mood hex values to find matching cinematography", "Cinematography study: browse by craft attributes (anamorphic, low-key, overhead) across directors", "Moodboard building: combine search + similar + color to curate a visual reference set", "AI image prompts: get the prompt field from frame detail to use as generation input" ] }