> For the complete documentation index, see [llms.txt](https://docs.meganova.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.meganova.ai/enterprise/token-plan.md).

# Token Plan

## Overview

[Libra OS](/libra-os.md) is MegaNova's enterprise AI platform. This guide shows how to power a Libra OS deployment's LLM tiers with a MegaNova **Token Plan** subscription — a flat monthly fee that includes an enterprise‑model usage allowance — instead of paying per request. Libra OS talks to MegaNova over an OpenAI‑compatible endpoint, so configuration is just a key, a base URL, and your model ids.

## What the Token Plan is

A recurring monthly subscription in the MegaNova console (**Libra OS → Subscription**): a flat fee that includes a monthly **usage allowance** of enterprise model usage, billed against the subscription instead of your pay‑as‑you‑go wallet. Usage is shown as an opaque **% used** and **resets each billing period**. Optional, opt‑in **capped overage** lets you keep working past the allowance at metered rates up to a limit you set.

## Key Features

* Predictable flat monthly billing with an included usage allowance
* Access to the enterprise model line over the [Enterprise Endpoint](/enterprise/enterprise-endpoint.md), an OpenAI‑compatible API
* [Zero data retention](#zero-data-retention) at the model provider for covered models
* A dedicated plan API key (allowance‑billed, not pay‑as‑you‑go)
* [Managed Web Search](/api-reference/platform-api/search.md) included, billed from the same allowance
* Opt‑in, capped overage when you need to go past the allowance
* Works with Libra OS out of the box — just a base URL and your usual model ids

## Zero Data Retention

Plan‑covered models run on the enterprise deployments described in [Data handling](/enterprise/enterprise-endpoint.md#data-handling): provider‑side caching disabled, no training on your data, and message content kept out of our operational logs. That posture comes from the deployment, not from the subscription — it is identical whether a call draws your plan allowance or a wallet. The model‑specific exceptions listed there (notably `anthropic/claude-fable-5`) apply to plan traffic too.

Speech‑to‑text is the one covered model served outside that endpoint. `Systran/faster-whisper-large-v3` runs on MegaNova's own GPUs, so no model provider ever receives your audio, and neither the audio nor the transcript is kept in our operational logs.

## Requirements

* A MegaNova account with billing enabled
* A running Libra OS deployment
* A **Token Plan** subscription (set up below)

## Integration Steps

### 1. Subscribe and get your plan key

1. In the MegaNova console, open **Libra OS → Subscription** and complete checkout.
2. On activation, a dedicated **"Libra OS" API key** is provisioned and shown on that page (Reveal / Copy / Regenerate).

> ⚠️ **The Token Plan only works with this key.** Usage on any other API key — even for the same models — is billed **pay‑as‑you‑go**, not from the plan allowance. This key is managed on the Libra OS page (it's hidden from the generic *API Keys* page).

### 2. Point Libra OS at the Enterprise Endpoint

Enterprise models are served from the [Enterprise Endpoint](/enterprise/enterprise-endpoint.md) — `https://enterprise.api.meganova.ai`. Use the **bare** host: the OpenAI‑compatible chat endpoint is served at `https://enterprise.api.meganova.ai/chat/completions`, which is what the OpenAI client libraries expect when given a bare host. (The explicit `https://enterprise.api.meganova.ai/v1` form works too, for tools that want the full base path.)

**Option A — environment / `docker-compose`:**

```bash
OPENAI_API_KEY=sk-<your Libra OS plan key>
OPENAI_API_BASE=https://enterprise.api.meganova.ai   # bare host — NOT .../v1
# Map the three routing tiers to covered models (see step 3):
LIBRA_OS_BRAIN_MODEL=gemini/gemini-2.5-pro         # planner
LIBRA_OS_SKILL_MODEL=gemini/gemini-2.5-flash-lite  # cheap skill agents
OPENAI_MODEL=gemini/gemini-2.5-pro                # answer / synthesis
```

**Option B — runtime, without a restart** (`PUT /api/config/settings`; persisted and hot‑reloaded):

```json
{
  "openai_api_key": "sk-<your Libra OS plan key>",
  "openai_api_base": "https://enterprise.api.meganova.ai",
  "synthesis_model": "gemini/gemini-2.5-pro"
}
```

> **Already running with `-Ent` model ids on `https://api.meganova.ai`?** That configuration keeps working — it is not being switched off. Moving to the endpoint form means dropping the `-Ent` suffixes and changing the base URL, as shown above; billing and the deployments serving your traffic are unchanged.

### 3. Use only the covered models

The Token Plan covers these **23** chat models. Use the full `provider/model` form — bare names are rejected, and any **non‑covered** model called with the plan key is billed pay‑as‑you‑go:

| Provider  | Model id                              |
| --------- | ------------------------------------- |
| Anthropic | `anthropic/claude-opus-5-5`           |
| Anthropic | `anthropic/claude-fable-5-1`          |
| Anthropic | `anthropic/claude-fable-5`            |
| Anthropic | `anthropic/claude-opus-5`             |
| Anthropic | `anthropic/claude-sonnet-5-5`         |
| Anthropic | `anthropic/claude-sonnet-5`           |
| Anthropic | `anthropic/claude-opus-4-8`           |
| Anthropic | `anthropic/claude-opus-4-7`           |
| Anthropic | `anthropic/claude-sonnet-4-6`         |
| Anthropic | `anthropic/claude-haiku-5-5`          |
| Anthropic | `anthropic/claude-haiku-4-5-20251001` |
| Gemini    | `gemini/gemini-4-argon`               |
| Gemini    | `gemini/gemini-3.7-flash`             |
| Gemini    | `gemini/gemini-3.6-flash`             |
| Gemini    | `gemini/gemini-3.5-flash`             |
| Gemini    | `gemini/gemini-3.5-flash-lite`        |
| Gemini    | `gemini/gemini-3.1-pro-preview`       |
| Gemini    | `gemini/gemini-3.1-flash-lite`        |
| Gemini    | `gemini/gemini-3-flash-preview`       |
| Gemini    | `gemini/gemini-2.5-pro`               |
| Gemini    | `gemini/gemini-2.5-flash`             |
| Gemini    | `gemini/gemini-2.5-flash-lite`        |
| Qwen      | `Qwen/Qwen3.5-Plus`                   |

Called on the Enterprise Endpoint, these ids reach the enterprise deployments and draw the allowance. Called on the standard endpoint (`https://api.meganova.ai`), the same ids are ordinary pay‑as‑you‑go models on the shared pool — the base URL is what makes the difference.

Map the **brain / skill / synthesis** tiers to ids from this list — for example a `-pro` model for the brain and synthesis tiers and a `-flash-lite` for the cheap skill tier to stretch the allowance.

**Audio transcription is also covered.** The plan covers the Faster‑Whisper speech‑to‑text model `Systran/faster-whisper-large-v3`, called at `POST https://api.meganova.ai/v1/audio/transcriptions` with the plan key — it draws the **same allowance** (billed per second of audio). Audio is served on the standard endpoint, not the Enterprise Endpoint, and it is not one of the Libra OS LLM tiers above. On any non‑plan key it stays pay‑as‑you‑go as usual.

## Web Search on the plan key

[Managed Web Search](/api-reference/platform-api/search.md) is included in the Token Plan. Calls made with a plan key draw on the same monthly allowance as model usage, at $0.002 per search and per fetch, instead of the ordinary 50/day free pool.

Two things differ from the pay-as-you-go path and are worth wiring correctly:

**The tier gate does not apply.** Web Search normally requires `ENGINEER_TIER_2`. A plan member key is entitled regardless of the account's tier, because the entitlement comes from the subscription. A brand-new account on the plan can search immediately without depositing anything.

**Fan-out needs a signed request group.** One user prompt usually triggers several searches, and you should pay for one. Mint a group per prompt and reuse it:

```bash
# once per user prompt
TOKEN=$(curl -s -X POST https://api.meganova.ai/api/v1/serverless/search/group \
  -H "Authorization: Bearer $PLAN_KEY" | jq -r .data.token)

# every search for that prompt
curl -X POST https://api.meganova.ai/api/v1/serverless/search \
  -H "Authorization: Bearer $PLAN_KEY" \
  -H "X-Request-Group-Id: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"...","max_results":5}'
```

Sending a plain UUID the way a pay-as-you-go integration would is not an error, but it earns nothing: each call is billed as its own prompt. Ten searches for one question then cost ten units instead of one. See [Create Request Group](/api-reference/platform-api/search/create-request-group.md).

Watch consumption in [`GET /serverless/search/usage`](/api-reference/platform-api/search/get-search-usage.md) — the `token_plan` block reports plan searches and allowance percentage. The `quota_*` fields in that same response describe the free daily pool, which plan traffic deliberately never touches — so they stay at `0` unless the same account also calls with a non-plan key.

> Entitlement is **per key**. A search made with any other key of the same account is billed pay-as-you-go from the wallet, exactly like an uncovered model — the same trap described in step 3 above.

## Allowance, Overage & Lifecycle

* **Allowance:** covered‑model calls **and Web Search** on the plan key draw the monthly allowance (not your wallet). Usage resets at the start of each billing period.
* **Overage:** when the allowance runs out, calls hard‑stop unless you enable **Extra usage** on the Libra OS page. Set a monthly limit (at least $5, and below your wallet balance); over‑allowance usage is then charged to your wallet up to that cap.
* **Regenerate:** if your key leaks, regenerate it on the Libra OS page, then update `OPENAI_API_KEY` in your deployment (or hot‑reload via `PUT /api/config/settings`). The old key stops working immediately.
* **Cancel:** cancellation takes effect at period end (no refund or proration); access continues until then.

## Troubleshooting

* **Usage is being charged pay‑as‑you‑go instead of the allowance** — you're calling the standard endpoint instead of the Enterprise Endpoint, calling with a key other than a Libra OS plan key, or using a model that isn't one of the covered ids. Check all three: base URL `https://enterprise.api.meganova.ai`, a plan key, and a covered `provider/model` id (or the covered audio model).
* **Calls return 403 `libra_os_key_required`** — the model is covered by your plan but the request used a key that isn't one of your plan keys. This is deliberate: it stops covered usage from silently billing your wallet instead of the allowance.
* **Calls return 404 / "model not found"** — the model has no enterprise deployment, or the id is missing its `provider/` prefix. `GET https://enterprise.api.meganova.ai/v1/models` lists what the endpoint serves. Note the ids no longer carry an `-Ent` suffix; if yours do, see the migration note in step 2.
* **Calls suddenly fail after a key reset** — you regenerated the key; redeploy with the new key (or hot‑reload via the settings API).
* **Requests stop when usage hits 100%** — the monthly allowance is exhausted; enable **Extra usage** with a limit, or wait for the next billing period.

## Support

Need help? Visit the [FAQ](/faq.md) or contact MegaNova support from the console.