> ## Documentation Index > Fetch the complete documentation index at: https://docs.videngineer.com/llms.txt > Use this file to discover all available pages before exploring further. # Connector recipes > Real asks for the videngineer connector: the tools each one triggers, the shape of what comes back, and what it costs. 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](/agents/mcp-connector). Full signatures for all **twenty-one** tools: [Connector API](/agents/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 `` 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. ```text theme={null} list_analyses() list_cuts("EXAMPLE_JOB_ID") ``` ```jsonc theme={null} { "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": "", "last_frame_url": "", "thumb": "" }, { "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. ```text theme={null} get_cut("EXAMPLE_JOB_ID", 3) ``` ```jsonc theme={null} { "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": "", "frames": [ "", "", "", "", "" ], "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"], "next_step": "Call get_cut_brief(job_id, cut) for the credit-gated recreation build-spec." } ``` 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`: ```text theme={null} 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. ```text theme={null} get_cut_brief("EXAMPLE_JOB_ID", 3) ``` This is the credit event: **2 credits** for a Cut Blueprint that has not been generated yet. It is the only per-cut call that spends. ```jsonc theme={null} { "job_id": "EXAMPLE_JOB_ID", "cut_number": 3, "technique_id": "cut-003", "title": "Intimate Static Two-Shot Bonding Frame", "cached": false, "charged": 2, "credit_status": "generated, 2 credits charged", "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: ```jsonc theme={null} { "cut_number": 3, "cached": true, "charged": 0, "credit_status": "already generated — re-opened free", "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: ```jsonc theme={null} { "job_id": "EXAMPLE_JOB_ID", "cut_number": 3, "technique_id": "cut-003", "status": "running", "credit_status": "generation started — credit outcome pending", "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? ```text theme={null} 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. ```jsonc theme={null} { "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": "", "keyframe_urls": ["", ""] } }, { "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: ```jsonc theme={null} { "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 recreation prompts with `[YOUR PRODUCT]` placeholders, ready to paste into your own image or video tool. ## 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. ```text theme={null} 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. `get_report` polls until the analysis completes - usually about 90 seconds - then returns the full breakdown for your assistant to write from. Pass `wait=False` if you would rather it return the current status immediately and check back. Better habit: `preset="lean"` first, then pull only what you need. ```text theme={null} 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 | ## Related pages Install, the twenty-one tools, credits, and troubleshooting. Signatures, params, charges, and measured response sizes for all 19 tools. How cuts are detected and what a Cut Blueprint contains. The copy-paste handoff, without the connector.