Can you top up Sume credits through the API? What the API does cover

No. Sume has no public API endpoint that tops up a wallet. A top-up is a dashboard operation: you start a Stripe-backed checkout in Billing and subscription, and after it completes the usage ledger shows the top-up and the new balance (read 2026-10-06). The public Developer API gives you two read-only calls for money, GET /v1/balance and GET /v1/usage, and both are scoped to the workspace of the API key.

That shapes how you build. An agent or a cron job cannot buy its way out of a short balance, so it has to notice the problem early and hand it to a person. The design below is a guard that runs before you submit, and an alert that fires with days to spare.

What the API does when the balance is short

A generation submit reserves the billable amount first. If the spendable balance cannot cover it, the request fails with 402 insufficient_credits before any provider work starts, and nothing is charged. When the job succeeds Sume captures the reserve, and when it fails the reserve is refunded. So a balance of $5.00 with $4.00 held for queued jobs has $1.00 to spend, and a $2.00 submit fails.

This matters for batches. A batch of 50 jobs at $1.25 needs $62.50 of free balance if you submit them all, because each accepted job holds its price while it waits in the queue. Ask for the balance, subtract what is held, and submit only the jobs that fit.

• Read the balance before the batch, not after the first 402.
• Treat 402 as a stop, not a retry. Retrying the same job with the same key will fail the same way until someone tops up.
• Keep a daily read of the balance, and alert at a runway in days, not in dollars.
• Do not rely on a ledger read as a lock. Another job can reserve between your read and your submit.

A submit guard that never hits 402

The function below takes a free balance and a list of job prices in cents, and returns how many jobs to submit and how much to top up for the rest. Feed it the balance field from the OpenAPI schema of GET /v1/balance.

def admit(balance_cents: int, prices_cents: list) -> dict:
    admitted, spent = 0, 0
    for price in prices_cents:
        if spent + price > balance_cents:
            break
        spent += price
        admitted += 1
    rest = sum(prices_cents[admitted:])
    return {"submit": admitted, "hold": spent, "top_up_for_rest": rest}


jobs = [125] * 50
print(admit(5000, jobs))
print(admit(7000, jobs))

Who tops up, and when

Give the top-up to a named person and write the trigger down. A workable rule is to top up when the balance covers fewer than 10 days at the last seven days of spend. The spend comes from GET /v1/usage, and the days come from the balance divided by the daily average. If the rule fires, send a message with the amount needed to reach 30 days.

For a team on a plan the limits are separate. Concurrency belongs to the plan and a top-up does not raise it, so a larger balance does not make a batch run faster. The billing docs, the API reference, the error table and the admission rules are the sources for each of these points.

A weekly routine for the person who tops up

Run the same three checks every Monday. First, read the balance and write it down. Second, read the last seven days of usage and compute the average daily capture, ignoring refunds, since refunded jobs cost nothing. Third, divide the balance by that average and compare the result with your trigger. If the runway is under 10 days, top up in the dashboard that day, and note the amount in the same place you keep the balance.

Keep planned spikes out of the average. A launch week with 300 clips at $1.25 is $375.00 of captures, and a runway computed from a quiet week will say you are fine when you are not. Add the planned spike to the expected spend, then top up before it starts, because a 402 in the middle of a batch leaves a half-finished set of clips and a person hunting for a card at the worst time.

Finally, make the failure loud. If a job comes back 402, post the workspace name, the price you tried to reserve and the free balance to a channel a human reads. That one message is the whole recovery plan, since the API cannot do the repair itself.