402 on an 8-second 720p Gemini Omni clip: the balance must cover $1.00

An 8-second 720p clip on gemini-omni-flash-1.1 needs $1.00 of balance at submit. Sume reserves the estimated amount when it accepts a paid job, and if it cannot reserve it the call fails with 402 insufficient_credits before any provider work starts. For a batch of 25 clips the same check needs $25.00, so read GET /v1/balance first and submit only what the balance covers.

The arithmetic

Sume bills provider list times 1.25, rounded up to whole cents. For Gemini Omni Flash 1.1 at 720p the catalog list is $0.10 per second, and the clip is 3 to 10 seconds.

Reservation, capture and refund

The reservation is held at submit. A successful completion captures it. Failed jobs and failed queue admissions release or refund the reservation where applicable. The docs describe the 402 fix as waiting for included Gen$, upgrading the plan, or submitting a cheaper request, and they say not to invent prepaid top-ups.

Gate the batch

The check below computes the batch cost from a per-clip price in cents and stops before submit when the balance is short. Read the balance field name from your own response, since the docs describe the endpoint only as the available balance in USD.

import os
import httpx

PRICE_CENTS = {3: 38, 5: 63, 8: 100, 10: 125}  # gemini-omni-flash-1.1, 720p

def affordable(balance_usd: float, seconds: int, clips: int) -> bool:
    need = PRICE_CENTS[seconds] * clips / 100
    print(f"need ${need:.2f}, have ${balance_usd:.2f}")
    return balance_usd >= need

key = os.environ.get("SUME_API_KEY", "")
if not key:
    raise SystemExit("set SUME_API_KEY")
r = httpx.get("https://api.sume.com/v1/balance",
              headers={"Authorization": f"Bearer {key}"}, timeout=20)
r.raise_for_status()
data = r.json()
print(data)  # find the USD balance field, then pass it below
print(affordable(100.0, 8, 25))  # need $25.00, have $100.00

Do not retry a 402 in a loop

A 402 will not clear by itself. Stop the batch, record how many items were submitted, and resume with the same keys after the balance changes.

Rounding and what the reserve really is

Billing rounds up to the cent per request, not per second. That is why a 3-second clip, whose exact figure is $0.375, bills $0.38, and why batches are cheaper to estimate by the request than by total seconds. For 25 clips of 3 seconds the bill is 25 x $0.38 = $9.50, while 75 seconds at the exact rate would be $9.375.

The reservation is the estimate at submit. If the final cost is lower, the reserved amount is what the docs call the estimate, and usage shows the billed amount. Compare usage.cost on completed jobs with your own table to catch a mistaken assumption early.

Check the balance once at the start of a batch, then again after every wave, since other jobs may spend from the same workspace balance. If a 402 still arrives mid-batch, stop submitting, record the index of the first unsent item, and resume from there with the same keys. The jobs that were accepted continue to run to completion.