> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Billing & Pricing

> Understand TokenLab's pay-as-you-go pricing

## Overview

TokenLab uses **pay-as-you-go pricing**. You only pay for what you use, with no subscriptions or minimum commitments.

## How Billing Works

1. **Add credits** to your account
2. **Use the API** - costs are deducted per request
3. **Monitor usage** in your dashboard
4. **Top up** when your balance is low

## Pricing Models

Live prices can change as providers, routes, and model details change. Treat the Dashboard, the Models page, `GET /v1/models/:model/pricing`, and [Pricing API](/api-reference/pricing/get-pricing) to check current support.

### Token-Based Pricing

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

| Pricing family      | Examples                                           | Verify current price                 |
| ------------------- | -------------------------------------------------- | ------------------------------------ |
| Chat / Responses    | `gpt-5.4`, `claude-sonnet-4-6`, `gemini-3.5-flash` | Models page or Pricing API           |
| Embeddings / rerank | `text-embedding-3-small`, `qwen3-vl-rerank`        | Model pricing detail                 |
| Token-priced images | `gpt-image-2`                                      | `GET /v1/models/gpt-image-2/pricing` |

<Note>
  Avoid copying static price tables into production logic. Store only model IDs in code and fetch or review current pricing before launch.
</Note>

### Request and Task Pricing

Image, video, music, 3D, audio, and world-generation models may be priced per request, per image, per second/minute, per task, or by provider-specific usage. Check the selected model details before production usage.

| Family | Examples                      |
| ------ | ----------------------------- |
| Image  | `flux-pro`, `qwen-image-plus` |
| Video  | `veo3.1`, `seedance-2.0`      |
| Music  | `suno-music`                  |
| 3D     | `tripo-h3.1`                  |
| Audio  | `tts-1`, `whisper-1`          |

### Async Task Billing (Video/Music/3D and Some Image Models)

<Note>
  For task-based generation, creating the task may reserve or pre-deduct the estimated cost. Final settlement happens only after the async task reaches a terminal success state during polling or finalization.
</Note>

For task-based generation flows (video, music, 3D, and some image models):

1. Submit the task. TokenLab may place an estimated pre-deduction or reservation to verify balance and spending limits.
2. Follow the returned `poll_url`, or call `GET /v1/tasks/{id}`, until the task reaches a terminal status.
3. When the task completes successfully, final settlement records the usage and the task response includes `billing_transaction_id`.
4. If creation fails or the terminal status is failed, the pending amount is refunded or released and the request is marked non-billable.

If the dashboard does not reflect a completed settlement or refund after terminal status is visible, contact [support@tokenlab.sh](mailto:support@tokenlab.sh) for assistance.

```python theme={null}
# Example: Video generation billing
response = client.post("/v1/videos/generations", json={
    "model": "veo3.1",
    "prompt": "A sunset over the ocean"
})
# Estimated cost may be reserved now; final billing appears after success.

poll_url = response.json()["poll_url"]
task_id = response.json()["task_id"]
# Poll poll_url for status; billing_transaction_id appears after settlement.
```

### Billing Transaction IDs

Successful billable OpenAI-compatible non-streaming JSON responses include `billing_transaction_id` when settlement has completed before the response is finalized. The same value is also exposed as the `X-Billing-Transaction-ID` response header for browser and server integrations. Native compatibility routes, such as Gemini `/v1beta`, may expose the value via the header only to preserve the provider-native response shape. For async media tasks, poll the returned `poll_url` or `GET /v1/tasks/{id}`; the task response includes `billing_transaction_id` once settlement is complete. Streaming responses may settle after the stream has already been sent, so use the dashboard usage logs for reconciliation when the header is absent.

## Token Counting

Tokens are the basic units of text processing:

* \~4 characters = 1 token (English)
* \~1-2 characters = 1 token (Chinese)
* 1 image = varies by size and detail

### Estimating Tokens

```python theme={null}
# Rough estimation
def estimate_tokens(text):
    return len(text) / 4  # Approximate for English

# Actual count (for OpenAI models)
import tiktoken
encoder = tiktoken.encoding_for_model("gpt-4o")
tokens = encoder.encode("Your text here")
print(f"Token count: {len(tokens)}")
```

## Usage Tracking

### Dashboard

Monitor your usage in the [Dashboard](https://tokenlab.sh/dashboard):

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

### API Response

Each response includes usage information:

```json theme={null}
{
  "usage": {
    "prompt_tokens": 50,
    "completion_tokens": 100,
    "total_tokens": 150
  }
}
```

## Cost Optimization

<AccordionGroup>
  <Accordion title="Use appropriate models">
    Use smaller models (GPT-4o-mini, Gemini Flash) for simple tasks.
  </Accordion>

  <Accordion title="Implement caching">
    Cache responses for repeated identical requests.
  </Accordion>

  <Accordion title="Optimize prompts">
    Keep prompts concise while maintaining clarity.
  </Accordion>

  <Accordion title="Set max_tokens">
    Limit response length when full responses aren't needed.
  </Accordion>

  <Accordion title="Use streaming for long responses">
    Streaming doesn't cost extra but improves perceived performance.
  </Accordion>
</AccordionGroup>

## Low Balance Alerts

Configure alerts when your balance drops:

1. Go to **Dashboard → Settings → Notifications**
2. Set your threshold amount
3. Receive email notifications

## Adding Credits

### Payment Methods

* Stripe (Visa, Mastercard)

### Steps

1. Log in to [Dashboard](https://tokenlab.sh/dashboard)
2. Click **Add Credits**
3. Select amount and payment method
4. Complete payment

Credits are added instantly after payment confirmation.

## API Key Limits

You can set spending limits on individual API keys:

1. Go to **Dashboard → API Keys**
2. Click on a key to edit
3. Set **Usage Limit**

When the limit is reached, requests with that key will return `402 Payment Required`.

## Questions?

Contact [support@tokenlab.sh](mailto:support@tokenlab.sh) for billing inquiries.