Connector recipes

Connector recipes answer: what do I actually ask, and what comes back? These are the asks the connector was built for. Each one shows the natural-language request, the tools it triggers, and an abbreviated version of the payload. Set up first: The connector. Full signatures for all thirty-eight tools: Connector API.

Every payload below is illustrative and cut down to the fields that matter. Job ids are placeholders, and frame URLs are signed and short-lived, so they are shown as <signed frame URL> rather than pasted.

1. Open the cut index

Show me the cuts in the manifesto spot I analyzed yesterday.

Two calls, both free. list_analyses resolves the title you used into a job_id, then list_cuts returns the index.

list_analyses()
list_cuts("EXAMPLE_JOB_ID")

{
  "job_id": "EXAMPLE_JOB_ID",
  "cuts_built": true,
  "count": 31,
  "cuts": [
    { "cut_number": 1, "technique_id": "cut-001",
      "title": "Cold Open On Hands, No Face",
      "duration_s": 2.4,
      "desc": "Tight close-up on hands counting cash, no establishing shot",
      "first_frame_url": "<signed frame URL>",
      "last_frame_url": "<signed frame URL>",
      "thumb": "<signed frame URL>" },
    { "cut_number": 2, "technique_id": "cut-002",
      "title": "Whip Pan Into Interior", "duration_s": 0.9, "desc": "..." },
    { "cut_number": 3, "technique_id": "cut-003",
      "title": "Intimate Static Two-Shot Bonding Frame", "duration_s": 3.8, "desc": "..." }
    // ... 28 more
  ],
  "note": "Call get_cut(job_id, cut_number) to inspect one cut."
}

This is a menu, not a report. No transcripts, no full frame arrays, no brief content — so your assistant can open it freely on every turn. It reads back as a numbered list you can point at. Why this matters: the index is what turns a 31-cut teardown into 31 addressable pieces of work. Instead of loading a whole analysis into context to talk about one shot, your assistant loads the menu and then loads one cut.

2. Inspect one cut, free

Tell me about cut 3.

get_cut("EXAMPLE_JOB_ID", 3)

{
  "job_id": "EXAMPLE_JOB_ID",
  "cut_number": 3,
  "technique_id": "cut-003",
  "title": "Intimate Static Two-Shot Bonding Frame",
  "desc": "Two subjects share a locked-off medium frame; the emotional beat lands on a held pause",
  "clip_url": "<signed clip URL — the cut MP4 itself, short-lived (~15 min): fetch it promptly, never store it>",
  "frames": [
    "<signed frame URL>", "<signed frame URL>", "<signed frame URL>",
    "<signed frame URL>", "<signed frame URL>"
  ],
  "timing": { "duration_s": 3.8, "start_s": 11.2, "end_s": 15.0 },
  "on_screen_text": ["Break the cycle"],
  "motion_camera": ["medium two-shot · static", "medium two-shot · slow push-in"],
  "scene_classes": ["narrative_beat"]
}

Free, and it stays free no matter how many cuts you inspect. What you get is the source facts: up to 8 keyframes, real timing read from the footage, the on-screen text, the camera and motion signals, and how the scene was classified. What you do not get is a build spec. get_cut never returns or reconstructs one, so browsing cuts can never quietly turn into a charge. cut-003 works exactly like 3:

get_cut("EXAMPLE_JOB_ID", "cut-003")

3. Get the build spec for one cut

Get me the build spec for cut 3, I want to remake it with my own footage.

get_cut_brief("EXAMPLE_JOB_ID", 3)

This is the credit event: a Cut Blueprint that has not been built yet spends credits (the response states the amount). Re-opening it is free. It is the only per-cut call that spends.

{
  "job_id": "EXAMPLE_JOB_ID",
  "cut_number": 3,
  "technique_id": "cut-003",
  "title": "Intimate Static Two-Shot Bonding Frame",
  "cached": false,
  "charged": "<credits>",
  "build_spec": {
    "group_prompt": "Locked-off medium two-shot, 50mm equivalent, eye level, subjects at equal frame weight; warm low-key practicals, shallow falloff, no camera movement so the performance carries the beat. Swap in [YOUR SUBJECT] …",
    "frames": [
      { "frame_number": 1,
        "timestamp": "0:11",
        "duration_s": 1.6,
        "image_prompt": "Medium two-shot of [YOUR SUBJECT] pair seated at a table, eye level, 50mm, warm practical lamp off-frame left, shallow depth of field …",
        "video_prompt": "Camera static. Motion: micro only - a slow shoulder settle and one blink. Duration 1.6s. No push, no handheld drift.",
        "camera_motion": "locked off, eye level, 50mm equivalent",
        "transition_to_next": "straight cut on the head turn" },
      { "frame_number": 2, "timestamp": "0:13", "duration_s": 2.2, "image_prompt": "…" }
    ],
    "direction": {
      "how_they_did_it": "The cut earns its length by refusing coverage. One frame, no movement, and the edit holds two beats past comfortable …",
      "build_steps": "1. Block both subjects at equal distance from lens. 2. Light with one warm practical plus negative fill …",
      "swap_note": "Replace the subjects, wardrobe, and set. Keep the locked-off frame, the equal weighting, and the held pause - those are the mechanism.",
      "difficulty": "moderate",
      "aspect_ratio": "9:16",
      "consistency": "Same lens and lamp position across every frame in this cut",
      "sound": "Room tone only under the dialogue; music drops out for the pause",
      "animation_notes": "None - live action",
      "estimated_duration_s": 4,
      "use_cases": ["Founder story beat", "Testimonial mid-section"]
    },
    "timing": {
      "pacing": "Two held beats against a fast surrounding montage",
      "key_visual_elements": ["equal frame weight", "warm practical", "held pause"]
    }
  },
  "reference_note": "Study the mechanism, then shoot it with your own subjects and footage."
}

Ask for the same cut again and it re-opens for nothing:

{ "cut_number": 3, "cached": true, "charged": 0,
  "build_spec": { /* ... */ } }

If the brief is still being built when you ask, you get the honest interim state rather than a stall, and re-calling with the same cut retrieves the saved brief:

{ "job_id": "EXAMPLE_JOB_ID", "cut_number": 3, "technique_id": "cut-003",
  "status": "running",
  "note": "Re-call get_cut_brief with the same cut to retrieve the saved brief." }

Read charged and credit_status rather than assuming. They come from the server, which is the only authority on what your account was charged. The agentic unlock: cut index, then one cut, then one brief. Your assistant works a shot at a time, you spend on the shots you decide to remake, and the reference stays a reference - the footage is yours.

4. Compare hooks across several teardowns

Across my last three teardowns, what do the hooks have in common?

list_analyses()
get_context_bundle(["EXAMPLE_JOB_ID_1", "EXAMPLE_JOB_ID_2", "EXAMPLE_JOB_ID_3"],
                   preset="hooks_only")

Free, and one call instead of three reports. hooks_only returns openings and scorecards, nothing else - no transcripts, no beat sheets.

{
  "preset": "hooks_only",
  "requested": 3,
  "included": 3,
  "truncated": false,
  "items": [
    { "id": "EXAMPLE_JOB_ID_1", "owned": true,
      "title": "Reference A - manifesto spot",
      "hook_type": "cold_open_visual",
      "hook": "Opens on hands counting cash before a single word is spoken",
      "opening_beats": [
        "0:00 · cold_open — hands counting cash",
        "0:02 · narrative_beat — subject looks up · text:\"Break the cycle\"",
        "0:05 · talking_head — subject mid-frame"
      ],
      "scorecard": { "overall": 7.4, "verdict": "Strong open, soft close",
                     "top_moves": ["Hook · first 3s 9/10 — visual before language"] },
      "assets": { "thumb_url": "<signed frame URL>",
                  "keyframe_urls": ["<signed frame URL>", "<signed frame URL>"] } },
    { "id": "EXAMPLE_JOB_ID_2", "owned": true, "hook_type": "question_open", "hook": "..." },
    { "id": "EXAMPLE_JOB_ID_3", "owned": true, "hook_type": "cold_open_visual", "hook": "..." }
  ]
}

Your assistant does the comparing from there: two of the three open on image before language, the third opens on a question, and the scorecards say which one held. If you want the comparison computed rather than inferred, ask for the same set as a synthesis bundle. That preset adds a pattern layer built from structure, not from a model’s opinion:

{
  "preset": "synthesis",
  "pattern_layer": {
    "videos_merged": 3,
    "common_beats": [
      { "scene_type": "cold_open", "in_videos": "3/3", "avg_position_pct": 2 },
      { "scene_type": "problem_setup", "in_videos": "2/3", "avg_position_pct": 14 }
    ],
    "divergent_hooks": [
      { "id": "EXAMPLE_JOB_ID_1", "title": "Reference A - manifesto spot",
        "hook_type": "cold_open_visual", "hook": "...", "hook_score": 9 },
      { "id": "EXAMPLE_JOB_ID_2", "title": "Reference B - founder story",
        "hook_type": "question_open", "hook": "...", "hook_score": 6 }
    ],
    "shared_voice_traits": { "gender": "male", "pace": "fast", "energy_level": "high" }
  },
  "videos": [ /* thin per-video refs, no transcripts */ ]
}

Bundles cap at ten analyses. Ask for more and the extras are dropped with truncated: true and a note saying how many, so a silent trim never happens.

Presets by intent: hooks_only for openings across N videos, synthesis for the merged pattern layer across N, remix for a deep single-video payload - beats, pacing, style, voice, transcript, and per-scene prompts with [YOUR PRODUCT] placeholders.

5. Analyze something new, then write from it

Analyze this video, then write me a 60-second script in the same structure for my product.

analyze_video("https://youtu.be/EXAMPLE", label="Competitor launch film")
get_report("EXAMPLE_JOB_ID", preset="full")

analyze_video draws on your plan exactly like a new teardown in the app, and returns a job_id right away. Analyses usually finish in about 90 seconds. Hosted get_report polls for at most 36 seconds and returns successful progress in under a minute if the breakdown is still running. It preserves the raw progress, adds an approximate percentage when available, and says to ask again in a minute. Call get_report again with the same job ID until it returns status: "complete", then write from the breakdown. Hosted wait=False and get_status each make one read bounded to 8 seconds. The local connector keeps its configurable 300-second polling cap with wait=True, plus the existing 90-second request timeout; the final request can extend past the cap. Better habit: preset="lean" first, then pull only what you need.

get_report("EXAMPLE_JOB_ID", fields=["beats", "transcript", "scorecard"])

The lean response lists the field names available for that analysis, so your assistant can pick without guessing.

When something is off

These are the honest failure shapes. Each one is self-correcting: it tells your assistant what to do next instead of returning an opaque error.

What you asked	What comes back
A cut on an analysis whose cuts were never built	`cuts_built: false` with a `recovery` block naming `build_cuts` - call it (0 credits), then poll `list_cuts` until `cuts_built: true`
Cut 40 of a 31-cut analysis	An error carrying `valid_cut_numbers` and `valid_technique_ids`
An analysis another account owns	`owned: false` with a preview only - title, thumbnail, hook type, duration - plus an `add_to_library` block naming the source URL and the credit cost. It is never analyzed for you
A bundle including an analysis that is still running	That id lands in `unavailable` with its status; the rest of the bundle still comes back
Anything, with no key configured	An error telling you to generate a key at Account → API access
Anything, with a key whose plan no longer includes API access	Unauthorized on every call. The key is suspended, not deleted; upgrading reactivates the same key

The connector

Install, the thirty-eight tools, credits, and troubleshooting.

Connector API

Signatures, params, charges, and measured response sizes for all 38 tools.

The Cuts

How cuts are detected and what a Cut Blueprint contains.

For your AI

The copy-paste handoff, without the connector.

Getting Started

Running Teardowns

The Analysis, Layer by Layer

Cast, Assets & Extractor

Your Library

Recipe & Workflow

Extension & Agents

Billing, Account & Legal

1. Open the cut index

2. Inspect one cut, free

3. Get the build spec for one cut

4. Compare hooks across several teardowns

5. Analyze something new, then write from it

When something is off

The connector

Connector API

The Cuts

For your AI

​1. Open the cut index

​2. Inspect one cut, free

​3. Get the build spec for one cut

​4. Compare hooks across several teardowns

​5. Analyze something new, then write from it

​When something is off

​Related pages

The connector

Connector API

The Cuts

For your AI

1. Open the cut index

2. Inspect one cut, free

3. Get the build spec for one cut

4. Compare hooks across several teardowns

5. Analyze something new, then write from it

When something is off

Related pages