Sociaro

Balance and billing

Your organisation has a balance. Requests draw it down; top-ups build it up. There is no monthly reset and nothing expires — what you paid for stays yours until you use it.

Where the number comes from

balance = everything paid in − everything spent

Both sides count from the beginning, not from the first of the month. That is why the remainder carries over on its own: it is not stored anywhere to be reset, it is the difference between two running totals.

The console shows the balance on every page. This month on the Keys tab is a separate figure, there to answer "how fast are we going" — it takes no part in the calculation.

Reading it from code

One call, one number — what this key can still spend:

curl https://api.sociaro.com/v1/balance -H "Authorization: Bearer $SOCIARO_API_KEY"
{"remaining": 312.58}

US dollars, and the same figure the console shows: your organisation's limit minus what it has spent. That is the only balance there is — keys and teams do not carry separate budgets, so every key in your organisation reads the same number.

When there is nothing left you get a 429 and no number. That is deliberate. The figure would be zero or below, and a number you cannot spend is not an answer; top up and ask again.

It excludes work still running. A generation is billed when it completes, so clips in flight are not subtracted here yet. Read it right after submitting a batch and you are reading the figure from before you submitted.

Refusals: 401 the key is missing or invalid · 404 the key belongs to no organisation · 409 your organisation has no spending limit configured — contact your account manager · 429 nothing left, or too many requests · 502 our own check failed, retry · 503 temporarily unavailable.

Topping up

On the Billing tab: add a card, then top up. Payment happens on Stripe's own page — the card never touches us.

Automatic top-up charges the saved card when the balance falls below a threshold you set. You choose the threshold, the amount, and a daily maximum that nothing can exceed. If the card is declined in a way that needs you present, top-up switches itself off and we e-mail you rather than retrying a card that cannot work.

Bank transfer is possible by arrangement — contact your account manager. When it arrives we add it to your balance, it appears under Payments on the Billing tab, and the organisation's owner gets an e-mail.

Running out

Before it runs out: when the balance falls below $10, the console's Keys, Spend, Logs and Users tabs show a banner with the balance left and a Top up link to Billing. (Before an organisation's first top-up, Keys and Users show their own "top up first" notice instead.)

A request that would spend beyond the balance is refused with 429 and a plain reason:

{"error": {"message": "budget exceeded for this organisation: its spend has reached the balance it was topped up to. Top up in the console to continue."}}

Nothing is charged for a refused request, and the refusal appears in your Logs so you can see it happened rather than guessing from a status code your code swallowed.

What a request costs

Chat and completion models are billed per token, at the rate on the model's own page. Image and video models are billed per image or per second of output, by resolution.

Media jobs are billed from what the vendor reports it rendered, not from what was asked for. If you request 1080p and the vendor delivers 720p, you pay for 720p. A job we cannot price is withheld rather than delivered free — you are never billed for something you did not receive, and never given something nobody could price. The one exception is an Ideogram job whose images were all withheld by the generator's safety check: the generator produced and charged for them, so the job ends failed and is billed for the images produced.

Recraft's generators are billed per image delivered, never more than the n you asked for, plus a flat amount once per request that sends style_reference_urls (every generator but Flash V2, which takes none); its image tools (vectorize, remove background, the two upscales) are billed per request. A Recraft job the generator refused, or did not finish, ends failed and is not billed.

The price before you send

POST /v2/jobs/estimate takes the body of a /v2 job and answers with estimated_cost_usd and an estimate_kind. Nothing is created, charged or held, and a key with no balance may ask. For exact models cost_usd of the finished job equals the estimate; for upper_bound models it is never above it; for approximate models, whose price depends on the length of a file you send, it can be slightly above or below. The estimate is at your organisation's price when you ask, and cost_usd follows the price in force when the job is charged. Prompt enhancement is free and in neither number. Jobs API has the kinds by model.

Seeing where it went

Spend breaks the period down by key, and each key opens into a day-by-day view. Logs lists individual requests with their model, duration and cost, and exports to CSV. An export covers at most 10,000 requests per key; for a key past that in the chosen period, the console asks for a shorter period instead of handing back a partial file.