API Keys & Budgets

API keys in ModelHive are budget-aware — each key has its own spending limit drawn from the tenant's wallet.

Creating an API Key

API keys are created from the ModelHive Dashboard:

1. Go to Dashboard → API Keys
2. Click Create New Key
3. Configure the key settings:

Setting	Description
Name	A human-readable label (e.g., "backend-production")
Budget	Maximum spend in USD — deducted from your wallet
Models	Optionally restrict to specific models (empty = all models)
Metadata	Custom tags (environment, team, service)

4. Click Create and copy the generated key (starts with sk-)

warning

The full API key is only shown once at creation time. Store it securely — it cannot be retrieved later.

Using Your API Key

Use your key with any OpenAI-compatible SDK or HTTP client:

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-modelhive-key",
    base_url="https://api.modelhive.ai/v1"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}]
)

Key Properties

Each API key has the following configurable properties (managed from the dashboard):

Property	Description	Default
key_alias	Human-readable name	Required
max_budget	Maximum spend in USD	None
models	Restrict to specific models	All models
auto_recharge_enabled	Automatically recharge from wallet when low	false
recharge_threshold	Budget threshold to trigger recharge	$10.00
recharge_amount	Amount to recharge when triggered	$50.00
budget_alerts_enabled	Send alerts when approaching budget limit	true
budget_alert_threshold_pct	Alert at this % of budget consumed	30%

Managing Keys

All key management is done through the Dashboard:

• List keys — View all keys for your tenant with current spend
• Update a key — Change budget, models, or auto-recharge settings
• Delete a key — Unused budget is automatically refunded to the wallet

info

When you increase a key's budget, the difference is deducted from the wallet. When you decrease it, the excess is returned.

The funding gate

A key is refused before the request reaches a provider when it cannot pay for the model it named. The check is per model, not per key: what matters is whether serving that particular model costs the gateway money.

Situation	Outcome
The model is not billed to the gateway	Allowed, whatever the budget
Budget is zero or unset, on a billed model	429 budget_exceeded — no budget
Spend has reached the budget, on a billed model	429 budget_exceeded — budget spent
Master key, or a pass-through caller with its own upstream credentials	Allowed — neither carries a budget, and neither should be asked for one

The two refusals are worded differently on purpose. Telling a key that has spent its budget that it never had one sends whoever reads the error looking for the wrong thing.

{"error": {"code": "budget_exceeded",
           "message": "this API key has no budget and \"gpt-4o\" is billed to the gateway: set a budget, or use a model served by an OAuth pass-through deployment"}}

The gate covers every route that can reach a provider — chat completions, messages, responses, completions, embeddings, moderations, image generation and audio — not only the conversational ones.

An empty whitelist is not an unusable key

A key with no budget and no model whitelist is still useful: an empty whitelist means every model, which includes the ones the gateway does not pay for, and those need no budget. That is why key creation does not demand a budget up front.

Auto-Recharge

Enable automatic budget refills so your keys never unexpectedly stop working. When a key's remaining budget drops below the threshold, ModelHive automatically transfers funds from your wallet.

See Auto-Recharge & Budget Alerts for more details.

Budget Transfer

You can transfer budget between your wallet and a specific key from the Dashboard — useful for reallocating budget across keys without creating new ones.