Billing & retention

Who pays, price estimates and dry runs, per-key credit caps, and how long results are kept.

#Credits

API calls spend the credits of the AITOPIA account that owns the key, at the same prices as the AITOPIA app; there is no separate API price list. Listing models, reading requests, the balance and uploads are free.

Check the balance with GET /v1/account/balance:

JSON

{
  "credits": 940,
  "unlimited": false,
  "paid_credits": 900,
  "daily_credits_remaining": 40,
  "daily_allowance": 50
}

Field	Description
`credits`	Credits available for generation. `null` on an unlimited plan.
`unlimited`	`true` on an unlimited plan.
`paid_credits`	Purchased credit balance, when known.
`daily_credits_remaining`	Free daily credits left today, when known.
`daily_allowance`	Size of the daily allowance, when known.

A run the account cannot afford is refused with 402 INSUFFICIENT_CREDITS and nothing runs.

#Prices and estimates

GET /v1/models and GET /v1/models/{model_id} show each model's price: credits, and where it applies min / max or per_second (for duration-priced models).
Requests carry credits_estimated, the price computed before the run. Treat every credit figure in the API as an estimate; the charge itself is made by AITOPIA's billing for the run.

#Dry runs

Add ?dry_run=true (also 1 or yes, any case) to POST /v1/models/{model_id}, POST /v1/edit or POST /v1/batch. The input is validated and priced, but nothing runs, nothing is stored and nothing is charged. The answer is 200:

JSON

{
  "dry_run": true,
  "endpoint": "google/nano-banana-2",
  "credits_estimated": 4,
  "affordable": true,
  "credits_available": 100
}

Field	Description
`credits_estimated`	Estimated credits, or `null` when unknown.
`affordable`	Whether the account can pay for it, when known.
`credits_available`	Credits available for generation, or `"unlimited"`.
`complete`, `basis`	How complete the estimate is and what it is based on, when the price source says so.
`plan_token`, `plan_token_expires_in_sec`	`POST /v1/edit` only, see below.
`items`	`POST /v1/batch` only: per item `index`, `kind`, `model_id`, `credits_estimated`, and an `error` for an item that would be refused.

dry_run=false, 0 or no (or no parameter) runs normally. Any other value answers 400 INVALID_INPUT and nothing runs.

#Fixed-price edits

An edit's dry run returns a plan_token. Send it back with the same asset_url and instruction to run exactly the plan that was priced:

Shell

curl -X POST "https://api-live.aitopia.ai/v1/edit" \
  -H "Authorization: Key $AITOPIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"asset_url": "https://cdn.aitopia.ai/...", "instruction": "remove the background", "plan_token": "<plan_token from the dry run>"}'

A plan token runs once, within 1 hour. If the price has changed meanwhile the run is refused with 409 PRICE_CHANGED; an expired or used token gives 409 PLAN_EXPIRED. Nothing is charged in either case. Without a plan token, max_credits refuses any plan above that total with 402 OVER_BUDGET.

#Monthly credit cap

A key can have an optional monthly credit cap, set under profile menu > API keys on aitopia.ai. It limits how much that one key can spend; the account's other keys are not affected.

The month is the calendar month in UTC.
Usage is the sum of the credits of this key's requests created this month (the run's recorded credits, otherwise its estimate). Failed and cancelled requests do not count.
Before a run, the API prices it with a dry run. If usage plus the estimate would pass the cap, the submit is refused with 402 KEY_CREDIT_CAP_REACHED and nothing runs. Reaching the cap exactly is allowed.
A model whose price cannot be estimated is allowed while usage is still under the cap.

#Cancelling and charges

Cancelling stops billing only for runs that were really cancelled. When the answer is cannot_cancel, will_be_charged says whether the run will still be billed. See Cancelling.

#Retention

Requests and their results are kept for 30 days after they were created, then deleted. Read or store what you need before then.
Generated files are hosted on the AITOPIA CDN; the URLs are in output. When aitopia_url is present it opens the result in the AITOPIA app.
The stored copy of your input leaves out large base64 data; your key is never stored in plain text.