Ad Creative → Shot Spec

Reverse-engineer any video ad into a per-shot reconstruction spec — camera, lighting, color grade, composition, and a ready-to-paste generation prompt for Veo, Kling, Runway, or Seedance.

Most "video → prompt" tools give you one vague paragraph. This one decodes the video shot by shot and outputs a structured spec built for one thing: rebuilding the ad on your own product, on any AI video engine.

Why it's near-free to run

You bring your own API key — Google Gemini, OpenAI, or Anthropic. The vision analysis is billed directly to you by the provider, so there's no markup and no per-image tax hidden in a subscription. Frames are downscaled to 512px before analysis, cutting your vision-token bill several-fold.

No key yet? Google Gemini gives a genuinely free API key with no credit card at aistudio.google.com/apikey — the actor defaults to Gemini. Test the whole thing for $0.

What you get — one row per shot

Field
subject, action	what's on screen, staged as reproducible direction
cameraMovement, cameraAngle, lensLook	how it's shot
lighting, colorGrade, composition, pacing	the look, each with a confidence read
onScreenText	verbatim captions/hooks
engineFeasibility	can current engines actually reproduce this shot? (yes / partial / no)
reproducibilityRisk	the one hardest thing to reproduce, flagged in advance
generationPrompt	model-agnostic creative core
modelPrompt	the above, tuned to your targetModel
confidenceFlags	fields to eyeball — we tell you what we're unsure of

Reconstruction, not scoring. Other actors critique an ad. This one tells you how to remake it — honestly, including what will fail.

Input

• videoUrls — direct MP4 URLs, or
• datasetId — pipe in the output of any ad-library scraper; we auto-detect the video URL field
• provider + apiKey (your key, marked secret) · targetModel · maxScenes (cost cap) · maxDuration

Chain it with an ad-library scraper

1. Run an ad-library scraper actor → get its dataset ID
2. Paste that ID into datasetId here
3. Get a shot spec for every ad in the batch

Pricing

Pay-per-event, not compute-time:

• $0.05 per shot row — one fully-decoded shot with camera, lighting, grade, composition, on-screen text, feasibility, and a ready-to-paste generation prompt.
• $0.002 per skipped input — a categorised error row when a source can't be analyzed.

You pay your LLM provider separately for the vision calls (a few cents per shot, or free on Gemini's free tier). Comparable "scraper" actors charge $1–3 per 1,000 rows for plain text extraction — this does real per-shot video decode and structured film analysis, which is why it's priced above that band.

---

Run locally first (recommended before you spend)

pip install -r requirements.txt          # needs ffmpeg on PATH
set OPENAI_API_KEY=sk-...
python test_local.py path/to/ad.mp4 --provider openai --target kling

Outputs test_output.json — one object per shot.

Notes / limits

• Legible small text and logos can't be generated by any engine — the spec flags this; composite branding in post.
• Motion, camera movement, and pacing are inferred from a representative still and marked with confidence — not fabricated as fact.
• generationPrompt is deliberately model-agnostic so it survives any single engine's deprecation; modelPrompt is a formatting layer on top.