Usage Management

Understanding Credits

A credit is the fundamental billing unit in OmniLink. Different operations consume credits at different rates depending on the underlying resource cost. Credits are deducted in real time as you use the platform.

Credits are tracked across five categories:

• AI engine usage — Token-based billing for model inference
• Speech-to-text — Per-second billing for audio transcription
• Text-to-speech — Per-character billing for voice synthesis
• Chat API — Character-based tracking for conversation messages
• ToolRunner sessions — Fixed credits for orchestration

AI Engine Usage

Each AI engine bills based on the number of input and output tokens processed. Token costs vary by model:

Token counts include both the user message and the system instructions. Longer system instructions consume more input tokens on every request. Keep system instructions concise to minimize per-request costs.

Speech-to-Text Usage

The /api/stt endpoint uses OpenAI Whisper for audio transcription. Usage is billed per second of audio processed.

• Audio is not stored after transcription.
• Supported formats: WAV, MP3, M4A, WebM, OGG.
• Maximum audio duration per request: 5 minutes.

To minimize STT costs, trim silence from audio before sending and use voice activity detection (VAD) on the client side to avoid transcribing empty audio.

Text-to-Speech Usage

The /api/tts endpoint uses Google Chirp 3 HD for voice synthesis. Usage is billed per character of input text.

• All characters count, including spaces and punctuation.
• SSML markup characters are excluded from billing.
• Maximum text length per request: 5,000 characters.

For longer content, split text into paragraphs and synthesize them sequentially. This also improves perceived latency since audio starts playing while subsequent segments are being generated.

Chat API Usage

The /api/chat endpoint tracks usage by character count. Both the input message and the AI response contribute to usage. Knowledge base retrieval, when enabled, adds the retrieved snippet length to the input count.

ToolRunner Credits

ToolRunner sessions use a fixed-credit model that keeps costs predictable regardless of session length:

A typical 30-minute ToolRunner session without periodic reviews costs 2 credits (1 kickoff + 1 final). With one periodic review, it costs 3 credits. This is orders of magnitude cheaper than calling the AI at every step.

# ToolRunner cost examples:
#
# Simple task, no reviews:     1 + 0 + 1 = 2 credits
# 30-min session, 1 review:    1 + 1 + 1 = 3 credits
# 60-min session, 3 reviews:   1 + 3 + 1 = 5 credits
# Compare: traditional agent loop for same tasks = 20-100+ credits

Plan Tiers

OmniLink offers four subscription tiers. All plans include access to every AI engine, every API endpoint, and the full Dashboard. The difference is the monthly credit allocation and rate limits.

All plans are billed monthly through Stripe. Credits reset at the beginning of each billing cycle. Unused credits do not roll over.

Monitoring Usage

Dashboard Usage Page

The OmniLink Dashboard includes a real-time usage page that shows:

• Total credits used in the current billing cycle
• Credits remaining until the next reset
• Breakdown by category (AI, STT, TTS, Chat, ToolRunner)
• Daily usage trends over the past 30 days
• Per-engine usage distribution

Usage API Endpoint

Query your usage programmatically with the /api/omni-key-usage endpoint:

from omnilink import OmniLinkClient
import os

client = OmniLinkClient(omni_key=os.environ["OMNI_KEY"])

usage = client.get_usage()
print(f"Credits used: {usage['total']}")
print(f"AI engine: {usage['ai_engine']}")
print(f"STT: {usage['stt']}")
print(f"TTS: {usage['tts']}")
print(f"Chat: {usage['chat']}")
print(f"ToolRunner: {usage['tool_runner']}")

# Direct API call
curl -H "Authorization: Bearer omk_your_key" \
  https://www.omnilink-agents.com/api/omni-key-usage

{
  "total": 142,
  "ai_engine": 98,
  "stt": 12,
  "tts": 18,
  "chat": 8,
  "tool_runner": 6,
  "plan": "Silver",
  "credits_remaining": 358,
  "billing_cycle_start": "2026-03-01",
  "billing_cycle_end": "2026-03-31"
}

Billing and Subscriptions

Stripe Integration

All payment processing is handled by Stripe. OmniLink never stores or processes credit card information directly. Billing features include:

• Automatic monthly billing on the anniversary of your signup date
• Invoices and receipts available in the Dashboard and via email
• Multiple payment methods: credit card, debit card
• Tax calculation based on your billing address

Upgrading Your Plan

You can upgrade your plan at any time from the Dashboard. Upgrades take effect immediately:

• Your new credit allocation is applied instantly.
• Stripe prorates the charge for the remainder of the billing cycle.
• Rate limits are updated immediately.

Downgrading Your Plan

Downgrades take effect at the start of the next billing cycle. Your current plan remains active until the cycle ends, so you do not lose any prepaid access.

Cancellation

Cancel your subscription at any time from the Dashboard. Upon cancellation:

• Your plan remains active until the end of the current billing cycle.
• No further charges are made.
• Data (agents, memory, knowledge) is retained for 30 days after the plan expires.
• After the 30-day grace period, data may be permanently deleted.

Rate Limits

Rate limits are enforced per Omni Key and vary by plan tier. Exceeding the limit returns a 429 Too Many Requests response with a Retry-After header.

If your application regularly approaches the rate limit, consider implementing client-side request queuing with exponential backoff.

Optimizing Usage

Follow these strategies to get the most value from your credits:

Choose the Right Engine

Not every request needs the most powerful model. Use the cheapest engine that meets your quality requirements:

• g1-engine (Gemini) — Use for FAQ responses, simple classifications, and high-volume workloads. It is the most cost-efficient option.
• g2-engine (GPT) — Use when accuracy is critical or the task requires multi-step reasoning.
• g3-engine (Grok) — Use when you need current, real-time information in responses.
• g4-engine (Claude) — Use for nuanced instruction following, complex support interactions, and tasks requiring careful analysis.

Use ToolRunner for Extended Sessions

A 30-minute ToolRunner session costs only 1–2 credits, regardless of how many local actions are executed. If your workflow involves multiple sequential steps, ToolRunner is far cheaper than making individual API calls.

Batch Knowledge Retrieval

Instead of querying the knowledge base on every message, batch related questions together or cache frequently accessed snippets on the client side.

Optimize System Instructions

System instructions are included in every request as input tokens. A 2,000-character system prompt adds cost to every single API call. Keep instructions focused and concise.

Monitor with the Usage Dashboard

Check the usage dashboard regularly to identify patterns. Common findings include:

• A single agent consuming disproportionate credits (optimize its system instructions or switch to a cheaper engine).
• High STT usage from silence in audio streams (add client-side VAD).
• Excessive TTS usage from long responses (summarize before synthesizing).

Alerts and Notifications

OmniLink provides usage alerts to help you stay within budget:

• 75% threshold — Email notification when you reach 75% of your monthly allocation.
• 90% threshold — Email notification with a recommendation to upgrade or reduce usage.
• 100% threshold — API requests return a 402 Payment Required error until the next billing cycle or a plan upgrade.

Alert recipients can be configured in the Dashboard under Settings > Notifications.