Terminology

This page summarizes key terms used across the docs for consistent understanding.

Core Concepts

BYOK (Bring Your Own Key): A model where users manage their own upstream AI provider API Keys. The system does not provide paid key pools; it only performs encrypted custody of user-owned Provider Keys and decrypts them just-in-time for authorized calls from you and your descendants.
Provider Key / Upstream Key (上游密钥): The original API Key obtained by users from official platforms like OpenAI, Claude, DeepSeek, etc., which is added to the XAI system and stored encrypted.
XAI API Key / Virtual Key (虚拟密钥): The exclusive key assigned by the XAI system to users (format: sk-Xvs...), used to call the XAI Base URL.
Zero Markup Pricing: API call charges are deducted directly from the user's official account, with XAI charging no markup or service fees.
End-to-End Encryption: Provider Keys are encrypted using user-specific keys via the ChaCha20-Poly1305 algorithm; there is no super-admin access, and just-in-time decryption can only be triggered by authorized calls from you and your descendants.

Owner (主账户): A first-level account created by self-signup on xaicontrol.com, with Admin configuration permissions to manage its own third-party AI API Keys and distribute resources to sub-accounts.
Sub-account (子账户): A child account created by the owner inside the system to consume distributed model/quota resources; it does not have Admin configuration permissions.
Descendants (后代用户): Any users in the owner's subtree; see "User Hierarchy".
DNA: Lineage path (e.g., .1.42.) used to filter user groups.
Gear (档位): User attribute that impacts routing/drift strategies.
Tier (层级): User attribute for pricing/permissions.

Level (等级): Abstraction for key pools and model routing. Users can assign different Provider Keys to different Levels.
Key Pool (密钥池): A collection of multiple Provider Keys under the same Level, automatically rotated by the system to distribute request pressure.
Model Mapper (模型映射): Aliasing models to targets (e.g., gpt-4=gpt-4-turbo), configurable at user-level or owner-level.
Level Mapper (Level 映射): Map model patterns to a Level (e.g., claude*=2), routing to the corresponding key pool.
Sleep (休眠): After errors (e.g., 429, 5xx), the key is temporarily removed from rotation and rejoins after a waiting period.
Switch Over (故障切换): Move from one Level to another when the current Level is unavailable.

Resources (资源白名单): Allowed API paths (e.g., /v1/chat/completions).
AllowModels (模型白名单): List of models a sub-account is allowed to call.
AllowIPs (IP 白名单): IP addresses or CIDR ranges allowed to call the API.
Encryption Key (加密密钥): Each user's unique 32-character key used to encrypt that user's Provider Keys.

Factor (因子): Coefficient used in pricing.
Rates (费率倍率): Multiplier applied to model pricing.
Model Limits (模型限速): User-level or model-level throttling policy for RPM/RPH/RPD and TPM/TPH/TPD; model aliases, mapped names, and upstream snapshot names are merged into the effective model for accounting.
Cooldown: Independent penalty window after a limit is hit. Short-window limits renew cooldown on repeated probing; daily limits only cool down until the end of the current day.
RPM/RPH/RPD: Requests per minute/hour/day. RPM/RPH are short-window throttles; RPD is a natural-day request quota based on the server-side business date.
TPM/TPH/TPD: Tokens per minute/hour/day. TPM/TPH are short-window throttles; TPD is a natural-day token quota based on the server-side business date. TPD is accrued after successful usage, so if one successful request pushes the day over the cap, blocking usually starts with the next request.
Credit Balance (信用额度): User's prepaid card balance, used for internal billing statistics (independent of upstream official billing).