Model Discovery

Use the Models page or the Models API to inspect available text models. Model metadata includes vendor, serving provider, modality, context length, supported API families, supported capabilities, availability, account-level limits, and credit pricing.

Endpoint: GET /v1/models Purpose: List models available to the current account.

Copycurl --request GET \
  --url https://api.basicrouter.ai/api/v1/models \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

Capability matrix

API family compatibility matrix

Authentication

Every API request uses a bearer token. Store keys in server-side environment variables, rotate them when team access changes, and log request IDs for debugging.

Key security recommendations

1. Keep API keys on the server. Do not expose keys in browser or mobile client code.
2. Use separate keys for development, staging, production, and third-party integrations.
3. Scope keys by environment, service, customer, or tenant when available.
4. Rotate keys after employee departures, vendor access changes, or suspected leakage.
5. Store keys in secret managers or environment variables, not source code.

Using the Console

The BasicRouter Console is the operational control plane for API access, model availability, routing policies, usage visibility, and billing administration. It gives account administrators a centralized view of keys, models, requests, credits, and account-level controls for production model traffic.

Managing API keys

Create, rotate, revoke, and label API keys from the console. Use separate keys for development, staging, production, and individual services so usage can be audited and isolated by environment or application.

Model list

Use the Models page to review models available to the account. Each model entry may include vendor, serving provider, modality, supported API families, context length, capability flags, availability status, and pricing information.

For production applications, verify model capabilities before enabling traffic. Some parameters and features are model-dependent and may not be supported across all API families.

Usage & logs

The Usage & Logs view provides operational visibility into API traffic. Teams can inspect request volume, selected models, resolved routing targets, credit consumption, latency, error codes, and request IDs.

• Troubleshoot failed requests.
• Identify high-cost workloads.
• Compare model usage across applications and environments.
• Validate routing and fallback behavior.
• Investigate latency or provider availability issues.
• Provide request IDs when contacting support.

Each API response includes or exposes a BasicRouter request ID. Store this ID in your application logs to make production debugging and support escalation more efficient.

Fallback

Fallback is BasicRouter's resilience mechanism. When the primary model or routing policy fails, the system automatically switches to a backup model to keep processing the request. This keeps your application responsive and minimizes the risk of service disruption.

Why fallback matters

In production, model services can run into a number of unpredictable issues:

• Model service failure: the upstream API becomes temporarily unavailable or times out.
• Performance fluctuation: high model load leads to slow or failed responses.
• Routing failure: all candidate models selected by smart routing become unavailable.

Fallback keeps your application available by providing a reliable backup path.

Core advantages

Global fallback model configuration

BasicRouter supports setting a global fallback model from the console backend. All requests automatically use this model as a backup when they fail.

How to configure it:

1. Go to the BasicRouter strategy settings page.
2. Find the Default Fallback Model setting.
3. Select your global fallback model from the dropdown list.
4. Save the setting to apply it immediately.

Advantages of global configuration:

• No code changes required: configure once and it applies globally, with no need to repeat the setting on every request.
• Centralized management: manage the fallback policy in one place for easier adjustment and monitoring.
• Simplified maintenance: reduces code complexity and the chance of configuration errors.
• Flexible override: request-level fallback configuration takes priority and can override the global setting for specific scenarios.

Request-level fallback configuration

For specific business scenarios, you can specify a fallback model on an individual request to override the global configuration.

Specify the fallback model with the router.fallBackModels parameter:

Copy{
  "model": "claude-sonnet-4",
  "messages": [
    {
      "role": "user",
      "content": "Explain what quantum computing is"
    }
  ],
  "router": {
    "fallBackModels": ["glm-5.2"]
  }
}

Priority rules

When multiple fallback configurations are present, priority runs from highest to lowest:

1. Request-level router.fallBackModels: the fallback model specified on an individual request.
2. Global Default Fallback Model: the global fallback model configured in the console.
3. No fallback: if neither is configured, the request returns an error on failure.

Account administration

Depending on account type, the console may include account-level model enablement, reseller or distributor controls, billing configuration, and access settings. Administrators can use these controls to align model access, usage visibility, and billing responsibility with applications, customer accounts, or business units.

Production operations checklist

Billing & Credits

BasicRouter uses a credit-based billing model across text, image, video, and other supported model workloads. Credits provide a unified unit for multi-model and multi-provider usage so teams can manage consumption consistently across modalities and API families.

Detailed model pricing is available on the Models page or through model metadata APIs. Pricing may vary by model, provider, modality, resolution, token type, output length, task duration, account type, and commercial agreement.

Top up & wallet

Accounts may add pay-as-you-go wallet credits for flexible usage. Wallet credits are used after monthly plan credits and resource packs have been consumed, unless a custom billing rule applies to the account.

Wallet credits do not expire unless otherwise specified in applicable commercial terms. Service fee is charged when recharging the pay-as-you-go wallet.

Monthly plans and resource packs

Each user or account can select one active monthly plan. Monthly plans provide a defined amount of usage capacity, commercial terms, and account-level access configuration for the billing period.

Users can also buy multiple resource packs for additional usage capacity. Resource packs can separate committed usage from pay-as-you-go wallet balance and are useful for high-volume text, image, video, or dedicated workload usage.

Deduction order

Unless custom billing rules are configured, credits are deducted in the following order:

For accounts with custom commercial terms, deduction order, expiration rules, included usage, and pricing may differ. Account-specific rules are shown in the console or provided through the commercial agreement.

Custom pricing

Pricing can be customized for each user or account. Enterprise customers, reseller accounts, distributor accounts, and high-volume customers may be eligible for custom pricing. Contact sales for a quote.

Custom pricing can be configured by account, model, provider, modality, region, usage volume, or commercial agreement. When custom pricing is enabled, the console and billing APIs reflect account-specific pricing and deduction rules where available.

Pricing units

Different model modalities use different measurement units. BasicRouter converts these units into credits according to the model’s pricing rules.

Pricing units may vary by model. Always refer to the model detail page or pricing metadata before enabling a model in production.

Usage attribution

BasicRouter usage can be reviewed by account, API key, model, modality, or time range. This allows teams to attribute cost to applications, environments, customers, or internal business units.

Credit balance

Check how many credits are available across your account. The balance is split into three wallets that are deducted in order: the monthly plan allowance, purchased resource packs, and the pay-as-you-go wallet. A combined resource total (monthly plan + resource packs, excluding pay-as-you-go) is also available for tracking included usage separately from top-up spending.

To retrieve this programmatically, see GET /v1/billing/balance in the API Reference.

Usage details

Review a paginated, chronological list of individual usage records for reporting, monitoring, and internal cost allocation. Each record shows the model, model type (text, image, or video), the credits deducted, and a breakdown of which wallet each deduction was drawn from. Results can be filtered to a specific time range.

To retrieve this programmatically, see GET /v1/usage in the API Reference.

Transaction history

Use transaction history to review credit movements, including top-ups, plan allocations, resource pack grants, usage deductions, adjustments, and administrative corrections.

To retrieve this programmatically, see GET /v1/billing/transactions in the API Reference.

Failed requests and refunds

Validation errors, authentication errors, and permission errors are generally not billed because no model execution occurs. Requests that reach an upstream model or generate partial output may consume credits depending on the model, provider, and response state.

For async image and video tasks, billing behavior depends on whether the task was accepted, started, completed, failed, or cancelled. The task detail response includes usage information when credits have been consumed.

Top-ups, monthly plans, resource packs, and consumed credits are non-refundable unless otherwise specified in the applicable commercial agreement or required by law.

Operational

Errors

BasicRouter returns stable error codes so applications can handle retries, fallbacks, billing issues, and debugging consistently.

Provider-compatible endpoints try to preserve the original API family's error shape where possible. BasicRouter-native endpoints use the BasicRouter error object.

HTTP status and error code mapping

Common error codes