Admin guide
Group management
Groups isolate channel access and billing ratios for different users
Groups tie users, tokens, and channels together: a user can only use channels that match their group, and each group can have its own billing ratio (group_ratio). Admins list groups with `GET /api/group/` and maintain group names and ratios through the `prefill_group` API. The web console page follows the reference design and is still being wired up.
How groups are used
Groups span three layers of configuration—users, tokens, and channels—and together decide who can use which channels and at what billing ratio:
User groups
Assign a user's group (user.group) when editing the user. Users can only use channels that match their group, and Model Square and pricing also show available models and ratios based on the user's group.
Related field: user.group · See User management
Token groups
Specify the channel group (token.group) when creating or editing a token. API calls are routed by matching the token's group against channel.group and the ability table. You can enable “Cross-group retry” to try other groups when the preferred group has no available channel.
Related field: token.group · See API keys
When a token's group is set to `auto`, the system picks an available group in priority order, which is useful when you need failover across groups.
Channel groups
Set the group (channel.group, default: default) when adding or editing a channel. A channel takes part in routing only when the user or token group matches the channel group.
Related field: channel.group · See Channel management
Configure group ratios
Group names and billing ratios are maintained through the prefill group API. The group_ratio returned by `GET /api/pricing` is reflected in the group filters and ratio badges in Model Square.
| Field | Description |
|---|---|
name · Group name | For example default, vip, or test; corresponds to the group field on user / token / channel |
ratio / group_ratio · Billing ratio | Multiplier relative to the base price, shown as e.g. 1.5x in Model Square and the pricing API |
description · Description | Optional; helps admins identify the group's purpose |
Related APIs
| API | Description |
|---|---|
GET /api/group/ | Returns existing groups and their ratios |
GET|POST|PUT|DELETE /api/prefill_group/ | Create, update, and delete group definitions |
GET /api/user/groups | No sign-in required; used for registration or display |
Channel routing also relies on the ability table (group + model + channel_id), which declares which channel forwards a given model for a given group. For details on ratios and group differences, see the Pricing docs.