Tool reference
by the PREVIZ team
102 tools, generated from the same registry the server answers tools/list from, so this list cannot drift from the door.
Read
Projects, boards, the scene graph, locked identities, drift, provenance, footage, meshes and the look vocabulary. Free, exact, nothing inferred.
list_projectsList projects · read · free- List the projects this caller can reach — the person's own, and those shared with them or their organisation — with the role held on each (a viewer or commenter can read; an editor or above can also write and spend). Free, <300 ms.
get_boardSummarize a board · read · free- Summarize a project's Infinitum board: how many frames, clips, audio and notes it holds, what is still rendering, and which locked identities ride on it. Free, <300 ms.
board_queryQuery the board · read · free- An exact index over the board — no model inside, you are the mind. Filter shapes by kind, lane, lock, look, engine, drift verdict, lineage or text and get compact rows with ids to act on. verdict reads the recorded continuity checks (pass|warn|fail|unchecked; with lockName, for that lock). look matches the prompt text because the board records no look field. Free, <300 ms.
scene_graphRead the scene graph · read · free- The board as a graph: nodes (assets, locks, lanes, notes, groups, docs) and typed edges — madeFrom (lineage), holds (lock → frame it rode on), anchoredBy (lock → its anchor card), inLane, inGroup, connector, driftedFrom (frame → lock, with the recorded verdict and score). The lineage DAG the inspector draws, as JSON a pipeline TD or a Blender collection builder can walk. Free, <300 ms; truncated:true past 2000 nodes.
list_identitiesList locked identities · read · free- The project's locked identities (continuity banks): every character/model, object/garment and location/set held faithful across renders, with its anchor description and — when the lock has an anchor card — its anchorImageUrl and anchorShapeId. A lock WITH an anchor image rides into renders as a reference; one without rides as text. Free, <300 ms.
provenance_reportRead provenance · read · free- Per-asset provenance for a project's board: engine, credits spent, render time, ancestry and locked identities for each finished asset — the chain-of-custody record. Free, <300 ms.
read_driftRead drift · read · free- The drift meter as a verb. method 'embedding' (default): cosine between the cached image embeddings of a and b — 'looks alike', NOT identity — via the platform's embedding lane; cached vectors cost nothing, a fresh one is a written read of the picture embedded as text (a few seconds) and no credits; both images must be this project's own (board cards, renders, plates). method 'checklist': the RECORDED closed-loop verdict (identity/styling/palette scores, pass|warn|fail, supervisor note) for frame b against lock a, written when b rendered with the lock riding — free, exact, and absent when no such render happened (this mode never runs a judge). a: url | shapeId | lockName. b: url | shapeId. Shot to shot across a cut: check_cut_continuity (free) and judge_cut_continuity read every cut pair.
plan_quotePrice a plan · read · free- Price a whole plan before anything runs, and learn which steps this project's engine policy would REFUSE. steps are {tool, args} pairs for any generating tool here (generate_frame, edit_frame, animate_frame, render_cut, generate_mesh, estimate_depth, decompose_frame, inpaint_frame, relight_frame; free tools price 0). Each step's number is computed by the same quote path its tool uses, so the plan's total is the number the charges will read; policy is the same rule the lanes enforce, dry-run without spending. Returns per-step {credits, policy}, total, keyBudget and wouldExceedBudget. Free, <500 ms.
list_footageList footage · read · free- WHERE ARE MY VIDEOS: the project's finished footage, newest first — every frame and take on its Infinitum board, PLUS every finished take that is not on the board (onBoard:false, e.g. takes rendered through this door before 29 Sep 2026). Each item has its file url and an openUrl that opens the board on it (an off-board take is landed on the board when opened). Free.
list_looksList looks · read · free- The platform's look-profile vocabulary — every named look a frame can be rendered in (directors, periods, genres), by the names the studio's picker shows. Pass a look's name as `look` on generate_frame / edit_frame / animate_frame (ids from earlier answers still resolve). Free.
get_shot_sheetRead a shot sheet · read · free- A frame's camera as numbers — lens_mm, sensor_mm (36), height_m, pitch_deg, azimuth_deg, distance_m — with the evidentiary GRADE: 'recorded' when the shape carries the camera the studio stored with it at generation time (its `basis` — orbit-studio, camera-rig, cineforge — is returned verbatim, with recordedAt); 'derived' when the numbers were computed and say so; 'unknown' when nothing was measured (36 mm sensor, no lens claim). The frame URL and ratio are always returned so a Blender camera can still be built as a start. Frames generated before cameras were recorded answer 'unknown'. Free, <300 ms.
list_meshesList meshes · read · free- The project's 3D meshes, newest first: every text→3D and image→3D generation with its glb URL, source lane, status, credits and engine (the capability that made it — never a vendor's model). Free, <300 ms.
get_accountRead this connection's access · read · free- What this credential may do: how it signed in, its scopes, the projects it is limited to, its monthly credit cap and this month's spend through it, its live spending agreement's remaining budget and expiry, how many projects it reaches, until when a deprecated confirm:true still runs, its call-rate and parallel-run limits, the calls it has left right now, the paid runs it holds in flight, each engine lane's own per-minute pace, and — the one answer a frozen credential still gets — whether it is frozen and where a person lifts it. Free, <300 ms.
get_engine_policyRead the engine policy · read · free- The engine policy in force on a project — the contract every generating tool and every production runs under: whether it is restricted, the jurisdiction classes it allows (null: any), how many engine companies it excludes by name (never which), whether an engine of unknown jurisdiction may run, its label, where it comes from (the organisation's ceiling, its default, the project's own row, your personal default) layer by layer, and its fingerprint. Every quote token, approval and job is bound to that fingerprint: if it changes, a quote you hold comes back QUOTE_STALE. Only a person changes a policy, in PREVIZ. Free, <300 ms.
explain_routeExplain where a call would run · read · free- Before anything runs: which capability a call would use, engine by engine in the order it would try them, the jurisdiction class of each, which may run, which this project's engine policy excludes and why, and which your constraints would exclude — plus the price of the call and of each alternative the arguments could select (another tier's lane). Pass op (any paid tool's name), its args exactly as you would send them, and optionally constraints ({jurisdiction, noTrainingUse}). verdict says whether the call would run, be refused by the policy, or be refused by your constraints. Names classes and positions, never an engine or the company behind it. Nothing runs and nothing is charged. Free, <500 ms.
list_voicesList voices to cast · read · free- The voices a character can be cast to: PREVIZ's stock voices (each with the read it suits) and the person's own voices made in PREVIZ whose consent is on record and current. Each has an opaque id for cast_voice, convert_voice and speak_line. Voices are made and consented to only by the person in PREVIZ — never through this door. Free, <1 s.
get_castRead the project's cast · read · free- The project's cast of voices: each character and the voice locked to them — the same cast the studio's audio rooms read, so a line spoken anywhere in PREVIZ for that character is that voice. setBy says whether this credential's person set it. Free, <1 s.
brain_searchSearch project memory · read · free- Search everything PREVIZ remembers about a project, across every room: scenes, shots, frames, takes, sets, board cards, sounds and files people handed over. Answers the best matches with the room each came from, its kind, its caption and where it lives. Says whether the search was by meaning or by keyword only (a project whose engine policy excludes the embedding engine is searched by keyword). Free.
brain_contextRead the project's memory · read · free- The project's memory as one briefing, the same one PREVIZ's own planners read: the cast, props and places that matter, the decisions in force with their versions, the work that best matches your question across every room, what is stale, what drifted and what is approved. Pass a query to rank it for a task; pass none for the project at a glance. Free.
ask_brainAsk project memory · read · free- Ask a question about a project and get a short answer from its memory and nothing else: what was decided and at which version, what exists, what is happening now. It says so plainly when the memory holds no answer. The person's own hourly ceiling on questions applies; a project whose engine policy leaves no engine to answer is refused (brain_context still reads). Free.
list_decisionsList decisions in force · read · free- The decisions that hold in a project: each lock, look, frame, rule, palette and camera decision with its version, what it is about and when it was decided. A decision is never edited: a change is a new version that supersedes the last (includeSuperseded lists the chain). Free, <300 ms.
get_entityRead an entity · read · free- One character, prop, place, wardrobe, vehicle or look as the project's memory holds it: its sheet, its reference images, whether it is locked, and every version of its lock with the reference image each version was locked with. Name it by id or by name; pass version to read it as it was locked then. Free, <300 ms.
stale_sinceList what went stale · read · free- What a changed decision left behind: every frame, take, set and card made under a version that has since been superseded, in every room, each with the version it was made under and the one in force now. Pass decisionId (either version) for one decision's work, or none for the whole project. Work re-made under the version in force is not listed. replay_stale prices re-shooting it. Free.
check_continuityCheck a frame against a lock · read · free- Is this frame still the character, prop or place as locked? Compares a project image with the reference image a lock version was locked with and answers pass, fail or unjudged, with the similarity it read and every verdict already recorded for that frame. It never guesses: a likeness in the middle band, a low score for a character or prop (which cannot tell a different person from a different scene), a version locked without a reference image, or an engine policy that excludes the read all answer unjudged, never pass. Free.
plan_chainPrice a chain · read · free- Check and price a chain before anything runs. A chain is a pipeline written as data: steps, each one a tool call, where a step's arguments may take an earlier step's output with {"$from": "stepId.output"}. Chainable tools and what each hands on: generate_frame (image), edit_frame (image), inpaint_frame (image), relight_frame (image), estimate_depth (depth), split_plate (plate, subject), animate_frame (take, video), render_cut (video), speak_line (audio), convert_voice (audio, video), generate_sfx (audio), generate_music (audio). A take's outputs are there once the take has finished. PREVIZ refuses a chain with a circle in it, more than 24 steps, steps more than 8 deep, more than 6 that could run at once or that wait on one step, a tool that is not chainable (with the reason), or a step it cannot price up front. Each step's number comes from that tool's own quote, so the total is the most the chain can cost; each step is also checked against this project's engine policy and your constraints. Returns the steps in the order they would run, the total, and every refusal by step. Free; nothing runs.
get_scriptRead the script · read · free- The project's script as the Script room holds it: the text (capped by maxChars, default 60,000 — `truncated` says when the cap applied), its length, how many scenes it is split into, and the revision in force (the last one a person accepted, numbered). Free, <1 s.
list_scenesList the scenes · read · free- Every scene in script order: id, number (the script's own, e.g. 12A, else its position), heading, title, synopsis, length in eighths of a page, story day, set, and version (bumped when its heading, cast, action or dialogue changes). Free, <1 s.
get_sceneRead one scene · read · free- One scene in full: its exact text from the script, heading, number, version, and the elements recorded in it (character, location, prop … — each with its lock id and whether it is locked). Free, <1 s.
list_locksList the script's elements · read · free- The project's continuity elements from the breakdown — characters, locations, props, vehicles, wardrobe, animals — each with its kind, description, sheet image when it has one, and whether it is LOCKED. Only locked elements are canon in renders; pass lockedOnly:false to see the proposed ones too. Free, <1 s.
list_revisionsList the accepted revisions · read · free- The script's accepted revisions, newest first: number, when it was accepted, how many scenes it held, and what the accept did (scenes inserted, matched, removed). Autosaves are not revisions and are not listed. Free, <1 s.
list_templatesList the templates · read · free- PREVIZ's Quick Start templates — the same catalogue every studio's Quick start reads: each one's name, what you get, its questions (answers) and the media it works on (slots), about how long it takes, and whether the door runs it (runs:true, with the tool it runs as and the default mode) or a person runs it in PREVIZ (runs:false, with the reason and the room it opens in). A template the door runs is priced exactly like that tool, because it runs through the same lane the app's own button uses. Free, <100 ms.
list_capabilitiesList what the door can make · read · free- Every capability the door can run in this project, before you write a line of code: what it takes and what it makes, its price in each mode (fast, balanced, deep) read live from the credit table, about how long it takes (rounded: to 5 s under a minute, to 30 s above), the jurisdiction classes it may run in, and whether this project allows it — under its engine policy and under the rules a person or organisation set for agents. Names capabilities, never an engine or the company behind it. Free, <1 s.
simulate_policySimulate the rules for a call · read · free- A dry run of every rule that would judge a call, before you spend: the rules a person or organisation set for agents on this tool (allow, ask or deny, and who set it) and this project's engine policy and your constraints (whether the call would run, and the jurisdiction classes it may reach). decision is deny when any rule refuses, ask when a person's press is needed, allow otherwise; decidedBy names the rule. Pass op and its args as you would send them. Writes nothing, charges nothing. Free, <500 ms.
Shoot
Frames, edits, takes, frame surgery and meshes, through the same gated, metered functions the studio's own buttons run. A paid one called without a quoteToken or an idempotencyKey answers with its quote and runs nothing.
generate_frameGenerate a frame · spend · quotes, then runs once- Generate a cinematic frame — the same gated, metered lane the studio's generate button runs. Without a quoteToken (or idempotencyKey) returns the CREDIT QUOTE and a quoteToken, and runs nothing; with it renders and returns the URL — or, past the time a client waits, a job handle {jobId} that get_job finishes. Locked identities ride by name (lockNames): a lock with an anchor card rides as a reference image, one without rides as anchor text. referenceImageUrls (≤3) add a reference line to the quote. keepBestOf 2–3 renders N candidates in Fast mode in parallel, embeds each against judgeAgainst (a lock name, shape id or URL — must be a project image) and returns ONLY the best by cosine with runner-up scores; every candidate is charged, and the quote counts every candidate. The price is the quote's, never typed here. mode: fast | balanced | deep (absent: fast until 28 Feb 2027, then balanced). Latency: fast est. 5–10 s; deep est. 15–40 s; keepBestOf adds a few seconds to read and embed each candidate. Returns imageUrl and a `where` block (project, room, onBoard, openUrl, assetUrl): the frame is a file in the project's storage; placeOnBoard:true also lands it as a card on the project's Infinitum board.
edit_frameEdit a frame · spend · quotes, then runs once- Edit an existing frame with words — the image lane's reference-edit path (the source frame rides as the reference; the prompt says what changes). Same gated, metered lane as generate_frame. Without a quoteToken (or idempotencyKey) returns the CREDIT QUOTE and a quoteToken: the tier's line plus a reference line. Latency est. 5–20 s. Returns imageUrl and `where`; placeOnBoard:true lands the edit as a card on the project's Infinitum board. If the result matches the source frame, nothing is saved and the charge is refunded by its ledger id: the answer reads {unchanged:true, refunded, creditsDeducted, nextStep}.
animate_frameAnimate a take · spend · quotes, then runs once- Render a video take — the studio's own metered video lane. With imageUrl the take animates from that frame; fromTake continues a finished take from its last frame (read out by PREVIZ, free); with closingImageUrl too it lands on that frame (first→last, 4 s floor); without imageUrl the prompt IS the shot (text-to-video). mode: balanced (default; priced per second, by resolution) | fast (priced per second at one rate whatever the resolution, 5–15 s, tops out at 768p — a 1080p ask is delivered at 768p and the quote says so; est. 60–120 s for 5 s — no repo measurement) | deep (the flagship lane, 4 s floor, priced per second by resolution). referenceImageUrls guide the look; look/camera/motion are shaped into the prompt the same way the studio's rail does. Without a quoteToken (or idempotencyKey) returns the CREDIT QUOTE and a quoteToken — computed by the lane's own billing branches, so fast quotes the fast rate. With it, submits, PLACES THE TAKE ON THE PROJECT'S INFINITUM BOARD as a card that fills in when it lands (placeOnBoard:false to skip), and returns {shapeId, where} — where.openUrl opens the board on the take. Poll check_take with the shapeId. ONE-STEP VOICED TAKE: with dialogue and castVoice, run under a signed spending agreement (your own idempotencyKey with maxCredits or a mandateId; queue:true works too) by a key that also holds write with an editor's role on the project (PREVIZ finishes the take on the board as that key; without them the answer keeps the two calls and says so), the answer is ONE job — jobId — that lands the take already in the character's cast voice: the conversion's price is quoted with the take, judged against maxCredits as one total and held beside the take's own; the take is charged when it launches and the conversion when PREVIZ runs it after the take lands, with nothing to poll. If the take fails the conversion's hold is released; if the conversion cannot run, the job lands the take with its own sound (voiced:false), the conversion is not charged, and the answer says why.
check_takeCheck a take · read · free- Poll a video take started by animate_frame. Advances the job on the engine (the same poller the studio runs) and returns {status, videoUrl?, latencyMs?, error?, nextStep?, where} — call every 10–20 s until status is done or error. On done the take is ON the project's Infinitum board (its card finished, or placed if it was missing) and where.openUrl opens the board on it. On error the credits are back and nextStep says what to change. Advancing and landing need the write scope and an editor role; without them the answer is readOnly:true, from what is already recorded. Free, <1 s.
estimate_depthEstimate depth · spend · quotes, then runs once- Monocular depth map for a frame (bright = near), persisted — the first step of Step-In and the AE 'Build comp' camera. Same gated lane the Step-In viewer calls. Without a quoteToken (or idempotencyKey) returns the CREDIT QUOTE and a quoteToken. Latency est. 5–10 s (one queue call; the lane waits up to ~70 s).
decompose_frameSeparate layers · spend · quotes, then runs once- Split a frame into 2–10 alpha PNG layers (clean background plus each foreground element) — the studio's layer lane, on every plan. Returns imageUrls and, when the engine states it, layers with names and bounding boxes. Without a quoteToken (or idempotencyKey) returns the CREDIT QUOTE and a quoteToken. Latency est. 20–60 s, so a run answers a job handle {jobId} at once and get_job returns the layers when they land.
inpaint_frameInpaint a region · spend · quotes, then runs once- Mask-aware inpaint or object removal: replace the WHITE region of maskUrl inside imageUrl with the prompt (empty prompt = remove and fill from the surroundings). Same gated lane the canvas calls; upload a mask with upload_asset kind 'mask'. Without a quoteToken (or idempotencyKey) returns the CREDIT QUOTE and a quoteToken. Latency est. 10–20 s. If the result matches the source frame, nothing is saved and the charge is refunded by its ledger id: the answer reads {unchanged:true, refunded, creditsDeducted, nextStep}.
relight_frameRelight a frame · spend · quotes, then runs once- Relight a frame without regenerating it — subjects, pose and composition held; only light, shadow and colour temperature move. lightingStyle: natural | golden_hour | neon | studio | dramatic | soft | backlit | moody | cool | warm. Without a quoteToken (or idempotencyKey) returns the CREDIT QUOTE and a quoteToken. Latency est. 10–25 s. If the result matches the source frame, nothing is saved and the charge is refunded by its ledger id: the answer reads {unchanged:true, refunded, creditsDeducted, nextStep}.
split_plateSplit plate and subject · spend · quotes, then runs once- Split a frame into [clean plate, subject] for a compositor: the subject cutout (alpha PNG) and the healed background plate with the subject removed, run IN PARALLEL through the studio's own two gated, metered lanes — so relighting the plate afterwards (relight_frame on plateUrl) cannot drift the character, who is never re-rendered. Without a quoteToken (or idempotencyKey) returns the CREDIT QUOTE and a quoteToken {credits, lines} — one line per half. With it returns {plateUrl, subjectUrl, engine:{plate, subject}, creditsDeducted, latencyMs}; if one half fails its URL is null, partial:true says which, and only the half that landed is charged (the lanes refund their own failures). Latency est. 10–20 s (parallel; wall time is the slower lane).
generate_meshGenerate a 3D mesh · spend · quotes, then runs once- Generate a 3D mesh (glb) into a project — the studio's own gated, metered 3D lane. With imageUrl the mesh stands up from that image (image→3D); WITHOUT it the prompt builds it (text→3D). Locked identities can ride by name: image→3D holds them through the source render, text→3D folds their anchor descriptions into the prompt so the geometry is built to the locked look — and the lock set is stamped on the result as provenance. Without a quoteToken (or idempotencyKey) returns the CREDIT QUOTE and a quoteToken, and runs nothing; with it, submits and returns {requestId, engine, locks, provenance} to poll with check_mesh; text→3D and image→3D are priced separately in the quote. engine names the capability, never a vendor's model. mode: balanced (default) | fast (image→3D only: the rapid, untextured mesh) | deep (runs as balanced and is charged the Balanced price: 3D has two rungs). Text→3D has one lane: every mode runs it at one price. Latency: balanced ~300 s (the lane's own comment); fast est. 60–90 s.
check_meshCheck a mesh · read · free- Poll a 3D mesh started by generate_mesh. Returns {status, modelUrl?, thumbnailUrl?, engine?, error?} — call until status is done or error. Pass source (text|image) from generate_mesh; omit it and the job's own kind is used. The modelUrl is a glb the plugin imports; the thumbnailUrl is a preview that can ride onto the board with place_on_board. Free, <1 s.
start_productionStart a production · produce · free- Hand PREVIZ a brief and start a production in the project: PREVIZ's producer plans it, asks what it needs to know, makes the frames and takes and lands them on the project's board, and keeps working with no client connected. Sending words never spends: the plan comes back PRICED (decisions[] with needKey "plan") and nothing runs until it is agreed — decide under a spending agreement (mandateId), or a person's press on PREVIZ. With mandateId here, PREVIZ agrees each priced decision that fits the agreement itself, within about a minute (the plan's Go included; final-tier work and settings changes stay a press), and the answer says autoPress: true; omit it to review prices and decide yourself. recipeId runs a recipe a person saved in PREVIZ. Read it with get_production; follow it with events_since or the event stream. API keys only.
saySay something to a production · produce · free- One message into a production: a steer, a change, the next thing to make. It is queued behind the work in flight and the production carries on. Words never move money: approving words while a price is open ("go", "approved") are refused with input_required and the words are not sent — answer the priced decision with decide. API keys only.
answerAnswer a production's question · produce · free- Answer a question the production asked (decisions[] with kind clarification or slot): the options chosen, or the slots' values. Answering never spends. A likeness — a real person's face or voice — is never answered by an agent: that stays a person's own choice in PREVIZ. API keys only.
decideDecide a production's decision · produce · free- Press one of a decision's choices (decisions[]: needKey and a choice id). A free choice — a plan review, skip, retry — is answered at once. A PRICED choice (money: true — the plan's Go with needKey "plan", an overrun, a setting change) runs only under a spending agreement a person signed for this key (mandateId), which PREVIZ holds before anything is charged; without one, or past its limits, the answer is input_required with an approvalUrl a person presses on PREVIZ, and nothing is charged until they do. The press is made the way a person's is: it binds the price shown and never lands before a person could have read it. API keys only.
stopStop a production · produce · free- Pause a production (press 1: nothing new starts; work already running finishes) or stop it (press 2: running work is cancelled at the engine; what was made is kept and billed, what was not comes back). resume lifts a pause. Stopping never charges. API keys only.
resumeResume a production · produce · free- Lift a pause: what was queued goes ahead. Resuming never charges; anything priced still waits for its decision. API keys only.
get_productionRead a production · produce · free- Read a production as it stands: its status, the decisions waiting (with their prices), its turns, its takes and outputs with their states (running, input_required, landed, failed — the engine said so — or house — PREVIZ's side), its messages (in untrusted envelopes) and its ledger (agreed, held, made, billed, returned). since (a turn sequence) reads only what changed. No state here comes from a clock. Free.
list_productionsList productions · produce · free- The project's productions, newest first — each with its status, state and ledger. Free.
production_settingsA production's settings · produce · free- Read a production's settings — aspect, image and video resolution and length, how hard PREVIZ thinks — or change them with `set`. Engines are chosen by PREVIZ under the project's engine policy and are not set here; money is never set here. A change re-prices the plan when one is waiting (read its decision again). API keys only.
queue_editEdit a production's queue · produce · free- Remove a message waiting in the production's queue, or move it up, down or to a place. Free. API keys only.
get_take_frameRead a frame out of a take · read · free- A still out of a finished take — its last frame by default (which: first | middle | last) — stored in the project and returned as an https imageUrl, ready to be the imageUrl of the next animate_frame or a reference anywhere. take: the take's jobId (an animate_frame job of this credential) or its shapeId. Read once per take and frame and kept, so asking again is instant. Reading a new frame out needs the write scope and an editor role; without them only a frame already read is returned. Free.
convert_voiceConvert a take's voice · spend · quotes, then runs once- Turn the speech in a finished take (take) or a sound file in this project (audioUrl) into a character's fixed voice (character — their cast voice, see cast_voice) or a named voice (voiceId). Speech-to-speech: the timing and delivery of the source are kept and background noise is removed, so a line the engine spoke in the take keeps matching the lips. The result is levelled to −23 LUFS (−1 dBTP). For a take, PREVIZ also lays the new voice under the take's picture as a new take (videoUrl) and, unless placeOnBoard is false, places it on the board beside the original. A sound from outside PREVIZ is uploaded first (upload_asset with url). The answer measures the timing: the source's and the result's durations. Pulling the sound out, levelling and laying it back are free; the conversion is metered. Without a quoteToken (or idempotencyKey) returns the CREDIT QUOTE and runs nothing. A take with no sound track is refused before anything is charged; a take whose sound has no speech is still converted and charged.
speak_lineSpeak a line in a character's voice · spend · quotes, then runs once- Speak a line — an off-screen voice, a voice-over, a phone voice — in a character's cast voice (character) or a named voice (voiceId), levelled to −23 LUFS (−1 dBTP), as a sound file in the project's storage. It is already in the character's fixed voice, so it needs no conversion. Returns audioUrl and its measured duration. Without a quoteToken (or idempotencyKey) returns the CREDIT QUOTE and runs nothing.
get_take_audioRead a take's sound out · write · free- A finished take's own sound as a file in the project's storage (take: its animate_frame jobId or its shapeId), levelled to −23 LUFS (−1 dBTP), with its measured duration — ready for your own mix, for separate_audio or for convert_voice. Read once per take and kept, so asking again is instant. Needs the write scope and an editor role on the project. A take with no sound answers so. Free.
separate_audioSeparate dialogue from the rest · spend · quotes, then runs once- Pull a finished take's sound (take) or a sound file in this project (audioUrl) apart into tracks. split dialogue (default): the dialogue alone, with background noise, effects and music removed. split stems: four stems — vocals (the dialogue) and drums, bass and other, which between them carry the effects, the ambience and any music; mix those three for one effects track. Every track is a file in the project's storage with its measured duration, and for a take the take's whole sound comes back too (fullUrl). A sound from outside PREVIZ is uploaded first (upload_asset with url). Pulling the sound out of a take is free; the separation is metered. Without a quoteToken (or idempotencyKey) returns the CREDIT QUOTE and runs nothing. A take with no sound is refused before anything is charged.
generate_sfxMake sound effects · spend · quotes, then runs once- Sound effects from words — footsteps on wet gravel, a door slam in a stairwell, room tone — one (prompt, durationSec) or up to 6 at once (cues), each a file in the project's storage. The answer is by segment: one per cue, with what was asked beside what was measured (duration, loudness) — PREVIZ does not listen to the result, so it never claims what the file sounds like. Each file is levelled to −23 LUFS unless you set loudnessLufs or engineLevel. Levelling and measuring are free; each effect is metered. Without a quoteToken (or idempotencyKey) returns the CREDIT QUOTE and runs nothing.
generate_musicCompose music · spend · quotes, then runs once- Music from words — a score cue, a stinger, a bed under a scene — one (prompt, durationSec) or up to 4 at once (cues), each a file in the project's storage. 5–360 s per cue; past 180 s a cue is composed as a long-form piece, which the quote shows as its own line. The answer is by segment: one per cue, with what was asked beside what was measured (duration, loudness) — PREVIZ does not listen to the result, so it never claims what the file sounds like. Each file is levelled to −23 LUFS unless you set loudnessLufs or engineLevel. Levelling and measuring are free; each cue is metered. Without a quoteToken (or idempotencyKey) returns the CREDIT QUOTE and runs nothing.
replay_staleRe-shoot what a decision made stale · spend · quotes, then runs once- Re-shoot exactly what a changed decision made stale, and nothing else. For a lock whose reference image changed, each board frame that lock rode in is rendered again from the request recorded when it was made, under the version in force (the one reference re-pointed where the request carried it; the request unchanged where the room attached the lock itself and reads it again), on the draft rung, onto the same card. Whatever cannot be replayed exactly, or would not change, is listed as skipped with its reason, never guessed: work from other rooms, a frame with no recorded request, a frame the lock did not ride in, a project-wide decision, a lock whose reference did not change. One re-shoot per frame per decision version; it spends inside the project's daily re-shoot budget and under today's engine policy. The first call answers the plan and its quote; nothing runs without the quoteToken.
replay_jobReplay a job exactly · spend · free- Run a finished job again exactly as it was asked: the arguments recorded when it ran, priced today under today's engine policy. Answers the tool to call, those exact arguments and a quoteToken bound to them; calling that tool with them runs it through its own path, once. Nothing can be changed on the way (change something by calling the tool yourself). Refused when the request is no longer kept, the tool has changed shape, or the policy now leaves it no engine — never run on a different one. Free; nothing runs here.
run_chainRun a chain · spend · quotes, then runs once- Run a chain: a pipeline of tool calls written as data (plan_chain says what a chain may hold; chainable tools and outputs: generate_frame (image), edit_frame (image), inpaint_frame (image), relight_frame (image), estimate_depth (depth), split_plate (plate, subject), animate_frame (take, video), render_cut (video), speak_line (audio), convert_voice (audio, video), generate_sfx (audio), generate_music (audio)). Without a quoteToken (or idempotencyKey) returns ONE quote for the whole chain, priced step by step by each tool's own quote, and runs nothing. With it PREVIZ opens the chain and answers a job handle at once; each step then runs as its own job — its own scope and reach check, engine-policy gate, audit row and charge — and is billed only when it lands. The steps together can never cost more than the quote. A step waits for the outputs it takes; onFail says what its failure does (stop, skip, retry_once). Under a spending agreement (mandateId with an idempotencyKey) every step is held to the agreement on its own: a step the agreement leaves to a person parks the chain as input_required, nothing run or charged for it, until they press. get_job {jobId} reads the chain and every step; cancel_job stops it (nothing new starts; a step already with its engine finishes and is billed only if it lands); resume_chain carries a stopped or parked chain on; replay_job quotes the same chain afresh. A credential may have 3 chains running at once and an organisation 10; a chain's quote stands for 24 hours.
resume_chainCarry a chain on · spend · free- Carry on a chain that stopped or is waiting on a person. A stopped chain's failed step is tried again when its last attempt charged nothing and it has attempts left (3 in all), and the steps behind it follow; a parked step runs once the person has pressed. Everything runs inside the total the chain was quoted at, under the authority it was started with, at the prices and engine policy it was quoted under — a price or policy that has moved stops the step, and replay_job then quotes the chain afresh. Refused for a cancelled chain, one that has ended, and one whose quote is more than 24 hours old. Free to call; steps are billed as they land.
run_templateRun a template · read · free- Run a Quick Start template (list_templates) in a project: answer its questions (answers) and give its media (slots, https addresses of project files), and the door runs it AS the tool list_templates names — the same quote, money law, mode, job and answer as calling that tool, at the app's own price. Without a quoteToken (or idempotencyKey, or an agreement) the first call returns the quote and runs nothing. `with` adds the tool's own optional arguments the template allows (passes), such as a voiceId or lockNames. A template the door does not run is refused TEMPLATE_UNAVAILABLE with the reason; nothing is charged. The answer names the template it ran.
Board
Place results on an Infinitum board, lock an identity, pin a note. Free writes to your own projects.
place_on_boardPlace on the board · write · free- Place a finished asset (imageUrl or videoUrl) onto the project's Infinitum board as a card, so it appears in the studio. With laneId the card lands INSIDE that Sequence Lane after its last clip (the lane grows to fit) and so joins the cut; without, beside the board's content. A project never opened in the studio gets its board on first use. Free — no credits, <500 ms.
lock_identityLock an identity · write · free- Lock an identity into the project's continuity banks so every future render holds it faithful. kind: character | object | location (in the fashion house these read as model | garment | set). anchorImageUrl places the image as an anchor card and references it from the lock, so the lock rides into renders as a REFERENCE IMAGE, not only as text; anchorShapeId references a card already on the board instead. The lock is also written to the project's continuity locks, so the studio's own renders, project memory and the drift check hold it too. A lock is SET ONCE from here: the same name with the same anchor is accepted again and changes nothing, and a call that would change a lock that stands (another anchor, another reference image, or a name a person left unlocked) is refused with LOCK_CHANGE_IS_A_PERSONS, because changing a lock supersedes a decision and a person makes it in PREVIZ. Works on a project never opened in the studio: its board is made on first use. Free.
write_notePin a note · write · free- Pin a note card onto the project's board — direction, TODOs, a brief. Free.
cast_voiceCast a voice to a character · write · free- Lock a voice to a character in the project — every later line for that character (convert_voice, speak_line, and the studio's own audio rooms) is performed in it. character is the name as the script writes it (MAYA, Maya and MAYA (V.O.) are one character). voiceId is an id from list_voices; it is checked before it is saved and again on every performance, so a voice whose consent lapses is refused by name. Re-casting replaces the character's voice; a lock another account set is not changed from here. Free.
propose_decisionPropose a decision · write · free- Ask a person to make a decision part of the project's memory: a rule, a look, a frame, a palette or a camera decision, optionally about one entity, optionally replacing a decision in force (replacesDecisionId). NOTHING changes until a signed-in person accepts it in PREVIZ; an agent cannot accept, and a lock is changed only by a person in its room. Their bell rings; a brain.proposal.decided event says what they chose. The same words still waiting answer the same proposal. Free.
propose_script_revisionPropose a script revision · write · free- Propose a new version of the project's script. It is saved as a PROPOSED revision in the script's history (Script → History, marked as proposed by an agent) and changes nothing else: the live script, its scenes and everything made from them stay exactly as they are until a person opens it and presses Use this — an agent never writes the live script. title names it in the history. An idempotencyKey makes a retry return the same proposal. Free, <1 s.
Cut
Read a Sequence Lane as a conform manifest and render the cut.
get_cutRead the cut · read · free- Read a project's Sequence Lane as a conform manifest: the ordered clips of the cut — a saved Cut Room edit's order, trims and omissions honored — with per-clip URLs, in/out points and audio flags, plus the lane's scratch music bed. Call without laneId to list the project's lanes (a single lane returns its manifest directly). Free. This is the manifest the Premiere panel's conform writes into a timeline.
render_cutRender the cut · spend · quotes, then runs once- Render a cut into ONE continuous MP4 — the studio's own compositor lane, same billing and refunds. The cut is a Sequence Lane on the board (laneId; a saved Cut Room edit's order, trims and omissions honored, its music bed and each clip's ticked sound mixed in) OR your own list of clips, no board needed: clips [{take | url, outMs?, sound?}] in order, a take by its animate_frame jobId or shapeId, a url only from this project's storage (upload_asset first). Each clip plays from its first frame for outMs (default: its whole length; at most 20 s; a still holds 2 s), with its own sound unless sound:false. tracks lays outside sound under the cut: [{url (a sound in this project), kind: voice | music | sfx, atMs, durationMs?, level?}], each levelled before the mix — dialogue −23 LUFS, effects −26, bed −32, or a LUFS number — so a bed sits under the voices; fades are not offered yet. A cut past 24 clips renders in sections of at most 24 and is joined into one file: every section is one line on the quote. Without a quoteToken (or idempotencyKey) returns the CREDIT QUOTE, the timeline (where each clip starts) and a quoteToken, and runs nothing; with it, answers a job handle {jobId, status: running} at once and get_job {jobId} returns the videoUrl when it lands. There is no machine re-edit on this path.
check_cut_continuityCheck continuity across the cuts · read · free- Continuity across each CUT PAIR of a cut — the last frame of clip i beside the first frame of clip i+1 — read as an embedding cosine ('looks alike': palette, silhouette, styling; NOT a verdict). Up to 12 pairs per call; fromPair pages a longer cut (the answer's nextPair). The cut is a lane (laneId) or your own clips list, as render_cut takes them. The stills are read out of the takes once and kept (free); reading new ones out needs the write scope and an editor role. A far band across a cut is often a scene change, which is meant — judge_cut_continuity reads objects, costume and screen direction pair by pair. Free.
judge_cut_continuityJudge continuity across the cuts · spend · quotes, then runs once- A judged continuity read of each CUT PAIR (the last frame of clip i and the first frame of clip i+1): is it one scene, and do objects, costume and screen direction (the 180° line) hold across the cut — pass | warn | fail | unclear per aspect, with what changed. Runs under the project's engine policy; priced per pair, and a pair the judge could not read is refunded. Up to 12 pairs per call (fromPair pages, or pairs names the ones to judge). The cut is a lane (laneId) or your own clips list. focus (optional) names what to watch, e.g. 'the red scarf'. A warn or fail lands as a drift.warn / drift.fail event. Without a quoteToken (or idempotencyKey) returns the CREDIT QUOTE and a quoteToken, and runs nothing.
Host
Upload an asset and read the events cursor, for panels, scripts and pipelines.
upload_assetUpload an asset · write · free- The door's inbound lane: put a file the host made (a Blender greypass, an AE mask, a Premiere frame, a take, a voice or music track) into the project's storage and get its https URL back for the other tools. kind: image | mask | video-frame | audio | video. Send EITHER base64 (≤ 2 MB decoded) OR url — an https address PREVIZ fetches itself: public hosts only (private, local and cloud-metadata addresses are refused, after DNS and on every redirect, at most 3), 30 s per hop, up to 10 MB for an image, 25 MB for audio, 50 MB for a video. The file's own bytes decide its type (png, jpeg, webp, mp3, wav, m4a, mp4); a mime that disagrees with them is refused. 200 uploads per project per day per key. placeOnBoard:true also lands an image or video as a card. No content check runs here — generation lanes moderate at render time. Free.
events_sinceRead events since a cursor · read · free- One cheap cursor instead of five job endpoints: everything that landed across this credential's projects since the cursor — job.queued (accepted into the queue, or sent back to wait: detail.position, detail.estimatedStartAt) | job.started | job.landed | job.failed | job.house | job.cancelled (this door's own runs; a job that ended on something only a person can lift carries detail.actionUrl, the page to hand them) | take.done | take.error | mesh.done | mesh.error | drift.warn | drift.fail | board.updated | production.turn (ids.productionId, ids.turnId) | production.item.landed (ids.productionId, ids.itemId) | production.question (ids.productionId, ids.needKey: answer it) | production.ask (ids.productionId, ids.needKey, detail.credits: a priced decision — decide) | production.settled (ids.productionId, detail.billed) | approval.needed | approval.decided (ids.approvalId) | mandate.80pct | mandate.exhausted (ids.mandateId) | brain.decision.superseded (ids.decisionId, ids.supersededId, detail.staleCount: stale_since lists the work, replay_stale prices re-shooting it) | brain.proposal.needed | brain.proposal.decided (ids.proposalId, detail.status) — with ids and short facts, oldest first, and a nextCursor to pass back. job.*, production.ask, production.settled, approval.* and mandate.* reach only the person who pays or signed. Read from an event outbox the platform's own tables write as they change, ordered so that no event is ever skipped (two that land in the same millisecond are both read). An ISO timestamp is still accepted as a cursor and read inclusively. Poll every 3–5 s while work is in flight, or hold the event stream instead: GET this same address with ?stream=events (Accept: text/event-stream; projectId and cursor as query parameters), resumable with Last-Event-ID, closing in under 140 s with a stream.end event naming nextCursor; at most 2 open per credential. Free, <300 ms.
get_jobRead a job · read · free- Read one run this credential started: a paid tool answers a job handle {jobId, status:"running"} when its work outlives the time a client waits (render_cut and decompose_frame always do), and the work carries on. status: queued | running | landed | failed | house | cancelled. A landed job's result is exactly the answer the tool call would have given; the receipt says what ran, what it was quoted, what the lanes charged and the policy it ran under. A job accepted with queue:true reads queued until PREVIZ starts it, with its place in line and an estimated start (queue). waitSeconds (0–25) holds the call until the job leaves running (or a queued job starts) or the wait ends — a long-poll, free. A job's state comes only from what the engine and the lanes said, never from a clock: a run whose worker was lost is finished by PREVIZ's sweeper with nobody watching. A chain's jobId (run_chain) also answers a chain block: the chain's own status (running, input_required, landed, stopped, cancelled), every step with its own jobId, what it was quoted and charged and what it made, and the chain's receipt; the wait ends when the chain stops moving. Free.
list_jobsList jobs · read · free- The runs this credential started, newest first — each with its jobId, op, status (queued | running | landed | failed | house | cancelled) and what it charged. A queued job carries its place in line and an estimated start. status narrows to one state; projectId to one project; label to one batch. labels sums jobs and settled credits per label over this credential's newest 1,000 runs under the same filters (truncated says when there were more). Use get_job {jobId} for a job's result and receipt. Free, <300 ms.
get_audit_logRead the audit log · read · free- Every call this credential made through the door, newest first — free reads and refusals included: op, project, outcome (ok | quoted | handle | refused | error), the refusal's code, credits charged, the capability that ran, its job and quote, the traceparent you sent and how long it took. Arguments are kept only as an HMAC (the same arguments give the same hash), never as text. Filter by projectId, op, outcome, since; page with before (the next block names it). The person reads every agent's calls, and exports them as CSV or JSON, in PREVIZ. Free, <300 ms.
freezeFreeze this credential · read · free- Brake yourself: freeze the credential this call came through, at once. Every call but get_account is then refused with FROZEN and no spend can start under it, until a person lifts it, signed in to PREVIZ. Use it when you have lost track of what you are spending or doing, or when told to stop. It freezes only this key or this connection — never another — and no tool can unfreeze. Free.
list_mandatesList spending agreements · read · free- The spending agreements a person signed for THIS API key, newest first: projects, total, per-job and per-day limits, tiers, jurisdictions, what stays a person's own press, expiry, and what is used and left. A paid tool called with one's mandateId and an idempotencyKey runs without the quote round trip while it fits; anything outside it is refused before anything runs. status filters (default active). A connector sign-in has none. Free, <300 ms.
get_mandateRead a spending agreement · read · free- One spending agreement of this API key by its mandateId, with what is used and left in all and today (UTC). Free, <300 ms.
request_mandateAsk a person for a spending agreement · read · free- Ask the person who owns this API key to sign a spending agreement, so paid tools can run without a quote round trip each time. Answers a PREVIZ link (approvalUrl) to hand the person — never an agreement: they choose the projects, limits, tiers and expiry on PREVIZ's own page, signed in, and may change anything you suggest. Suggest projectIds (required) and, optionally, upTo, perJobMax, perDayMax, tiers and expiresInDays (≤ 30); no free text is carried. The link stays open 24 hours; list_mandates shows the agreement once signed. Only an API key that can spend may ask. Free.
await_approvalWait for a person's press · read · free- Wait for the person to approve or decline a request this credential was answered input_required for: returns as soon as they press on PREVIZ, or after waitSeconds (at most 25) with status pending — call again, asking is free. status approved: call the same tool with the same arguments and approvalId to run it, once — except a production's decision (productionId in the answer), which the person's press already answered in the production: read get_production, nothing is re-run. declined is final for that request; expired means ask again. Only the person can press, signed in to PREVIZ; nothing here approves anything. Free.
cancel_jobCancel a job · write · free- Cancel a run this credential started. A job still waiting in the queue (status queued) is taken out at once: nothing ran, nothing is charged, and what it held under the spending agreement is released. A one-step voiced take is two jobs: cancelling its take while it waits releases the voice conversion too, and cancelling the voiced job takes the take out with it only while the take itself still waits. A production (start_production's jobId) is stopped at the engine: running work is cancelled, what was made is kept and billed, what was not comes back; itemId cancels one of its takes instead. A chain (run_chain's jobId) stops at once: nothing new starts, every step not yet with its engine is cancelled, and a step already with its engine finishes and is billed only if it lands. Any other run (a frame, a mesh, layers, a take) is already with its engine, which has no cancel: the answer is too_late, code CANCEL_TOO_LATE, and it says in the same answer what the run is billed if it lands (billedIfItLands) — a run that fails is not billed, a refusal is refunded, and a lost run's charge is reviewed and refunded only if nothing landed. Every answer carries a receipt: quoted, reserved, made, billed and returned. Cancelling twice answers the same. Cancelling never charges.
subscribe_webhookSubscribe a webhook endpoint · webhooks · free- Register an https endpoint and PREVIZ POSTs events to it as they happen: a take or a job landing, a production's question, a continuity warning, an approval waiting. Filter by event kind (take.done) or family (production.*) and by project. Each delivery is signed (Standard Webhooks headers: an HMAC under this endpoint's secret and an Ed25519 signature under PREVIZ's published key), carries ids only — read the rest with events_since or the tool the id belongs to — and is retried for 24 hours, then listed as a dead letter. The answer shows the endpoint's secret ONCE. The URL must be https on port 443 and resolve to public addresses; a redirect is never followed. This key's access is checked again at every delivery. Free.
list_webhooksList webhook endpoints · webhooks · free- The endpoints this API key subscribed, newest first, each with its filters, status and newest dead letters (deliveries that ran out of retries, were redirected, or lost their access): message id, event kind, attempts and why. A dead letter's cursor reads the event again through events_since. Free, <300 ms.
rotate_webhook_secretRotate a webhook secret · webhooks · free- Give an endpoint a new signing secret. The answer shows it ONCE; for 24 hours every delivery is signed with both the new and the previous secret, so the receiver can switch without dropping one. Free.
test_webhookSend a test delivery · webhooks · free- POST one signed webhook.test delivery to an endpoint now and answer how it went: the HTTP status it answered, or why nothing was sent. Use it to prove the receiver verifies signatures before real events arrive. A test that is answered 2xx revives an endpoint that had gone dead. No event happened; nothing is retried. Free.
delete_webhookDelete a webhook endpoint · webhooks · free- Stop delivering to an endpoint, at once. Its record is kept (deleted), nothing more is sent to it, and deleting it again answers the same. Free.
simulate_eventFire a test event · write · free- TEST KEYS ONLY. Write one event of any kind into the sandbox project's event stream, as if the work had happened: events_since, the event stream and every subscribed webhook endpoint then carry it. Use it to exercise a handler for a kind the sandbox script does not reach on its own (a continuity warning, a mesh finishing). The event names fixture ids. Free.
get_governanceRead the rules for agents · read · free- The rules that bind this credential: which tools an organisation's owner or admin, or the person themselves, set to deny (refused before anything is read) or ask (a priced run waits for a signed-in person's press on PREVIZ, with the price on the button; a quote is still answered). The strictest rule wins, and a person's own rule can only add to the organisation's. Pass projectId to include the rules of the organisation that owns that project. Quotes are bound to version: a rule changed after a quote makes the quote stale. Rules are set only by a signed-in person in PREVIZ; no tool changes one. Free, <300 ms.
get_set_packageRead a set package · read · free- A CineForge set as a SET PACKAGE: versioned JSON a virtual-production engine builds a sequence from. It holds every camera as a shot (the scene camera, the move on the timeline, each walked take) with its filmback, focal length and one baked key per frame at 24 fps — sampled with the same interpolation the room plays, in Unreal Engine's convention (centimetres, +Z up, left-handed, rotators) beside PREVIZ's own; every stand-in at its mark with its model file, the cast member it stands for and its PREVIZ id; the lighting rig as lights (type, aim, cone, colour temperature, ratios); and, with laneId, the cut as shot sections with handles. The package is stamped with the decisions in force when it was built (madeUnder) and a revision that changes only when the set does. Without sceneId it answers your most recently edited set in the project and lists the others. notes says, in sentences, what does not cross (focus distance, aperture, absolute light levels, a generated world's splat). Baked keys are large; summary:true answers the same package without them. Saved angles live in the browser and are only in a package the room sends. The import into Unreal Engine has not been verified by PREVIZ yet. Free, <2 s.
send_engine_frameSend an engine frame · write · free- THE WAY BACK from a virtual-production engine. A frame of a shot PREVIZ sent, taken in Unreal Engine (a viewport capture or a Movie Render Queue frame), becomes that shot's ENGINE FRAME: PREVIZ checks the bytes are a PNG or JPEG, stores its own copy in the project, and records what the picture is of (the shot, the set revision its sequence was built from, and which stand-ins had been moved in the level by then). By rule it also becomes the REFERENCE IMAGE of the set's location lock, which is how the Brain records it as a decision: a render that names the set then carries the frame as a reference, drift is checked against it, and takes made under the earlier reference read as stale. The rule: the first engine frame of a set becomes its reference; a newer frame of the same shot replaces it; a frame of another shot is stored and becomes the reference only with asReference:true; a reference image a person chose is never displaced without replaceReference:true; a lock a person left unlocked is written only when asked, and PREVIZ never locks it; a set with no name gets no lock. Send exactly one of base64 (up to 2 MB decoded) or url (https, up to 8 MB; upload_asset's url is fine). Name the shot with shotId (a shot id from get_set_package), or pass sidecar, the record the PREVIZ plugin writes beside each frame. The same picture of the same shot sent twice is stored once and changes nothing unless asReference:true (replayed:true). Free.
report_set_buildReport a set build · write · free- Tell PREVIZ that a set package was BUILT in a level, and under what. Pass build: the record the PREVIZ plugin writes under PREVIZ/builds for each build (format previz.set-build), holding the set revision, every decision version it was built under (the package's madeUnder), the sequence and level it made, and a fingerprint of where the stand-ins stood. PREVIZ keeps it and answers at once whether it is already stale. From then on get_set_link_status says, for every reported build, whether the set has been edited since, and which decision it was built under has a new version or is no longer in force. The same record sent twice is one row (replayed:true). A build made from a file the room saved did not read the project's decisions, and reads as 'not compared' rather than as fresh. Free.
get_set_link_statusRead the Set Link's status · read · free- Where a set stands between PREVIZ and Unreal Engine. For one of your CineForge sets (the most recently edited when sceneId is omitted): every build reported from a level with whether it is STALE and why (the set was edited since; a decision it was built under has a new version or is no longer in force; decisions made since are counted and do not make it stale); every engine frame that came back, newest first, with which one is the set's reference, whether the set was edited after its sequence was built, and how many stand-ins had been moved in the level when it was taken; the reference image on the set's location lock; and the editors paired with the set. Free, <2 s.
Live
Read a live session's direction log, direct a set that is on air, play a board live.
get_take_logRead a take's direction log · read · free- The direction log of an AIM Director LIVE take: every line the director said or typed, the prompt it became, its status, and the second it landed — for markers in a Premiere or AE timeline. Find the session by sessionId, or by a take's takeId (the grid row) or the board shapeId holding its video. tSeconds is from landed timestamps when the browser recorded them, else chunk × chunk length (Steady/Dynamic); the Cinema tier's chunking is not recorded server-side, so its chunk-derived times are null. Free, <300 ms.
list_live_sessionsList live sessions · read · free- What is ROLLING right now: the AIM Director LIVE sessions this key's owner has on air, across the key's projects (or one projectId) — id, projectId, tier, engine, startedAt, expiresAt, status, lastChunkAt (the newest landed direction when the browser has logged one, else the row's last update). A session must be rolling for live_direct or play_board to accept it. Free, <300 ms.
live_directDirect a live set · live · free- Direct a rolling live set from outside the browser: append ONE line to the session's inbox — the browser enqueues it into the same pacing queue as a typed direction (source 'agent', same 2.2 s gap, a newer line replaces a queued one rather than stacking) and it lands at the next chunk boundary, ≈3–7 s to picture. said ≤ 280 chars, plain direction ("wider, then hold on the door"). at: optional seconds into the session to schedule the beat; omit for as-soon-as-the-queue-allows. Refuses when the session is not rolling or not this key's owner's. The inbox keeps the last 200 lines. Free — the running session's minute meter is the only charge.
play_boardPlay the board live · live · free- Press play on the storyboard and it happens live: read a Sequence Lane's cut (a saved Cut Room edit's order and trims honored, the same manifest get_cut returns) and append it to a rolling session's inbox as a BEAT SHEET — one line per clip, said = the clip's prompt, at = the second the clip starts (cumulative durations from a now-relative 0). The browser's beat runner fires each at its time. Refuses when the lane has no clips with something to say, when the session is not rolling, or when the cut has more beats than the inbox holds. Returns beats, totalSeconds and any promptless clips skipped. Free.
Access classes
A key holds only the access classes its owner gave it, set in Account → API keys → the key's Access: a new key holds read and write, and spend needs a monthly credit cap. tools/list shows only the tools a key holds, and a call to any other is refused with INSUFFICIENT_SCOPE. A key made before access classes existed keeps what it could do then (read, write, spend and live) until its owner sets its access; produce is given, never inherited.
read- Reads only; changes nothing and costs nothing.
write- Changes your project for free: a card, a lock, a note, an upload.
spend- Can spend credits: called without a quoteToken or an idempotencyKey it answers with a quote and runs nothing; called with the quote's token, or with your own idempotency key, it runs once and is charged once. A key whose access its owner has set spends only under a monthly credit cap.
produce- Drives a production: start one from a brief, say, answer its questions, stop or resume it, read it. Words never move money: a priced decision is pressed by decide under a spending agreement (which needs spend too) or by a person on PREVIZ. API keys only; a key made before access classes existed does not hold it until its owner gives it.
live- Acts on a live session that is on air.
webhooks- Manages webhook endpoints: subscribe an https URL and PREVIZ posts your projects' events to it, signed, carrying ids only; list them, rotate a secret, send a test, delete one. API keys only; the key's access is checked again at every delivery.
Errors
Every way the door says no, what it sends and what to do next. A refusal never charges.
- A call from a web page on an origin that is not allowed
- HTTP 403, JSON-RPC error -32003, before the body or the key is read. Call the door from a server, a terminal or a desktop client.
- A body that is not one JSON-RPC 2.0 message, or a batch
- HTTP 400, JSON-RPC error -32700 (unparseable) or -32600 (invalid or a batch), before the key is read. Send one message per POST with "jsonrpc": "2.0", a method and a string or number id.
- No key, a malformed key or a revoked key
- HTTP 401 with a WWW-Authenticate challenge, before any method runs, the handshake included. Stop and ask your person for a key; retrying will not help.
- An MCP-Protocol-Version header naming a version this door does not speak
- HTTP 400, JSON-RPC error -32600, naming the versions it supports. A request with no such header is accepted. Send the protocolVersion that initialize returned, or leave the header off.
- An unknown method
- JSON-RPC error -32601, "Unknown method" with the method's name. Use initialize, ping, tools/list or tools/call.
- An unknown tool
- JSON-RPC error -32602, "Unknown tool", naming tools/list. Call tools/list for the tools this door offers.
- Arguments that do not match the tool's input schema
- Protocol 2025-06-18: JSON-RPC error -32602 with the issues. Protocol 2025-11-25: a tool answer with isError set, naming each issue. Fix the named arguments. Unknown arguments are named, never ignored; confirm sent as the text "true" is refused, never coerced.
- A project id this key cannot reach
- A tool answer with isError set, beginning PROJECT_UNREACHABLE, naming the cause (a key limited to other projects, a role below editor, a project outside the key's reach) and list_projects. Use an id from list_projects, or ask the key's owner to widen its access in Account → API keys.
- A tool whose access class the key does not hold
- A tool answer with isError set, beginning INSUFFICIENT_SCOPE, naming the class the tool needs and the classes the key holds. Nothing ran and nothing was charged. Ask the key's owner to add it in Account → API keys → the key's Access; spend needs the key's monthly cap first.
- A paid call with no price on record
- A tool answer with isError set, beginning PRICE_UNAVAILABLE. Nothing ran and nothing was charged. Tell your person; the door refuses rather than guess a price.
- A quoteToken whose arguments, price or project policy moved, or one past its ten minutes
- A tool answer with isError set, beginning QUOTE_STALE or QUOTE_EXPIRED, with a fresh quote attached. Nothing ran and nothing was charged. Show the fresh quote and run it with its own quoteToken.
- An idempotencyKey already used for different arguments
- A tool answer with isError set, beginning IDEMPOTENCY_KEY_REUSED. Nothing ran and nothing was charged. Use a new key for new work; resend the same key only with the same arguments.
- A spend with confirm where it is not accepted: a connector sign-in, a key made or given its access since access classes existed, or any key from 4 December 2026
- A tool answer with isError set, beginning QUOTE_REQUIRED. Nothing ran and nothing was charged. Call without confirm for a quote, then again with its quoteToken, or send an idempotencyKey.
- A spend from a key whose access was set but has no monthly cap, or one that would pass a key's cap
- A tool answer with isError set, beginning CAP_REQUIRED (no cap is set) or CAP_REACHED (naming the cap, what was spent this month and what remains). Nothing was charged. Ask the key's owner to set or raise the cap in Account → API keys, or wait for the month to turn.
- A spend from a capped key or connection whose cap or month's spend could not be read at that moment
- A tool answer with isError set, beginning CAP_UNREADABLE. The spend is never checked against a guess, so nothing ran and nothing was charged. Call again in a moment with the same quoteToken or idempotencyKey.
- A spend with mandateId that the spending agreement does not cover: no idempotencyKey, a connector sign-in, another key's agreement, revoked or expired, another project, final-tier work or a run over its per-run limit, an engine outside its jurisdictions, or past its per-day or total limit
- A tool answer with isError set, beginning with a MANDATE_ code that names which (for example MANDATE_HUMAN_ONLY or MANDATE_PER_DAY). Nothing ran and nothing was charged. Read list_mandates for what the agreement covers; for anything outside it, call without mandateId for a quote, or hand the person a request_mandate link.
- A spend sent with maxCredits whose price is above it, or a maxCredits that is not a whole number of credits from 1
- A tool answer with isError set, beginning PRICE_ABOVE_MAX (with price, maxCredits and a fresh quote attached) or MAX_CREDITS_INVALID. Nothing ran and nothing was charged, and the idempotencyKey sent with it was not used up. Decide on the number: call again with a maxCredits of at least the price and the same idempotencyKey, or run the attached quote with its quoteToken and no maxCredits.
- A spend sent with maxCredits (or queue: true) and an idempotencyKey by a key holding two or more live spending agreements that could each run the call
- A tool answer with isError set, beginning MANDATE_AMBIGUOUS and naming those agreements' ids. PREVIZ never picks between two that both can. An agreement that cannot run the call (no room for its price, a tier or region it does not cover, an engine policy that changed since it was signed) is set aside first, so a person who signed a new agreement beside an old one is not asked to choose. Nothing ran and nothing was charged. Send mandateId with the one to run under; list_mandates shows what each has left.
- A spend sent with queue: true by a key with no live spending agreement covering the project, from a connector sign-in, or without your own idempotencyKey
- A tool answer with isError set, beginning QUEUE_NEEDS_AGREEMENT. A queued job waits with its price held, so PREVIZ queues only under an agreement a person signed. Where the key simply has none, the refusal carries actionUrl, the page to sign one. Nothing ran and nothing was charged. Hand the person actionUrl (or a request_mandate link) and send the call again once they have signed, or send it without queue to get a quote as before.
- A spend sent with queue: true past what the agreement, the key's monthly cap or the queue itself has room for
- A tool answer with isError set: MANDATE_EXHAUSTED, MANDATE_PER_DAY or CAP_REACHED with the numbers, or QUEUE_FULL when the key already has 60 jobs waiting. The calls that fit were accepted as jobs; this one was not, and nothing of it will run later. Nothing was charged. Read list_jobs with status queued for what is waiting. Send the rest once some have run, cancel a queued job that is no longer wanted, or hand the person actionUrl to widen the agreement.
- A queued job whose turn came after its price or the project's engine policy changed, after its agreement was revoked or expired, or after 24 hours in the queue
- Not an error on any call: the job's status reads house (grey), with a note saying why it was not started. Nothing ran, nothing was charged, and what it held under the agreement was released. The event stream sends job.house. Where a person can lift the reason (an agreement to sign again, the key's monthly cap, the key's access), the job and its event carry actionUrl and actionLabel. Hand the person actionUrl where the job carries one, then send the call again under a new idempotencyKey to run it as things stand now.
- animate_frame with dialogue and castVoice, under a spending agreement that has room for the take but not for the voice conversion it reserves beside it
- A tool answer with isError set and voiced: false: the agreement's own refusal (MANDATE_EXHAUSTED, MANDATE_PER_DAY, CAP_REACHED, QUEUE_FULL) with the numbers, and a sentence saying it was the conversion. The two prices are held together or not at all, so the take was not run either. Nothing is held and nothing was charged. Send the take without castVoice to run it alone, or hand the person actionUrl to widen the agreement and send the same call again.
- A one-step voiced take whose take landed and whose voice conversion could not run
- Not an error on any call: the voiced job lands with voiced: false and the take's own videoUrl. conversion.why says what stopped it (the take has no sound, the price or the engine policy changed, the agreement ended, the voice lane refused it, or PREVIZ could not look at the take for 24 hours because the key was frozen or its access was narrowed). The conversion was not charged and nothing is held for it. If the take itself failed, the job ends with status house and its hold released. Use the take as it is, or call convert_voice on its takeShapeId later, on its own quote.
- A spend sent again with the idempotencyKey of a job that is still waiting in the queue
- Not an error: the same job again, with status queued, its place in line and again: true. A second job is never made and nothing is charged. Read get_job until it has run, or cancel_job to take it out of the line.
- A retry of an idempotencyKey whose run has not finished, after the project's engine policy changed
- A tool answer with isError set, beginning QUOTE_STALE. The run is never continued under a policy it was not first asked under; a finished run still replays its answer. Nothing ran and nothing was charged by the retry. If the run is still open, read it with get_job and wait for it to end. Once it has ended, run the attached fresh quote, or send the request again under a new idempotencyKey.
- A refusal only a person can lift: the person's credits ran out (INSUFFICIENT_CREDITS), a monthly cap is missing or reached, a key lacks an access class, a freeze, or a spending agreement that was revoked, expired or does not cover the call
- The refusal carries actionUrl and actionLabel: the exact PREVIZ page for the person to press on, behind their own sign-in. For an agreement to sign again, the page opens with the old agreement's numbers suggested. A run answered by a job handle (a queued job, a long render) carries the same two fields on its job: get_job, list_jobs and the job's event. Nothing ran and nothing was charged. Hand the person actionUrl as it is. After they act, send the same call again with the same quoteToken or idempotencyKey. Two cases take a new idempotencyKey instead: a key whose first call already ran under an earlier agreement, and a queued job that has ended.
- A spend sent with your own idempotencyKey by an API key that has neither a monthly credit cap nor a signed spending agreement covering the call
- A tool answer with isError set, beginning CAP_REQUIRED, with actionUrl (the key's cap) and agreementUrl (the signing page). It is answered before anything is written, so the idempotencyKey is not used up. Nothing ran and nothing was charged. Hand the person either page. Once they have set a cap or signed an agreement, send the same call again with the same idempotencyKey.
- A spend under an agreement that only a person may allow: final-tier work, a single run over the per-run limit, or past the per-day or total limit
- Not an error: status input_required, with approvalId and approvalUrl (a PREVIZ page the person's bell already shows). Nothing ran and nothing was charged. Hand the person approvalUrl and call await_approval; once approved, call the same tool with the same arguments and approvalId alone. It runs once; a changed request needs a new press.
- A spend with approvalId that cannot run: still pending, declined, lapsed, for a different request, another credential's, or from a connector sign-in
- A tool answer with isError set, beginning with APPROVAL_DECLINED, APPROVAL_EXPIRED, APPROVAL_NOT_FOUND, APPROVAL_KEY_ONLY, APPROVAL_INVALID or QUOTE_STALE (pending answers input_required again). Nothing ran and nothing was charged. A decline is final; for a lapsed or changed request, call without approvalId to ask again.
- A production op from a connector sign-in, or a production this key did not start
- A tool answer with isError set, beginning with PRODUCE_KEY_ONLY (productions are driven by an API key with the produce scope) or PRODUCTION_NOT_FOUND (a key presses only the productions it started; it may read any in a project it reaches). Nothing ran. Use an API key with produce; list_productions marks the ones this key started (startedByThisKey).
- Approving words sent to a production while a price is open ("go", "approved")
- Not an error: status input_required with code WORDS_NEVER_MOVE_MONEY and the decision waiting. The words were not sent and nothing was charged. Answer the priced decision with decide {needKey, choice} under a spending agreement (mandateId), or without one for an approvalUrl a person presses on PREVIZ.
- A priced production decision with no spending agreement, or past its limits
- Not an error: status input_required with approvalId, approvalUrl and productionId. The person's press on PREVIZ answers the decision in the production itself. Nothing was charged. Hand the person approvalUrl and call await_approval; then read get_production. Nothing is run again by the agent.
- A production decision that moved on, a choice that is a person's own, or a likeness
- A tool answer with isError set, beginning with DECISION_CHANGED, PERSON_ONLY_CHOICE or LIKENESS_IS_A_PERSONS. Nothing was charged or sent. Read get_production for the decisions as they stand; a person's own choice (their billing, a handover, a likeness) is made by them in PREVIZ.
- A production PREVIZ is reading at that moment, or Produce paused on PREVIZ's side
- A tool answer with isError set, beginning with PRODUCTION_BUSY or PRODUCE_PAUSED, with retryAfterMs. Never the request's fault; nothing was charged. Send the same call again after retryAfterMs.
- A spend whose own constraints exclude an engine it may reach ({jurisdiction, noTrainingUse}), or constraints that name an unknown class or an empty list
- A tool answer with isError set, beginning CONSTRAINT_EXCLUDES (with outside: the jurisdiction classes it may reach that the constraints exclude, and trainingUnrecorded) or CONSTRAINT_INVALID. Asked before any quote, agreement, approval or render; PREVIZ never swaps in a different engine. Nothing ran and nothing was charged. Call explain_route with the same arguments and constraints: it shows each engine's class and why. Loosen the constraint, pick an alternative it lists, or ask a person to narrow the project's engine policy in PREVIZ.
- A test key naming any project but its sandbox, a live key naming a sandbox project, or a test-only tool called with a live key
- A tool answer with isError set, beginning PROJECT_UNREACHABLE (a test key reaches only its sandbox project; a sandbox project is reached only by test keys) or TEST_KEY_ONLY. Nothing ran. Call list_projects for the project this key reaches. To work on a live project, use a live key; to try a tool for free, use a test key against the sandbox.
- A webhook endpoint whose URL is not https on port 443, carries a user name, or resolves to a private address; or a call for an endpoint this key did not subscribe
- A tool answer with isError set, beginning URL_REFUSED (subscribe_webhook; nothing was subscribed), WEBHOOK_NOT_FOUND, WEBHOOK_INVALID (an unknown event kind) or WEBHOOK_LIMIT (ten endpoints per key). Give a public https URL that answers 2xx itself (a redirect is never followed), name kinds or families from the subscribe_webhook reference, and read list_webhooks for this key's endpoints.
- A read of project memory that could not be made, an entity or decision that is not in this project, or more proposals than a person can be asked to decide
- A tool answer with isError set, beginning BRAIN_UNAVAILABLE (memory could not be read just now, or this part of it is not installed yet), BRAIN_NOT_FOUND, BRAIN_INVALID or PROPOSAL_LIMIT. Nothing was written or charged. Read list_decisions and get_entity for the ids this project holds. A proposal waits for a person in PREVIZ: read the ones already waiting before sending more.
- A replay that cannot be made exactly: a job whose request is no longer kept, a tool that changed shape, a policy that now leaves it no engine, or stale work that changed since its quote
- A tool answer with isError set, beginning REPLAY_UNAVAILABLE and saying which. Nothing ran and nothing was charged; PREVIZ never runs it on a different engine or from a guess. For replay_stale, call it again for a new plan and quote. For replay_job, call the tool yourself with the arguments you want.
- A tool that a rule for agents says is never run: the organisation's rule, or the person's own
- A tool answer with isError set, beginning GOVERNANCE_DENIED, naming whose rule it is. The call is refused before its arguments are read: nothing was priced, run or charged. get_governance lists every rule that binds this credential. An owner or admin changes the organisation's rule in PREVIZ; a person changes their own in their account.
- A rule for agents asks for a person before this tool spends
- A paid run answers input_required with an approvalUrl and an approvalId, and nothing is charged. A credential a press cannot be offered to (a connector sign-in, or a free tool the rule names) is refused with GOVERNANCE_NEEDS_PERSON instead. Hand the person the approvalUrl; after their press, call the tool again with the same arguments and the approvalId alone.
- A chain PREVIZ cannot bound or price: a circle, too many steps, too deep, too wide, a tool that is not a step, a money argument inside a step, an output that does not exist, or a step with no price up front
- A tool answer with isError set, beginning CHAIN_INVALID, with issues naming each step and limits giving the ceilings. Nothing was quoted, run or charged; a chain is never quoted in part. Fix the steps the issues name (plan_chain checks a chain for free), or call the tool that cannot be a step on its own.
- More chains open at once than a key or an organisation may hold
- HTTP 429 with Retry-After and a tool answer beginning CHAIN_LIMIT. Nothing ran and nothing was charged; the same quoteToken or idempotencyKey opens the chain later. Wait for a chain to end (list_jobs), or cancel one with cancel_job.
- resume_chain on a chain that cannot carry on: cancelled, ended, past its quote, or stopped on a step that was charged or has used its attempts
- A tool answer with isError set, beginning CHAIN_STATE (or CHAIN_NOT_FOUND for a chain this credential did not start). Nothing ran and nothing was charged. replay_job on the chain's jobId quotes the same chain afresh; get_job reads what the chain already made.
- A step the project's engine policy refuses, or a balance too low
- A tool answer with isError set, giving the lane's reason. Nothing was charged. Run plan_quote or explain_route first: they report policy refusals, and the price, before anything is spent.
Protocol
The server speaks the Model Context Protocol over streamable HTTP, versions 2025-11-25 and 2025-06-18, negotiated at initialize. One JSON-RPC message per POST; every notification is acknowledged with 202 and no body. Every tool answer carries structuredContent matching the tool's declared answer, and the same JSON as its first text block.