# Models ও Usage endpoint

> GET /v1/models-এ দেখা যায় আপনার key কোন কোন model call করতে পারে। GET /v1/tokens/usage-এ পাবেন plan, usage window, Wallet-এর ব্যালান্স আর key-র limit। সঙ্গে embeddings ও legacy completions-এর নোট।

দুটো read-only endpoint আছে, যাতে script বা tool browser session ছাড়াই জানতে পারে "কোন model call করতে পারি?" আর "কতটা বাকি আছে?"। দুটোতেই inference-এর API key-ই চলে, আর কোনোটার জন্য বিল হয় না।

## GET /v1/models দিয়ে model-এর list

```bash
curl https://tokens.bd/v1/models \
  -H "Authorization: Bearer $TOKENS_API_KEY"
```

```json
{
  "object": "list",
  "data": [
    {
      "id": "deepseek/deepseek-v4.1-flash",
      "object": "model",
      "created": 1788000000,
      "owned_by": "tokens",
      "permission": [],
      "root": "deepseek/deepseek-v4.1-flash",
      "parent": null
    }
  ]
}
```

| Field                          | মানে                                                                       |
| ------------------------------ | -------------------------------------------------------------------------- |
| `id`                           | `model` হিসেবে ঠিক এই string-টাই পাঠাতে হবে। সবসময় `provider/model` form-এ।    |
| `object`                       | সবসময় `"model"`।                                                           |
| `created`                      | Model catalog-এ যোগ হওয়ার Unix timestamp।                                  |
| `owned_by`                     | সবসময় `"tokens"`, model যে lab-ই বানাক না কেন।                              |
| `root`, `parent`, `permission` | OpenAI SDK-র সঙ্গে মেলানোর জন্য আছে; `root` আর `id` একই।                      |

Response-এ দাম বা context window থাকে না। সেগুলো পাবেন [model catalog](/models)-এ, প্রতিটা model-এর আলাদা পেজে। Catalog-এ capability flag-ও নেই (vision, tool calling, reasoning): কোনো model কী support করে সেটা কীভাবে জানবেন, তা [Model catalog](/docs/model-catalog) পেজে আছে।

### List-এ কোনো model না থাকলে কেন

List-টা যে key দিয়ে call করছেন তার জন্য ছাঁটাই হয়। তাই একই অ্যাকাউন্টের দুটো key আলাদা list দেখতে পারে:

1. **Key allow-list।** Key বানানোর সময় allowed-model list দিয়ে থাকলে শুধু সেই model-গুলোই আসে।
2. **Plan আর Wallet।** প্রতিটা model নির্দিষ্ট কিছু plan tier-এ আর pay-as-you-go-তে চালু থাকে। আপনার active plan-এর tier-এ model-টা থাকলে, অথবা model-টার জন্য pay-as-you-go চালু থাকলে এবং Wallet-এর ব্যালান্স শূন্যের বেশি হলে, সেটা list-এ আসে।
3. **Catalog status।** শুধু active catalog model-ই list-এ আসে।

`data` array খালি এলে সাধারণত বুঝবেন active plan আর Wallet ব্যালান্স কোনোটাই নেই। [Billing](/dashboard/billing)-এ গিয়ে subscribe করুন বা টাকা যোগ করুন; বিস্তারিত [plan ও Wallet](/docs/plans-and-wallet) পেজে।

## GET /v1/tokens/usage দিয়ে কতটা বাকি দেখুন

এই endpoint শুধু Tokens-এর নিজস্ব। এটা দেয় বর্তমান plan, plan-এর usage window, Wallet-এর ব্যালান্স আর যে key দিয়ে call করছেন তার limit। `tokens.mjs usage` CLI command এটাই পড়ে। Status bar-এ বা অনেকক্ষণ চলা কোনো agent-এর pre-flight check-এ এটা বেশ কাজে লাগে।

```bash
curl https://tokens.bd/v1/tokens/usage \
  -H "Authorization: Bearer $TOKENS_API_KEY"
```

```json
{
  "object": "tokens.usage",
  "plan": {
    "name": "Pro Monthly",
    "tier": "monthly",
    "periodEnd": "2026-11-02T08:15:00.000Z"
  },
  "windows": [
    {
      "type": "session_5h",
      "label": "5-Hour Session",
      "unit": "usd",
      "limit": 5,
      "used": 1.284,
      "remaining": 3.716,
      "percentUsed": 26,
      "resetsAt": "2026-10-03T14:40:00.000Z"
    }
  ],
  "wallet": { "balanceUsd": 12.5 },
  "key": {
    "monthlySpendCapUsd": 20,
    "allowedModels": null
  }
}
```

ওপরের plan-এর নাম আর সংখ্যাগুলো শুধু উদাহরণ; আপনারটা আপনার plan অনুযায়ী আলাদা হবে।

| Field                                  | Type             | মানে                                                                         |
| -------------------------------------- | ---------------- | ---------------------------------------------------------------------------- |
| `plan`                                 | object বা null   | Active সাবস্ক্রিপশন; শুধু pay-as-you-go হলে `null`                             |
| `plan.tier`                            | string           | Plan tier, যেমন `weekly` বা `monthly`                                        |
| `plan.periodEnd`                       | ISO 8601 বা null | চলতি সাবস্ক্রিপশন period কখন শেষ হবে                                          |
| `windows[]`                            | array            | যেসব plan usage window-এ চলতি period-এ usage হয়েছে                            |
| `windows[].type`                       | string           | `session_5h` (rolling 5 ঘণ্টা), `weekly` বা `monthly`                         |
| `windows[].unit`                       | string           | `usd` (credit, USD-তে প্রকাশ করা) বা `requests`                               |
| `windows[].limit`, `used`, `remaining` | number           | Window-র unit-এ                                                              |
| `windows[].percentUsed`                | integer          | 0 থেকে 100                                                                   |
| `windows[].resetsAt`                   | ISO 8601         | Window কখন reset হবে                                                         |
| `wallet`                               | object বা null   | `balanceUsd`: prepaid Wallet-এর ব্যালান্স USD-তে; Wallet না থাকলে `null`         |
| `key.monthlySpendCapUsd`               | number বা null   | যে key দিয়ে call করছেন তার monthly cap; cap না থাকলে `null`                   |
| `key.allowedModels`                    | array বা null    | Key-র allow-list; যেকোনো model চললে `null`                                   |

:::note
চলতি period-এ যে window এখনো ব্যবহার হয়নি, সেটা `windows`-এ থাকে না। তাই একদম নতুন plan-এ বা reset-এর ঠিক পরে array খালি আসাটা স্বাভাবিক।
:::

কোনো window-র সীমা শেষ হয়ে গেলে `resetsAt` পর্যন্ত inference request-এ 429 `window_exhausted` আসে। কোনো window-র 50, 75, 90 আর 100 শতাংশ ব্যবহার হলে Dashboard আপনাকে notify-ও করতে পারে; দেখুন [usage ও alert](/docs/usage-and-alerts)।

Response আসে `Cache-Control: no-store` সহ। মিনিটে একবার poll করাই যথেষ্ট; এটা আপনার বিলেও গোনা হয় না, আর প্রতি মিনিটের request limit-এও না।

## Embeddings: POST /v1/embeddings

Route-টা আছে এবং OpenAI-র embeddings format মেনে চলে, কিন্তু কাজ করে শুধু সেই catalog model-এ যেগুলো embedding model। Chat model-এ এটা fail করবে। এই endpoint-এর ওপর কিছু বানানোর আগে [model catalog](/models)-এ embedding model আছে কিনা দেখে নিন; কিছু না থাকলে বুঝবেন আপনার অ্যাকাউন্টের জন্য এখনো কোনো embedding model নেই।

## Legacy completions: POST /v1/completions

পুরোনো ধাঁচের prompt-দিলে-text-পাওয়া completions endpoint-টা পাস করে দেওয়া হয়, যেসব tool এখনো এটা ব্যবহার করে তাদের জন্য। এটা চলে শুধু তখনই যখন model-এর পেছনের upstream এটা support করে, আর অনেক chat model করে না। নতুন কিছুর জন্য [chat completions](/docs/chat-completions) ব্যবহার করুন।

## যেসব endpoint নেই

`/v1`-এর নিচে অন্য যেকোনো path-এ 404 আসে, code `unsupported_endpoint`। এর মধ্যে আছে images, audio, files, batches, assistants, fine-tuning আর moderations। Code-এর পুরো list পাবেন [errors](/docs/errors) পেজে।

---
Page: https://tokens.bd/bn/docs/models-and-usage