Jobs and events
by the PREVIZ team
Which PREVIZ tools answer at once and which start work that lands later, how to poll for it, and how one cursor watches every project.
Synchronous and asynchronous tools
Most tools answer in the same call: reads in well under a second, a frame in seconds, an edit or a depth map likewise. Two kinds of work take longer and start a job instead. animate_frame submits a video take and answers with a shapeId and a where block; the take is already a card on the project's board that fills in when it lands. generate_mesh submits a 3D mesh and answers with a requestId.
A program polls each job with its own check: check_take with the shapeId, check_mesh with the requestId. Each check is free, advances the job the same way the studio's own poller does, and answers generating, done or error. On done the result is on the board and the where block opens it. On error the credits are back, the answer says refunded, and nextStep says what to change.
// 1. Start a take (after its quote): returns { shapeId, where, next }
{ "name": "animate_frame", "arguments": { "projectId": "…", "imageUrl": "…", "seconds": 5, "quoteToken": "FROM_ITS_QUOTE" } }
// 2. Poll every 10–20 s until status is "done" or "error"
{ "name": "check_take", "arguments": { "projectId": "…", "shapeId": "…" } }
// Or watch every project at once from one cursor
{ "name": "events_since", "arguments": { "cursor": "NEXT_CURSOR_FROM_LAST_CALL" } }A batch that waits its turn
Each engine lane has its own pace for one person, the same on every plan; get_account lists them under lanePace. A call past it answers RATE_LIMITED with retryAfterMs, runs nothing and charges nothing. Under a signed spending agreement a program does not have to wait and call again: send the paid call with queue: true and your own idempotencyKey, and PREVIZ accepts it at once as a job with status queued. Its price is held against the agreement from that moment and charged only when it runs. PREVIZ starts waiting jobs oldest first as each lane has room, with nobody connected.
A batch is accepted as far as the agreement has room. Thirty takes sent against room for twenty are twenty jobs accepted and ten refusals that carry the agreement's numbers; nothing is half-run later. A queued job runs at the price it was accepted at or not at all: if the price or the project's engine policy has changed by the time its turn comes, the job ends without running, nothing is charged and what it held is released. The same happens if the agreement was revoked or expired meanwhile. A freeze stops jobs from starting and ends none of them; PREVIZ sets a frozen key's waiting jobs aside so nobody else's queue waits behind them, and they start again within a few minutes of a person lifting it.
get_job and list_jobs show a queued job's place in line and an estimated start, and the event stream sends job.queued, then job.started and job.landed. cancel_job on a queued job takes it out at once at no charge. Sending the same idempotencyKey again returns the same job, never a second one. A job still waiting after 24 hours ends, says so, and releases what it held. A job that ended on something only a person can lift (credits to buy, an agreement to sign again, a key's cap) carries actionUrl and actionLabel on get_job, list_jobs and its event: the page to hand them. A queue needs a signed agreement because the agreement is the limit on everything waiting; without one the call answers QUEUE_NEEDS_AGREEMENT and the link for the person to sign.
A spoken take in a character's voice, in one step
A character's lines are spoken on camera with dialogue, and castVoice (true, or the speaker's name) turns the take's sound into the voice that character is cast to in the project. Under a signed spending agreement that is one call: animate_frame with dialogue, castVoice, your own idempotencyKey and maxCredits (or a mandateId; queue: true works too). The answer is one job, jobId, and get_job on it lands the take already in the character's voice. The take's own job rides beside it as takeJobId. There is nothing to poll and no second call. One step needs a key that also holds write, with an editor's role on the project, because PREVIZ finishes the take on the board as that key; a key that spends without them gets the two-call answer, with voice.oneStep false and the page where the person adds write.
The conversion's price is read with the take's and the two are judged as one purchase: maxCredits is held against their sum, and both prices are held against the agreement before anything runs. If either cannot be held, neither is, and nothing runs. The take is charged when it launches, as any take. The conversion is charged only when PREVIZ runs it, after the take has landed.
If the take fails, the conversion's hold is released and the job ends without a charge. If the conversion cannot run (the take has no sound, its price or the project's engine policy changed, the agreement ended, or the voice lane refused it), the job lands the take with its own sound: voiced is false, the conversion is not charged, and the note says why. convert_voice can then be called on that take later. Without a signed agreement nothing changes: the take's answer carries voice.thenCall, the convert_voice call to make once check_take says done.
One cursor for everything
events_since is a single cheap cursor across every project the key reaches: take.done, take.error, mesh.done, mesh.error, drift.warn, drift.fail and board.updated; production.turn, production.item.landed, production.question, production.ask and production.settled for productions an agent started; approval.needed and approval.decided; mandate.80pct and mandate.exhausted; and the job events of the runs its person started through the door, each with its ids and short facts, oldest first, and a nextCursor to pass back. The job, money, approval and agreement events reach only the person who pays or signed. The events are written as the work lands and read in commit order, so two that land in the same millisecond are both delivered and none is skipped. Poll it every few seconds while work is in flight and slower when nothing is.
Events: pull or stream
Instead of polling, a program can hold the event stream: GET https://mcp.aimpreviz.com?stream=events with Accept: text/event-stream and the same Authorization header, optionally with projectId and cursor as query parameters. It sends the same events as server-sent events, each with an id that is its cursor, and closes in under 140 seconds with a stream.end event naming nextCursor; reconnect with that cursor as Last-Event-ID and nothing is missed. A key may hold two streams open at once, and a stream costs a call from the key's rate limit as it opens and every ten seconds while it runs. A plain GET without ?stream=events is not the stream and answers 405.
Webhooks: PREVIZ calls you
With the webhooks access class, an API key registers an https endpoint with subscribe_webhook and PREVIZ posts events to it as they happen, within about a minute: the same kinds events_since carries, filtered by kind (take.done), by family (production.*) or by project. A delivery carries ids only: the event's kind, its cursor, its project and its ids, and webhookId, the id of the endpoint it was sent to. Read the rest through the door, with the tool the id belongs to or events_since from that cursor, under the key's own reach. No file address, price or message ever rides a delivery.
Each delivery is signed with Standard Webhooks headers: webhook-id, webhook-timestamp and webhook-signature, over the id, the timestamp and the body joined by full stops. It carries two signatures. v1 is an HMAC-SHA256 under the endpoint's own secret, which subscribe_webhook shows once (rotate_webhook_secret makes a new one, and both sign for 24 hours). v1a is Ed25519 under PREVIZ's key, published as a key set at the door's address followed by /.well-known/previz-webhooks.json, so a receiver can verify with no shared secret. That key signs every subscriber's deliveries, so a receiver that verifies v1a must also check that the body's webhookId is its own endpoint's id and refuse any other: otherwise a delivery signed for someone else's endpoint, forwarded to yours, would verify. v1 is bound to your endpoint by its own secret. Refuse a timestamp more than 300 seconds from your clock and a webhook-id you have already taken: the id is the same on every retry of one event.
Answer 2xx within ten seconds. Anything else is retried on a widening schedule for 24 hours and then listed as a dead letter by list_webhooks, with the cursor that reads the event again. A redirect is never followed and ends the delivery at once. The endpoint must be https on port 443 and resolve to public addresses, checked at subscribe time and again at every attempt. The subscribing key's access is asked again at every attempt too: a revoked key, a removed access class, a freeze, a project out of reach or a rule for agents that denies the webhook tools or events_since ends the delivery unsent. When PREVIZ itself cannot check that access for a moment, the delivery waits and is tried again, and no retry is spent. test_webhook sends one signed test delivery and answers how it went.
Productions
With the produce access class, an API key can hand PREVIZ a brief: start_production returns a productionId and a jobId, and the production plans, asks what it needs, makes frames and takes and lands them on the project's board, and keeps working with no client connected. get_production reads its turns, its items and its ledger (quoted, agreed, made, billed, returned); answer replies to its questions; say steers it; stop and resume it; list_productions lists the project's.
Words never move money. A priced decision (the plan's Go, needKey plan, or a top-up) is answered with decide under a spending agreement, or by the person's press through the approval link; a typed go or approved while a price is open is refused with input_required and the words are kept. Started with a mandateId, a production's priced decisions that fit the agreement are agreed by PREVIZ within about a minute, and the answer says autoPress: true; final-tier work and settings changes still wait for a press. The bill is what was made, settled when the production is quiet.
Chains: a pipeline you describe once
A chain is a pipeline written as data, not code: a list of steps, each one a tool call, where a step's arguments may take what an earlier step made by writing {"$from": "stepId.output"} in place of a value. A frame hands on image; a take hands on take and video once it has finished rendering; a cut hands on video; a spoken line, a sound effect and a music cue hand on audio. plan_chain lists every tool a step can be and what each hands on, checks a chain and prices it, and runs nothing.
PREVIZ refuses a chain it cannot bound before it prices anything: a circle, 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 a step (the answer says why), a money argument inside a step, and a chain inside a chain. A step whose price cannot be known up front refuses the whole chain. Nothing is ever quoted for part of one.
run_chain answers one quote for the whole chain: the sum of each step's own quote, read by the same path that tool's own quote takes, with this project's engine policy and your constraints checked step by step. Call it again with that quoteToken (or your own idempotencyKey) and PREVIZ opens the chain and answers its jobId at once. Each step then runs as an ordinary call of its tool, with its own scope and reach check, its own entry in the audit log and its own job, and it is billed only when it lands. The steps together can never cost more than the quote; a step whose price or engine policy has moved since the quote does not run.
onFail says what a step's failure does: stop (the default) stops the chain, skip carries on without the step and skips every step that needed its output, and retry_once tries it one more time when the first attempt charged nothing. Under a spending agreement every step is held to the agreement on its own, so a step the agreement leaves to a person parks the chain: status input_required with an approvalUrl, nothing run or charged for that step, and the chain carries on within a minute of their press. A chain whose total is already past what the agreement has left asks for one press for the whole chain before anything runs.
get_job on the chain's jobId reads the chain and every step: its status, its own jobId, what it was quoted and charged, and what it made. cancel_job stops scheduling at once; a step already with its engine finishes and is billed only if it lands. resume_chain carries on a stopped or parked chain inside the same total, trying again only a step whose last attempt charged nothing. replay_job on the chain's jobId quotes the same chain afresh. A key may have 3 chains running at once and an organisation 10, and a chain's quote stands for 24 hours.
No clock decides
A job's state comes only from the engine's own answer. A take that is slow is still generating; nothing on PREVIZ's side turns it red because a timer ran out. If your program needs a deadline, keep it in your program and tell your person the take is still running; do not treat a slow take as a failed one.
Cancelling
cancel_job takes a job that is still queued out of the line at no charge, and stops a production at the engine (what was made is kept and billed, the rest comes back) and cancels one of its takes; a run whose engine has no cancel answers too_late (CANCEL_TOO_LATE) with the price it is billed if it lands, and nothing if it fails; a lost run's charge is reviewed and refunded only if nothing landed.
The tools this is about
animate_frame- Animate a take
check_take- Check a take
generate_mesh- Generate a 3D mesh
check_mesh- Check a mesh
events_since- Read events since a cursor
subscribe_webhook- Subscribe a webhook endpoint
test_webhook- Send a test delivery
list_webhooks- List webhook endpoints
start_production- Start a production
get_production- Read a production
decide- Decide a production's decision
cancel_job- Cancel a job
plan_chain- Price a chain
run_chain- Run a chain
resume_chain- Carry a chain on