What API calls cost, and how to cap them

The API spends the same credits as the site, at the same prices: see What a run costs, and where you see the price. Reading your account, listing models and boards, bringing files in and pricing a run cost nothing.

The price comes first

Nothing runs until your call names the price. Every address that spends has a twin ending in /quote that takes the same body and answers the price, your balance and any notes the studio's page would show. Send the same body to the address itself with confirmCredits set to that price, and the run starts, charged that price.

• If the price has gone up since you asked, nothing runs. The answer says price_changed and carries the new price.
• If it has come down, the run goes ahead at the lower price, as long as your confirmCredits was the figure quoted for that request.
• If you leave confirmCredits out, nothing runs. The answer says confirm_credits_required and carries the price.
• If your balance is too low, nothing runs, and the answer says insufficient_credits.

A message to the Creative Director is priced the same way: its quote is the most the reply's first step can cost, and it is settled to what the reply used.

The same request twice

Send an Idempotency-Key header with every run, a new one for each request (a UUID will do), and the same one for a request's quote and its run. If your server sends the same request again within 10 minutes, for instance because it never heard back, it gets the first answer back, and nothing runs or is charged a second time. The same key with a different body is refused.

A daily cap for each key

A daily cap is the most one key may spend in a day, from midnight to midnight UTC. Keys have no cap unless you give them one. Set it when you make the key, or later in Settings → API: press the key, type a number under Daily cap and save. A run that would take the key past its cap doesn't start, and the answer says daily_cap_reached.

When a run fails

A run that fails is not charged in most cases: its credits go back, as they do on the page. The job says whether it was charged. See My video failed. Did I lose my credits?.