Credits are shared across the app and the API. An image you generate through the API
costs exactly what the same image costs in the app, and both draw down the same
organization balance. Check what a key can spend any time with
GET /credits.Image generation
Image generation costs 5 credits per output at1K, scaled by resolution and
multiplied by the number of outputs:
num_outputs defaults to 1 (the app default is 4). For example, 4 outputs at
2K cost 5 × 4 × 2 = 40 credits. The price is the same on every text-to-image
engine; an engine offers only the resolutions it supports (see
GET /images/models).
Magic Edit
A Magic Edit (POST /images/edits) costs 5 credits per output at the base
resolution, multiplied by num_images. The three Nano Banana engines have
resolution tiers with the same multipliers as image generation; gemini and
kontext have a fixed resolution and always cost 5 per output:
The
202 returns the amount deducted as estimated_credits, together with the
effective engine and resolution. See
Engines and credits.
Image uploads
Image uploads (POST /images/uploads/prepare and
POST /images/uploads/{id}/complete, and the MCP tools prepare_image_upload and
complete_image_upload) are free. The operations you then run on the uploaded
image are billed as usual.
Image operations
The six image operations — img2img, variations, resize, upscale, background removal, and vectorization — each draw credits at submit and return the exact amount asestimated_credits in the 202 (it equals what was deducted).
The resolution multiplier is the same as image generation:
1K ×1, 2K ×2, 4K
×4. num_outputs defaults to 1. Img2img and resize take an explicit
resolution; variations inherit the source image’s resolution tier (there is no
resolution parameter) — a source with no recoverable dimensions prices at 1K.
Upscale
Upscale is priced by the target resolution tier, multiplied by the model’s credit multiplier. SeedVR and Crystal are ×1; Magnific Creative and Magnific Precision are ×3.
† For Crystal,
14K and above are priced by output megapixels (see below), not
this fixed figure — the 14K/16K values in the ×1 column are the SeedVR price.
Crystal matches the ×1 column exactly up to 12K.
The Magnific column shows the tier price where the model can reach it — the
Magnific engines enforce per-model output caps, so the highest tiers are only
reachable with Crystal. Resolution classes above
16K (20K–38K) are
Crystal-only.12K (14K and up) are priced by the
predicted output megapixels instead of the tier table:
Worked example — Crystal at 14K
A Crystal upscale whose predicted output is 101.6 MP (a
14K-class 16:9 image)
costs ceil(101.6 × 0.6 / 5) × 5 = ceil(12.19) × 5 = 65 credits.Cache hits cost nothing
Background removal and vectorization are cached per source image. When the source is animage_id you own and a matching result already exists, the submit returns
202 with status: "completed" and estimated_credits: 0 immediately — no new
job runs and the per-org concurrency cap is not consumed.
Every other case (an https url or base64 source, or an owned image with no ready
result) is the normal charged path.
A resize whose target ratio already matches the source (nothing new to outpaint)
and that has no
prompt skips the model, returns the flattened composition, and
refunds the unused outputs — it still completes.Model creation
Creating a custom model (POST /models) costs 0 credits — it is a billable
action recorded for your audit trail, charged at zero. You are billed for generating
with the model, not for creating it.
Legacy LoRA “training” is deprecated and not available through the API — the legacy
training endpoints return
410 Gone. “Model creation” and “model training” refer to
the same Gemini-based flow; see the overview for what you can build.Video generation
Video is billed at a base of 5 credits per second, then scaled by the engine, the resolution, and whether audio is generated:Engine multipliers
Theengine you pick sets the base multiplier. Some engines also generate audio, at
an additional multiplier applied on top.
“included” means audio is generated at no extra credit cost (×1.0). A ”—” means the
engine has no audio option. Engines omit
engine to use the default,
veo_3_1_lite.Resolution multipliers
On engines that expose resolution tiers, higher resolutions cost more:Worked examples
Kling 2.5 Pro Turbo · 5s
5 × 5 × 2 = 50 credits (fixed resolution, no audio).Veo 3.1 Lite · 8s · 1080p
5 × 8 × 1 × 2 = 80 credits (no audio).Veo 3.1 · 8s · 1080p · audio
5 × 8 × 5 × 2 × 1.25 = 500 credits.MiniMax 01 · 5s
5 × 5 × 1 = 25 credits (fixed resolution, no audio).Prompt improvement
Coming soon. Prompt improvement is not enabled yet, so nothing is charged
today. The price below applies from launch.
POST /prompts/improve, or the
MCP tool improve_prompt) costs 1 credit per call, for target image and
video alike. The credit is charged before the AI model runs, and the 200 response
reports it as credits_charged: 1.
- If the AI provider fails, the credit is refunded automatically and the call returns
502 provider_error. - A call repeated with the same
Idempotency-Keyand body within 24 hours returns the stored result and is not charged again. Without the header, every call is charged. See Idempotency.
Refunds
If a job fails on Samsa’s side — a terminal provider error after credits were deducted — the credits are automatically refunded to the same organization pool they were drawn from. Afailed job you submitted correctly does not cost you
credits. (Client errors such as 422 validation_error are rejected before anything is
charged.)
An image job that ends
failed with error delivery_blocked_compliance: <codes>
is different: the outputs were produced, but the compliance pipeline withheld them
(see Compliance blocks).
It is not refunded automatically, and its credits_used stays as charged.
Contact support@samsa.ai with the job id.When you run out of credits
If the balance the key can spend cannot cover an action’s cost, the submit request returns402 before any job is
created — nothing is charged and no job row exists.
insufficient_credits— the balance is below the cost, and the organization has no active teams (or is a budget-exempt system organization); also the fallback when the deduction itself fails operationally, whatever the regime — retry before treating it as a low balance. Top up or upgrade.insufficient_team_credits— same, for a key assigned to a team with its own budget. Raise the budget, reassign the key, or top up.insufficient_unallocated_credits— same, for a key that is not assigned to a budgeted team. Free unallocated credits, assign the key to a team with headroom, or top up.subscription_inactive— the organization has no usable subscription. Reactivate billing.
GET /credits reports the balance a key can spend
(available) and the budget scope that determines which of the three codes it gets.
Buy credits and top-ups
Purchase credits, add top-ups, and manage your plan in the Samsa app. API usage
draws from the same balance.