Quotes and money
by the PREVIZ team
How a paid PREVIZ tool answers with a quote and spends nothing, how its quote token or your own idempotency key turns it into exactly one charge, and what an agent can and cannot buy.
A paid tool quotes, then runs once
Reads are free. Every tool that can spend credits, called without a quoteToken or an idempotencyKey, answers with a quote and runs nothing: the credits, a line per priced part (a tier, a resolution, a surcharge), a sentence saying that nothing ran and nothing was charged, and a quoteToken that holds for ten minutes. Send the same call again with that quoteToken and it runs exactly what was quoted, at that price, once. If the arguments, the price or the project's engine policy moved since the quote, nothing runs and a fresh quote is attached (QUOTE_STALE); a token past its ten minutes gets a fresh quote too (QUOTE_EXPIRED).
A pipeline that cannot carry a quote back can send its own idempotencyKey instead: 1 to 200 printable characters naming this one request. The same key with the same arguments runs once; the same key with different arguments is refused with IDEMPOTENCY_KEY_REUSED. When this door cannot sign tokens, its quotes say so and carry none, and an idempotencyKey is the way to spend.
confirm set to true, the older way to spend, still runs until 4 December 2026 for an API key made before access classes existed, and every answer it gets carries a deprecation note. It is never accepted for a connector sign-in or a key made or given its access since access classes existed (QUOTE_REQUIRED), and a retry of it cannot be told from a new request.
The numbers come from the same price table the studio's own buttons charge from, read at the moment of the call. No price is typed into a tool's description, and the reference pages read the live table too. When the table has no row for something, the door refuses with PRICE_UNAVAILABLE instead of guessing a number the render would then disagree with.
{
"jsonrpc": "2.0", "id": 7, "method": "tools/call",
"params": {
"name": "generate_frame",
"arguments": { "projectId": "YOUR_PROJECT_ID", "prompt": "rain on a neon street", "tier": "cinematic" }
}
}
// → structuredContent.quote: { credits, lines, detail, note, quoteId,
// quoteToken, expiresAt } and, for a key with a cap,
// keyBudget: { monthlyCap, spentThisMonth, remaining }.
// Nothing ran and nothing was charged. Send the same call again with
// "quoteToken": the token from the quote, to spend and render once.A retried spend is the same spend
A call that carries a quoteToken or an idempotencyKey is one run however often it is sent. A retry after a timeout or a dropped connection joins the run that is already going and answers inProgress, with nothing charged a second time; a retry after it finished gets the same answer back. Many clients, agent frameworks and automation tools retry a failed request on their own, and with a token or a key that is safe. Only a run the lanes refused, and refunded, may be run again under the same token inside its ten minutes.
A render that outlives the time a client waits answers a job handle at once: inProgress true, a jobId and status running. The work carries on without the connection, and get_job with that jobId returns the tool's own answer when it lands, with a receipt of what was quoted and what was charged; list_jobs lists the runs this key started. If the worker running it is lost, PREVIZ's sweeper picks the job back up under the same id, so it lands once or ends saying why.
Spending agreements and approvals
A person can sign a spending agreement for one of their API keys on PREVIZ: which projects, an up-to, a most-per-job and a most-per-day, the tiers it covers and an expiry within 30 days. request_mandate gives an agent a PREVIZ link to hand its person; it never grants one itself, and list_mandates and get_mandate read what this key holds. A paid call sent with a mandateId and your own idempotencyKey then runs without the quote round trip while it fits: the agreement's limits, the key's cap and the project's engine policy are all held by PREVIZ before anything runs. Final-tier work and a run over the per-job limit stay a person's own press, and an agreement spends only while its key still holds spend.
Inside an agreement a call runs in one step. Send maxCredits, the most that one call may cost, with your own idempotencyKey: PREVIZ prices the call the way it prices every quote, finds the key's one live agreement that covers the project, and runs it when the price is at or under maxCredits and the agreement has room. The answer carries a receipt with the price that was quoted beside what was charged. If the price is higher, the answer is PRICE_ABOVE_MAX with the number and a quote; nothing runs and the idempotencyKey is not used up. A retry with the same key is the same run, never a second charge, and it stays under the agreement its first call ran under. An agreement cannot be widened, so a person who needs more signs a new one and the earlier one stays live beside it: where more than one covers the project, PREVIZ sets aside the ones that cannot run this call (no room for its price, a tier or region they do not cover, signed under an engine policy the project no longer has) and runs under the one that can. Only where two could both run it does the call name one with mandateId. A retry of a run that has not finished is refused if the project's engine policy changed in between, so nothing runs under a policy it was not asked under. Without an agreement nothing changes: a call quotes first, and maxCredits is only a ceiling. get_account shows a key's live agreement, what is left of it and when it ends.
A call past what an agent may do alone answers status input_required with an approvalId and an approvalUrl: nothing ran and nothing was charged, and the person's bell already shows it. The page shows the tool's own name, the project, the exact price and why it asks, never anything the agent wrote, and only a person signed in to PREVIZ in the last ten minutes can press Approve or Decline there. await_approval waits for that press. A single render then runs when the same tool is called with the same arguments and the approvalId, once; a production's decision needs no re-run, because the person's press answered it in the production itself, so read get_production. A decline is final for that request, and an approval lapses after a day.
Price a whole plan before the first step
plan_quote takes up to 40 steps, each a tool and its arguments, and prices every one through the same path that tool's own quote uses, so the plan's total is the number the charges will read. It also reports which steps the project's engine policy would refuse, and whether the total would exceed a capped key's remaining budget. It is free. An agent that plans a sequence should price it here, show its person the total, and then run each step with its own quote.
What is charged, and what comes back
A run is charged by the lane that does the work, exactly as a press of the same button in the studio would be, and the answer names creditsDeducted. A take or a mesh that fails on the engine gives its credits back, and its check says refunded. An edit whose result came back unchanged from its source is refunded and says so. A best-of frame (keepBestOf 2 or 3) renders every candidate and is charged for every candidate; the quote counts all of them before you run it.
A refusal never charges: an unreachable project, a missing access class, a policy refusal, a cap reached, a missing price, a stale or expired quote or an invalid argument all answer before a credit moves.
What an agent cannot do
An agent cannot buy credits, change a plan or sign a spending agreement on its person's behalf; those happen on PREVIZ's own pages. A key's spend is bounded by the cap its owner set, and by any spending agreement its owner signed for it. A key given the produce access class can drive a production (Produce) through this door, under the same rules: words never move money, and a priced decision is pressed by decide under a spending agreement, or by the person on PREVIZ.
The tools this is about
plan_quote- Price a plan
generate_frame- Generate a frame
animate_frame- Animate a take
get_job- Read a job
list_mandates- List spending agreements
request_mandate- Ask a person for a spending agreement
await_approval- Wait for a person's press