# Ad Creative → Shot Spec (`akki.1008/ad-creative-shot-spec`) Actor

Turn any video ad into a per-shot reconstruction spec — camera, lighting, grade, composition, on-screen text, and a ready-to-paste prompt for Veo, Kling, Runway & Sora. Reconstruction, not scoring. Bring your own LLM key; runs for pennies.

- **URL**: https://apify.com/akki.1008/ad-creative-shot-spec.md
- **Developed by:** [Akshay Kumar](https://apify.com/akki.1008) (community)
- **Categories:** AI, Videos
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $50.00 / 1,000 shot specs

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## 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](https://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)

```bash
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.

# Actor input Schema

## `videoUrls` (type: `array`):

Direct MP4 (or mov/webm) URLs to analyze. Leave empty if piping in a dataset from an ad-library scraper instead.

## `datasetId` (type: `string`):

Apify dataset ID from any ad-library scraper. Each item is scanned for a video URL field (videoUrl, video\_url, mediaUrl, url).

## `datasetVideoField` (type: `string`):

Which field in the source dataset holds the direct video URL. Auto-detects common names if left blank.

## `provider` (type: `string`):

Which vision model provider your API key is for.

## `apiKey` (type: `string`):

Your own API key, billed directly to you by the provider — never stored, never seen by us. Google Gemini offers a FREE key at aistudio.google.com with no card required.

## `model` (type: `string`):

Override the vision model. Defaults: OpenAI = gpt-4o, Anthropic = claude-3-5-sonnet-latest.

## `targetModel` (type: `string`):

The generation engine you'll paste prompts into. Adds an engine-tuned modelPrompt alongside the model-agnostic generationPrompt.

## `maxScenes` (type: `integer`):

Cap on shots analyzed per video (= number of vision calls = your LLM cost). Near-duplicate scenes are collapsed.

## `maxDuration` (type: `integer`):

Videos longer than this are skipped with an error row rather than run up your bill.

## `sceneThreshold` (type: `number`):

ffmpeg scene score threshold (0.2 = many cuts, 0.4 = only hard cuts). 0.3 is a good default for ads.

## Actor input object example

```json
{
  "videoUrls": [],
  "provider": "gemini",
  "targetModel": "generic",
  "maxScenes": 5,
  "maxDuration": 60,
  "sceneThreshold": 0.3
}
```

# Actor output Schema

## `shots` (type: `string`):

One row per shot: camera, lighting, colour grade, composition, on-screen text, engine feasibility, and a ready-to-paste generation prompt for Veo / Kling / Runway / Seedance.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "videoUrls": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("akki.1008/ad-creative-shot-spec").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "videoUrls": [] }

# Run the Actor and wait for it to finish
run = client.actor("akki.1008/ad-creative-shot-spec").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "videoUrls": []
}' |
apify call akki.1008/ad-creative-shot-spec --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,akki.1008/ad-creative-shot-spec"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/sWBJnpj2EJ7MJhOhc/builds/AGnzXO16NZ1BCe4aF/openapi.json