AI operations and Tokens

Paid AI through the API, max_tokens, prices, per-key caps and what a sandbox does instead.

Some endpoints run NOWScale's AI and spend the Workspace's Tokens, exactly as the same feature in the app does. Your key needs the ai:use permission. Today the API offers drafting a reply to a comment (POST /v1/ai/comment_replies); more operations follow.

Every paid call states its limit

Send max_tokens, the most the call may cost, in Tokens:

curl https://api.nowscale.com/v1/ai/comment_replies \
  -H "Authorization: Bearer $NOWSCALE_KEY" \
  -H "Idempotency-Key: 3f2a9c4e-1b7d-4e6a-9c2f-8d1e0b4a7c55" \
  -H "Content-Type: application/json" \
  -d '{"comment": "What camera do you use?", "video_title": "My studio tour", "max_tokens": 1}'

Without max_tokens the call is refused with 402 max_tokens_required and nothing is charged. The problem's quote tells you the price: its operation and tokens, a decimal string.
When the price is higher than max_tokens, the call is refused with 402 max_tokens_exceeded and the same quote.
Otherwise the operation runs at that price, and the response's tokens says what was charged.

The price is fixed when the call starts: if it changes before the charge, the call is refused rather than charged more. Send an Idempotency-Key so a retry after a network error never charges twice.

Caps per key

When you create a key with the ai:use permission in Settings > API keys, you can give it a daily and a monthly Token cap. A call that would pass a cap is refused with 402 key_spend_cap_reached, which names the cap and the window (day or month, counted in UTC). A call that fails gives its reservation back.

The Workspace's own balance, plan allowance and Extra Usage settings still apply first: 402 insufficient_balance or 402 overage_disabled mean the Workspace, not the key, is out of Tokens.

In a sandbox

AI in a sandbox is simulated: the answer is a realistic placeholder marked "simulated": true, no model runs and nothing is charged (tokens is "0"). Prices, max_tokens and key caps behave exactly as in live mode, so you can test the whole flow. The sandbox's test balance only refuses a call it could not cover.