TokenLab

Core Guides

Billing and pricing

How charges, estimates, balances, and limits work

One TokenLab balance works across models. There is no subscription or minimum spend. Top-ups start at $5. Charges are based on the model and usage recorded for each request.

If a top-up did not go through

A top-up adds balance only when its status is completed. Pending or failed means no balance was added yet.

  • Your bank asked you to verify the payment. Some cards open a verification window from the bank (a code or an app confirmation). Finish that step in the same browser tab; if the tab was closed, start the top-up again and complete the verification when it appears.
  • The card was declined. Try another card, or another of the methods your Console offers for your country. Your bank can also decline a card for cross-border or recurring-payment rules even when the card is valid.
  • The top-up stays pending. A pending top-up is waiting on the payment provider or your bank. Do not start a second top-up for the same amount while one is pending; the balance is added once.
  • The money left your account but the balance did not show up. Write to hello@tokenlab.sh with the date, the amount, and the last four digits of the card. We check the payment on our side and reply.

You do not need an API key or a running request to add balance, and there is no subscription: a top-up is charged once.

Delivery options

The same model and API are available through two routes: Verified costs less, and Official is more reliable. The delivery option decides which route runs a request and which price you pay.

OptionRoutePriceIf the route is unavailable
VerifiedVerified only: routes tested by TokenLabVerified price, lower than the Official price on most modelsThe request fails and is not charged
OfficialOfficial only: the model maker or a major platformOfficial price, the model maker's published priceThe request fails and is not charged
Auto (default)Verified first. Official runs the request once if Verified has no supply or fails before any outputThe price of the route that completed the requestOfficial runs the request

The Models page shows both prices for each model.

  • Each completed request is charged once.
  • Auto does not switch after output starts or after a task is accepted.
  • Before a run, Auto holds the higher of the two possible amounts. If the balance covers only the Verified estimate, Auto runs Verified alone for that request and does not fall back to Official. After the run, you pay the actual charge and the rest is released.
  • The X-TokenLab-Delivery-Policy request header overrides the API key setting, and the API key setting overrides the Workspace default. See the API introduction.

For paid generation, Console shows the maximum estimate before confirmation. After completion, Runs and Usage show the final charge and the option that completed the request.

Pricing Models

Model prices can change. Check Console, the Models page, GET /v1/models/:model/pricing, or the Pricing API for the current price.

On the Models page, a dash in the Verified price or discount column means no Verified offer is currently available; it does not mean free. Models with Official supply remain available through Official or Auto. In the API, the Verified price fields of such a model are null or omitted, and the official_* price fields show what you pay. Delivery labels describe supported options, while availability is checked when each request runs. Series prices summarize models with supply in the relevant delivery option and keep different billing units separate.

Token-Based Pricing

Most chat, reasoning, embedding, rerank, and some image models are priced by input, output, cache, or image-output tokens.

Pricing familyExamplesVerify current price
Chat / Responsesgpt-5.4, claude-sonnet-4-6, gemini-3.6-flashModels page or Pricing API
Embeddings / reranktext-embedding-3-small, qwen3-vl-rerankModel pricing detail
Token-priced imagesgpt-image-2GET /v1/models/gpt-image-2/pricing

Do not hard-code a copied price table. Read the current price when your application needs to display or compare costs.

Tool fees

Some built-in tools cost extra on top of tokens. TokenLab charges a tool fee only when the model uses the tool and the response reports it. A request that offers a tool the model does not use has no tool fee.

ToolModelsCharge
Web searchOpenAI, Claude and Grok models, and Gemini 3 models with Google Search groundingEach search the model runs. For Gemini 3, each unique search query
Search groundingGemini 2.5 models with Google Search groundingOnce for each request that the search grounded
  • Each model has its own tool fee for Verified and Official, the same as its token prices. The model's pricing details show it as Web search or Search grounding.
  • Search results that the model reads are billed as input tokens at the model's price.
  • A tool without a price on a model is not charged.
  • In Console, open a request in Runs: Tool fees shows the number of calls and the price of each call. The API key usage records show the same values in charged_price_basis: the count in measure.dimensions.webSearchCalls or groundedPrompts, and the price of each call in effectiveUnitPrices.webSearch or effectiveUnitPrices.groundedPrompt.

Prompt caching

A model can read the repeated start of a prompt from a cache. Tokens read from the cache cost less than input tokens.

  • GPT, Gemini and some other models cache long repeated prompts automatically. You do not set anything.
  • Claude models cache only when you ask. Send "anthropic_options": {"prompt_caching": true} in a Chat Completions request. TokenLab marks the end of the system prompt and the latest user message as cache points. With the Messages API, add cache_control to the blocks yourself.
ChargeCompared with the input price
Cache write, 5 minutes (default)Higher
Cache write, 1 hour ("prompt_caching_ttl": "1h")Higher than the 5-minute write
Cache readLower
  • Cache prices differ by model and delivery option. Check the model's cache prices on the Models page or in the Pricing API before you rely on a ratio.
  • A prompt that never repeats costs a little more with caching on, because of the cache write.
  • A prompt shorter than the model's minimum cacheable length is not cached and has no cache write charge.
  • A one-hour cache is not available on every model. If the model does not list it, use the five-minute cache.
  • The response shows the result: usage.prompt_tokens_details.cached_tokens is the number of tokens read from the cache. usage.cache_creation_input_tokens is the number written to it, and appears only when it is more than zero.

Service tier

TokenLab runs and bills requests at the standard service tier. service_tier values auto and default are accepted. Other values, such as flex, priority, fast, and ultrafast, are ignored: the request runs at the standard tier and is charged the standard price.

Request and Task Pricing

Image, video, music, 3D, audio, and world models may be priced per request, image, second, minute, or task. The model page shows the billing unit.

FamilyExamples
Imageflux-pro-1.1
Videoveo3.1, seedance-2.0
Musicsuno-music
3Dtripo-h3.1
Audiogrok-tts, whisper-large-v3

Async task billing

Some tasks reserve the estimated cost when they are created. A completed task is charged once; a failed task releases or refunds the pending amount.

Video, music, 3D, and task-based image generation return a task ID and poll_url. The final amount is recorded after the task becomes completed or failed. A completed task includes billing_transaction_id after billing; a failed task is not charged.

If Usage still does not show the final charge or released amount after the task finishes, contact hello@tokenlab.sh with the Request ID and task ID.

Billing transaction IDs

Non-streaming OpenAI-compatible responses include billing_transaction_id when billing finishes before the response is sent. The same value may appear in X-Billing-Transaction-ID; Gemini and other native formats may expose it only in this header.

Async tasks include billing_transaction_id after completion. Streaming may finish before billing does, so use Usage when the header is absent.

Token counts

Text models usually report input, output, and total tokens in usage. Tokenization differs by model, language, and media input, so character-count formulas are not reliable billing estimates. Use the model's current price and the final Usage record.

Find your usage

Open Usage to find:

  • Real-time balance
  • Usage history by model
  • Cost breakdown
  • API key usage

API response

Token-based responses usually include usage information:

{
  "usage": {
    "prompt_tokens": 50,
    "completion_tokens": 100,
    "total_tokens": 150
  }
}

Spend less

Low-balance alerts

Set a threshold in Console → Settings. TokenLab emails you when the balance falls below it.

Add balance

Open Console → Billing, choose an amount, and use one of the payment methods shown at checkout. The balance updates after the payment provider confirms the payment.

While the trial-credit offer runs, an eligible new account gets a one-time $0.25 trial credit for up to 10 calls. Unused trial credit expires after 7 days.

To keep requests from stopping at a low balance, turn on Automatic funding in Billing. It adds funds when the balance drops below the amount you set, up to a monthly limit.

API Key Limits

You can set a spending limit when you create or edit an API key in Console → API Keys.

When the limit is reached, requests with that key return 402 with the code quota_exceeded. Raise or remove the limit to continue.

A 402 can also come back with the code insufficient_balance: the account balance is lower than the estimated cost of the request. The error body carries balance_usd and estimated_cost_usd. Top up in Console → Billing (from $5) and retry; repeating the same request before a top-up will keep failing.

Request errors

400 with code=content_policy_violation is a content-safety refusal, not a malformed request: retryable=false and the request is not billed. Sending the same prompt again unchanged is refused again — change the input (text, image or both) instead of retrying. Other 400s name the offending param; fix that field and retry.

Billing help

Contact hello@tokenlab.sh for billing inquiries.

On this page