Spend confirmations

Nothing in Probably's API spends credits in one call. Paid work is prepared first, shown to the person who pays, and started only by a separate confirmation, so an agent can't overspend by retrying, looping or following instructions hidden in a brief.

Prepare, then confirmCopy Anchor Link

prepare_video creates the video as a draft straight away, so its confirmation names a video; confirming starts its first run. Audience research and a campaign's batches and openings run on a Space instead: confirm_spend answers them with videoId null and the spaceId, and a result naming the researchId that get_audience_research follows, the batch's body videos, or the openings by their ad codes.

What the preview saysCopy Anchor Link

A new run's preview says whether the organization's credits cover the work (fits), the credits available (availableCredits) and whether it starts with the free first draft (freeDraft). Variants', a change's and a campaign's batch and openings previews say the same, a change's as covered.

Its quote is the price: what confirming charges, fixed when the work was prepared.

• priceCredits is the whole price, charged line by line as each stage is accepted: lines lists them (script, stills, voice, clips, finish), each { line, credits }. A change lists only the lines of the stages it makes again, and a variant leaves out the stages it keeps.
• mostCredits is the most this work can be charged: its price plus every correction round its limits allow. Lead with it, as the studio does ("Up to 1,747 credits"), so the person never pays more than the number they agreed to.
• corrections is what correction rounds may add: when the critics send a stage back, each round costs its line's price in rounds, at most maxRoundsPerStage a stage and maxRounds a run, and never more than maxCredits in all. A run that needs none is charged priceCredits and nothing more.
• Retries after a provider failure, refusals, and the models and routes Probably picks never change it.
• A confirmation is charged the price its preview showed, even if prices change before you confirm. One prepared before prices were fixed is refused with price-changed: prepare it again to see the price.

get_video shows what a run has been charged against its price (run.charges: priceCredits, chargedCredits, each line charged as its stage was accepted, and each correction round charged), and what a change waiting on it costs.

Work is charged at fixed prices once Probably switches them on. Until then quote is null, and the preview shows the meter's estimates instead: a run's or variants' estimatedCredits, shown only to the organization's staff, and a change's credits per step and expectedCredits. A metered run holds its expected cost from the balance; each paid call then charges what it cost at Probably's rates, failed and refused calls charge nothing, and what the run didn't use is released when it ends.

The stage tools, research, brainstorm, write_script and review, run one stage of a video on its own: on a video you name (videoId, using its brief) or on a draft they make from brief, never both. A stage's preview shows its cap (capCredits), whether the credits cover it (fits) and the credits available. Confirming holds the cap and answers with the stage's runId; the stage charges its passes as they run, never above the cap, and the rest is released when it settles (see Pricing). get_stage reads its status, what it charged and what it delivered, and the stage.delivered event says when it's done. Stage primitives chains them on one video.

Audience research's preview (prepare_audience_research) shows its ceiling (ceilingCredits), the most it can charge; its estimate (estimatedCredits), what a run usually costs; the credits available and whether they cover the ceiling (fits). Confirming holds the whole ceiling, within your spend caps; a run charges what its calls cost, never above the ceiling, the rest is released when it ends, and one you stop pays only for the calls it made. Past the ceiling, Probably pays, and a run never pauses for credits midway, though it does pause with audience_research.paused if a spend cap is lowered below it, continuing once it's raised. Stage primitives follows it to its segments.

RulesCopy Anchor Link

• A confirmation expires after 15 minutes. A stale preview never spends: confirming later answers confirmation-expired; prepare again. For a draft prepare_video already made, call prepare_regenerate with its videoId for a fresh confirmation; prepare_video with a new requestKey makes another draft.
• Confirming twice starts one thing. Two confirm_spend calls with the same ID, even at once, start the work once, and both answer with what it started.
• Shortfalls wait. If the credits or a spend cap don't cover the work when you confirm, the answer is not-enough-credits or spend-cap-reached and the confirmation stays pending: confirm it again once an admin adds credits or raises the cap, before it expires.
• A price prepared on the meter is refused. A confirmation prepared before work was charged at fixed prices answers price-changed; prepare it again to see the price.
• Work that moved on is refused. If the change or draft was edited since you prepared it, or the line already started a version, the answer is change-outdated or a conflict; read the video and prepare again.
• Only the connection that prepared it can confirm it. Another connection's ID reads as not found.

Without the spend permissionCopy Anchor Link

A connection or key that may make changes but not spend still prepares work. Its answer carries a confirmUrl, a page in the studio where the person sees the same preview and confirms it themselves. Send them the link; confirm_spend isn't offered.

A connection with the spend permission gets no link (confirmUrl is null): the person agrees in your app, and your app calls confirm_spend for them.

LimitsCopy Anchor Link

Confirmations count against the spendConfirmations rate limit, repeats included (see Rate limits). Spend caps, balances and the free first draft apply exactly as in the studio, because the same services run.