---
name: cheaptokens
description: >-
  Use CheapTokens (OpenAI-compatible API at api.cheaptokens.com) to list models,
  compare prices, pick a model, and run chat/embeddings/images/audio/video with
  the user's own API key. Use when the user mentions CheapTokens, cheap tokens,
  国产算力, OpenAI-compatible Chinese inference, model marketplace pricing, or
  wants to call LLMs via a CheapTokens key.
---

# CheapTokens

OpenAI-compatible inference gateway. **User supplies their own API key** — never invent or embed keys.

## Auth (required)

1. Prefer env `CHEAPTOKENS_API_KEY`. Also accept `OPENAI_API_KEY` if `OPENAI_BASE_URL` / `CHEAPTOKENS_BASE_URL` points at CheapTokens.
2. If missing: tell user to create a key at https://cheaptokens.com/console/keys (format `cheap-…`) and export:

```bash
export CHEAPTOKENS_API_KEY='cheap-…'
export CHEAPTOKENS_BASE_URL='https://api.cheaptokens.com/v1'   # optional override
```

3. Local/dev default base if user says so: `http://localhost:47100/v1`.

Never print the full key in replies; mask as `cheap-********`.

## Type → endpoint (critical)

`GET {BASE}/models` returns `type`, `primary_endpoint`, `endpoints`, `billing_unit`. **Do not assume everything is chat.**

| type                                                  | Call                               |
| ----------------------------------------------------- | ---------------------------------- |
| LLM / MULTIMODAL / OCR / TRANSLATION / CLASSIFICATION | `POST /chat/completions`           |
| CODE_COMPLETION                                       | `POST /completions` (also chat OK) |
| EMBEDDING                                             | `POST /embeddings`                 |
| RERANKER                                              | `POST /rerank`                     |
| TEXT_TO_IMAGE                                         | `POST /images/generations`         |
| IMAGE_TO_IMAGE                                        | `POST /images/edits`               |
| TEXT_TO_VIDEO                                         | `POST /videos/generations`         |
| SPEECH_TO_TEXT                                        | `POST /audio/transcriptions`       |
| TEXT_TO_SPEECH                                        | `POST /audio/speech`               |

Site docs: https://cheaptokens.com/docs#models — market detail shows curl per type.

## Endpoints

`BASE` = `CHEAPTOKENS_BASE_URL` or `https://api.cheaptokens.com/v1`.

Header: `Authorization: Bearer $CHEAPTOKENS_API_KEY`

Optional routing: `X-Route-Strategy: cheapest | fastest | stable`.

## Workflows

### Find a model

```bash
curl -sS "$CHEAPTOKENS_BASE_URL/models" \
  -H "Authorization: Bearer $CHEAPTOKENS_API_KEY"
```

Use returned `type` / `primary_endpoint` to pick the path. Market: https://cheaptokens.com/market

### Chat (Python)

```python
from openai import OpenAI
import os

client = OpenAI(
    base_url=os.environ.get("CHEAPTOKENS_BASE_URL", "https://api.cheaptokens.com/v1"),
    api_key=os.environ["CHEAPTOKENS_API_KEY"],
)
r = client.chat.completions.create(
    model="deepseek-v4-flash",  # or cheap/deepseek/deepseek-v4-flash
    messages=[{"role": "user", "content": "你好"}],
)
print(r.choices[0].message.content)
```

### Embeddings / images / audio

Use the matching OpenAI SDK method or curl to `primary_endpoint` from `/models`. Examples on https://cheaptokens.com/docs#embeddings · `#images` · `#audio` · `#videos`.

## Errors

| Symptom                                   | What to tell the user                            |
| ----------------------------------------- | ------------------------------------------------ |
| 401 / invalid_api_key                     | Key wrong or revoked → recreate at /console/keys |
| insufficient balance                      | Top up at console                                |
| no node / model unavailable               | Pick another model from `/models` or market      |
| wrong endpoint (e.g. embed model on chat) | Use `primary_endpoint` for that model's `type`   |

## Do not

- Do not use Admin APIs or invent platform secrets.
- Do not store the user's key in the repo or skill files.
- Do not assume a shared/demo key exists.
- Do not call `/chat/completions` for EMBEDDING / IMAGE / VIDEO / ASR models.

## More detail

See [reference.md](reference.md).