# speak_line: Speak a line in a character's voice | AIM Previz

https://aimpreviz.com/developers/reference/speak_line

[Previz](https://aimpreviz.com/) / [Tool reference](https://aimpreviz.com/developers/reference) / Tool reference · Shoot

# `speak_line`

Published 4 Nov 2026Updated 5 Nov 2026by the PREVIZ team

Speak a line in a character's voice

## What it does

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.

- **Access class** — `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.
- **Cost** — Without a quoteToken or an idempotencyKey it answers with a quote and runs nothing; with the quote's token, or your own idempotency key, it runs once and is charged once.
- **Project** — Takes `projectId`, an id from [list_projects](https://aimpreviz.com/developers/reference/list_projects).

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.

## Price

Reading the current price from the credit table…

Read live from the same table the tool's quote reads. The quote for your exact arguments is the number that is charged; it may combine several lines.

## Arguments

- **`projectId`

string · required** — The project, as an id from list_projects.
- **`text`

string · required** — The line, as it should be spoken.
- **`character`

string · optional** — Speak in this character's cast voice. Instead of voiceId.
- **`voiceId`

string · optional** — Speak in this voice (list_voices). Instead of character.
- **`quoteToken`

string · optional** — The quoteToken from this tool's quote: runs exactly what was quoted, once. Without it (or an idempotencyKey) the call returns a quote and runs nothing.
- **`quote_token`

string · optional** — Same as quoteToken.
- **`idempotencyKey`

string · optional** — Instead of a quoteToken: your own id for this request (1–200 printable characters). The same key with the same arguments runs once and replays its answer; with different arguments it is refused.
- **`idempotency_key`

string · optional** — Same as idempotencyKey.
- **`confirm`

boolean · optional** — Deprecated: true runs without a token for an API key until 4 Dec 2026, with a deprecation note in the answer. Never accepted for a connector sign-in. Use quoteToken.
- **`mandateId`

string · optional** — Run under a spending agreement a person signed for this API key in PREVIZ (list_mandates): sent WITH an idempotencyKey, the call runs without the quote round trip — if it fits the agreement's projects, tiers, jurisdictions and its per-job, per-day and total limits, which PREVIZ holds before anything runs. Final-tier work and a job over the per-job limit stay a person's own press.
- **`mandate_id`

string · optional** — Same as mandateId.
- **`maxCredits`

integer (1–100000) · optional** — The most this one call may cost, in credits. Sent WITH your own idempotencyKey by an API key that holds a signed spending agreement covering the project, the call is priced and — when the price is at or under maxCredits and the agreement has room — run in this one call, with no quote round trip and no mandateId needed (name one only when two agreements cover the project). A price above it answers PRICE_ABOVE_MAX with the number and a quote, runs nothing and leaves the idempotencyKey unused. Without an agreement it is a ceiling only: the call runs or quotes exactly as it would without it.
- **`max_credits`

integer (1–100000) · optional** — Same as maxCredits.
- **`queue`

boolean · optional** — true, sent WITH your own idempotencyKey by an API key that holds a signed spending agreement covering the project: the call is priced and accepted at once as a job in state queued, and PREVIZ starts it by itself when its engine lane has room — so a batch (thirty takes) needs no waiting and retrying. Its price is held against the agreement from the moment it is accepted and charged only when it runs, at that price: if the price or the project's engine policy has moved by then, the job ends without running and nothing is charged. A batch is accepted as far as the agreement has room; the rest is refused with the numbers. get_job shows the place in line and an estimated start; cancel_job on a queued job is free. Without a signed agreement it is refused (QUEUE_NEEDS_AGREEMENT): the agreement is the cap on everything waiting.
- **`approvalId`

string · optional** — Run exactly the request a person approved on PREVIZ (an input_required answer's approvalId, once await_approval reads approved): send it ALONE with the same arguments, in place of any mandateId, idempotencyKey or quoteToken. It runs once; a retry of the same call rejoins that run. Changed arguments, price or engine policy need a new press.
- **`approval_id`

string · optional** — Same as approvalId.
- **`constraints`

object · optional** — Narrow THIS call only: {jurisdiction: one class or a list (US, EU, UK, IL, CN), noTrainingUse: true}. It can only narrow the project's engine policy, never widen it. If any engine the call may reach breaks it, the call is refused (CONSTRAINT_EXCLUDES) before anything is quoted, held or run — PREVIZ never swaps in a different engine. An engine whose jurisdiction is not established is outside every jurisdiction constraint; noTrainingUse holds only for an engine whose company's no-training term PREVIZ has on record.
- **`label`

string · optional** — Your own word for the batch this run belongs to (pilot, scene 2, fixes), up to 60 characters. Returned on the job; list_jobs filters by it and sums credits per label. It never changes what runs or what it costs: a quote taken without a label runs with one.
- **`mode`

one of fast, balanced, deep · optional** — fast | balanced | deep (default balanced). Every quote prices all three; a mode the project's engine policy does not allow is refused with the reason (MODE_UNAVAILABLE), never run as another.
- **`dryRun`

boolean · optional** — true: answer what this call WOULD do — the route its engines would take under the project's policy, its price in every mode, whether it writes — and run nothing: nothing is written, nothing is charged.

Unknown arguments are refused by name rather than ignored, so a misspelling never runs quietly.

## Answer

The fields this tool's answer declares. They arrive as structuredContent, and as the same JSON in the first text block for clients that read text.

- **`quote`** — Present when the call carried no quoteToken or idempotencyKey: the price read from the credit table (credits, lines, detail, note) and, when this door can sign one, quoteId, quoteToken and expiresAt; on a tool with modes, modes {fast, balanced, deep} — each mode's credits, whether the project's policy allows it, what it delivers and, when the door can sign, its own quoteToken (send it with that mode). Nothing ran and nothing was charged.
- **`keyBudget`** — For a key with a monthly cap: monthlyCap, spentThisMonth, remaining.
- **`audioUrl`** — The spoken line, levelled, in project storage.
- **`durationMs`** — Its measured duration (null when it could not be measured).
- **`voice`** — Who performed it: character, voiceId, via (lock = the character's cast voice, request = the voiceId you named) and lockRead (hit = the cast was read and honoured).
- **`loudness`** — targetLufs (−23 integrated), truePeak (−1 dBTP), measuredLufs (what the levelling reported, or null when it reports nothing) and leveled (false when levelling could not run: the file is the engine's own level).
- **`creditsDeducted`** — Credits the call charged.
- **`where`** — Where the output lands: project, room, onBoard, openUrl (the PREVIZ address that opens the room on it) and assetUrl (the file).
- **`note`** — A sentence for the agent about what the answer means or what to do next.
- **`jobId`** — The run's job (S4): every run has one, written before any engine is called. When the answer is a handle (status running), get_job {jobId} returns the result once it lands.
- **`status`** — Present on a handle: running, or queued (accepted with queue:true and waiting for its engine lane's pace; PREVIZ starts it by itself). get_job reads it on to landed, failed (the engine refused; red), house (stopped on PREVIZ's side; grey, never the request's fault) or cancelled (taken out of the queue; grey). input_required: nothing ran and nothing was charged — a person's press on PREVIZ is needed first (approvalUrl).
- **`queue`** — On a queued job: position (its place in the person's line on that engine lane, from 1), estimatedStartAt (an estimate from the lane's pace) and waitingOn.
- **`creditsQuoted`** — On a queued job: the price it was accepted at, held against the spending agreement and charged only when it runs.
- **`approvalId`** — On input_required: the request a person is asked to approve. await_approval {approvalId} waits for the press; then call again with the same arguments and approvalId.
- **`approvalUrl`** — On input_required: the PREVIZ page to hand the person (their bell already shows it). Behind their own sign-in; only they can press there.
- **`reason`** — On input_required: why a person must press — over_mandate, human_for:final, human_for:over_per_job, or final_gate (the project approves shots before final renders).
- **`pollAfterMs`** — On a handle: how long to wait before asking get_job.
- **`quoteId`** — The quote (or idempotency key) this run was charged under; a retry with the same token or key replays this answer.
- **`replayed`** — true when this is the stored answer of a run that already finished: nothing ran and nothing was charged again.
- **`inProgress`** — true when the run is still going — the same quote already running, or a job handle: nothing was charged again; call again with the same quoteToken or idempotencyKey (or get_job {jobId}) for its answer.
- **`deprecation`** — Present on a run confirmed by the deprecated confirm:true: when it stops working and what to send instead.
- **`mandate`** — On a run under a spending agreement: mandateId, upTo, used, remaining, today, perDayMax, expiresAt — the agreement after this run's hold.
- **`receipt`** — On a landed run: quoted (the price PREVIZ read before it ran), charged (what the engines' lanes charged), maxCredits (the ceiling the call carried, when it carried one), mandateId (the spending agreement it ran under, when it ran under one) and policyVersion (the engine-policy fingerprint it was bound to).
- **`actionUrl`** — On a refusal only a person can lift (credits, a monthly cap, a key's access, a freeze, a spending agreement): the exact PREVIZ page to hand them. Behind their own sign-in; nothing in the address is a credential.
- **`actionLabel`** — What the person does on actionUrl, in a few words.
- **`label`** — The run's label, when the call carried one.
- **`retryAfterMs`** — On RATE_LIMITED: how long to wait before calling again with the same quoteToken or idempotencyKey. limit says whose: credential, organization, or lane (the engine lane's own per-person pace).
- **`mode`** — The quality mode this call was made in (fast, balanced or deep), after any deprecated alias was read.
- **`working`** — How the call worked with the person: ask_first, within_agreement, dry_run or sandbox.
- **`modeNotes`** — Deprecations and defaults the call relied on, in words (an old ladder word, a defaulted mode).
- **`delivered`** — Present when what is delivered differs from what was asked (a Fast take at 1080p is 768p; Deep on a mesh runs Balanced): said here and on the quote before anything is charged.

## Behaviour hints

The hints the tool declares to clients, so an agent can decide what needs a person's approval.

- Read-only

  No
- Destructive

  No
- Idempotent

  No
- Reaches outside PREVIZ

  No

## Call it

The JSON-RPC message, then the same call over HTTPS. Placeholders are in capitals.

tools/call: the quote (nothing runs)

```
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "speak_line",
    "arguments": {
      "projectId": "YOUR_PROJECT_ID",
      "text": "…"
    }
  }
}
```

tools/call: the spend, after you have read the quote

```
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "speak_line",
    "arguments": {
      "projectId": "YOUR_PROJECT_ID",
      "text": "…",
      "quoteToken": "QUOTE_TOKEN_FROM_THE_QUOTE"
    }
  }
}
```

curl

```
curl -s https://mcp.aimpreviz.com \
  -H "Authorization: Bearer $PVZ_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"speak_line","arguments":{"projectId":"YOUR_PROJECT_ID","text":"…"}}}'
```

The spend call runs only what its quote priced, inside ten minutes. Sent twice, by hand or by a client that retries after a timeout, it is one run and one charge: the second send joins the first, or gets its answer back. A render that outlives the wait answers a jobId; read it with get_job rather than resending ([Quotes and money](https://aimpreviz.com/developers/concepts/money)).

From an agent client you never write this by hand: connect it once ([Claude Code](https://aimpreviz.com/developers/connect/claude-code), [Cursor](https://aimpreviz.com/developers/connect/cursor), [TypeScript or Python](https://aimpreviz.com/developers/connect/http)) and ask for what you want.

## When it fails

What the door answers instead, 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.

## Related

### Concepts

- [Quotes and money](https://aimpreviz.com/developers/concepts/money)

### Also in shoot

- [`generate_frame`](https://aimpreviz.com/developers/reference/generate_frame)
- [`edit_frame`](https://aimpreviz.com/developers/reference/edit_frame)
- [`animate_frame`](https://aimpreviz.com/developers/reference/animate_frame)
- [`check_take`](https://aimpreviz.com/developers/reference/check_take)
- [`estimate_depth`](https://aimpreviz.com/developers/reference/estimate_depth)
- [`decompose_frame`](https://aimpreviz.com/developers/reference/decompose_frame)
- [`inpaint_frame`](https://aimpreviz.com/developers/reference/inpaint_frame)
- [`relight_frame`](https://aimpreviz.com/developers/reference/relight_frame)
- [`split_plate`](https://aimpreviz.com/developers/reference/split_plate)
- [`generate_mesh`](https://aimpreviz.com/developers/reference/generate_mesh)
- [`check_mesh`](https://aimpreviz.com/developers/reference/check_mesh)
- [`start_production`](https://aimpreviz.com/developers/reference/start_production)
- [`say`](https://aimpreviz.com/developers/reference/say)
- [`answer`](https://aimpreviz.com/developers/reference/answer)
- [`decide`](https://aimpreviz.com/developers/reference/decide)
- [`stop`](https://aimpreviz.com/developers/reference/stop)
- [`resume`](https://aimpreviz.com/developers/reference/resume)
- [`get_production`](https://aimpreviz.com/developers/reference/get_production)
- [`list_productions`](https://aimpreviz.com/developers/reference/list_productions)
- [`production_settings`](https://aimpreviz.com/developers/reference/production_settings)
- [`queue_edit`](https://aimpreviz.com/developers/reference/queue_edit)
- [`get_take_frame`](https://aimpreviz.com/developers/reference/get_take_frame)
- [`convert_voice`](https://aimpreviz.com/developers/reference/convert_voice)
- [`get_take_audio`](https://aimpreviz.com/developers/reference/get_take_audio)
- [`separate_audio`](https://aimpreviz.com/developers/reference/separate_audio)
- [`generate_sfx`](https://aimpreviz.com/developers/reference/generate_sfx)
- [`generate_music`](https://aimpreviz.com/developers/reference/generate_music)
- [`replay_stale`](https://aimpreviz.com/developers/reference/replay_stale)
- [`replay_job`](https://aimpreviz.com/developers/reference/replay_job)
- [`run_chain`](https://aimpreviz.com/developers/reference/run_chain)
- [`resume_chain`](https://aimpreviz.com/developers/reference/resume_chain)
- [`run_template`](https://aimpreviz.com/developers/reference/run_template)

[All tools](https://aimpreviz.com/developers/reference) [Developers home](https://aimpreviz.com/developers) [Mint a key](https://aimpreviz.com/account)
