> For the complete documentation index, see [llms.txt](https://bountyv.gitbook.io/vdocs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bountyv.gitbook.io/vdocs/account/credits.md). # Credits & pricing Check your balance and the per-call pricing that applies to your account. This is the canonical source of truth for pricing — other reference pages link back here instead of hardcoding rates. ## The currency: V-Tokens Everything on Substance is priced in **V-Tokens**, whichever way you created your account: * **Email/password accounts** hold V-Tokens in your Substance balance, topped up with the [crypto top-up flow](/vdocs/account/topup.md). * **V-Auth accounts** spend from your shared V-Auth wallet, so the same tokens work across every V-Auth product. Same currency, same prices either way — only where the tokens are held differs, and nothing in this API changes because of it. **1 V-Token = 1 US cent.** Every `*_cents` field in the API is therefore the same number as the equivalent token count; the `*_tokens` fields are the canonical name and the `*_cents` ones remain as aliases for existing integrations. ``` GET /api/v1/credits ``` Synchronous. Calling this endpoint is free — it never deducts from your balance. ## Authentication Requires a Bearer API key. See [Authentication](/vdocs/authentication.md). ## Request No body. Send only the `Authorization` header. | Field | Type | Required | Description | | ----- | ---- | -------- | --------------------------------- | | — | — | — | This endpoint takes no parameters | ## Response ```json { "currency": "V-Tokens", "unlimited": false, "balance_tokens": 5000, "balance_cents": 5000, "pricing": { "identity_create": { "charge_cents": 500 }, "identity_image": { "charge_cents": 20 }, "video_generate": { "charge_cents": 85 }, "thumbnail": { "charge_cents": 15 }, "clip_clean": { "charge_cents": 25 }, "clip_split": { "charge_cents": 25 }, "clip_stitch": { "charge_cents": 25 } }, "engine_pricing": { "txt2img": { "zimage": 25, "sdxl": 25, "sd15": 25, "qwen": 25, "flux2": 25, "seedream": 29, "nanobanana": 49, "gptimage": 39 }, "i2i": { "sdxl": 25, "zimage": 25, "qwen": 25, "flux2": 25, "seedream": 29, "nanobanana": 49, "gptimage": 39 }, "img2video": { "wan": 99, "seedance": 159, "dirtydan": 249 } }, "frontier_pricing": { "nano-banana-pro": 49, "chatgpt-image": 39, "seedream": 29, "seedream-5-pro": 49, "seedream-5-pro-uncensored": 49, "seedance": 159, "seedance-dirty-dan": 249, "omni-flash": 249 } } ``` `unlimited: true` marks an account that is never debited (internal and test accounts); its `balance_tokens` is `null` because it has no meaningful balance. ### Per-engine rates `pricing` gives one figure per endpoint, which is only meaningful where the endpoint has a single engine. The image and video endpoints price **by engine** — an external frontier model costs us more per render than a self-hosted lane — so `engine_pricing` gives the resolved rate for every engine choice, and `frontier_pricing` does the same for the raw [Frontier Passthrough](/vdocs/frontier-passthrough/frontier-overview.md) routes. All values are cents. Frontier routes bill on the same key as their wrapped engine, so a model costs the same whichever surface you reach it through. The two Seedream entries are **per output image** — multiply by `count` when using sequential-set mode. | Field | Type | Description | | ------------------------------- | ------- | --------------------------------------------------------------------- | | `balance_cents` | integer | Your available balance, in US cents (100 = $1.00) | | `pricing` | object | Per-action pricing that applies to your account's tier | | `pricing..charge_cents` | integer | Amount deducted from your balance on a successful call to that action | Rates are read live from your account's cost tier at request time — the values above are illustrative. Always read pricing from this endpoint at runtime rather than hardcoding it; rates can change. If you call an endpoint whose action isn't listed above, the amount actually charged is still returned inline as `charged_cents` in that endpoint's own response. ## Example ```bash curl https://substance-api.com/api/v1/credits \ -H "Authorization: Bearer sk_live_..." ``` ## Errors | Status | When | | ------ | -------------------------------------- | | `401` | Missing, malformed, or revoked API key | | `403` | Account disabled — contact support | | `429` | Rate limit exceeded for your key | See [Errors](/vdocs/errors.md) for the full error format. ## Pricing This endpoint is free to call — checking your balance and rates never incurs a charge. Use it before a batch of calls to confirm you have enough balance, or at startup to cache per-action pricing for display in your own UI. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://bountyv.gitbook.io/vdocs/account/credits.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.