Invocation Guide and Routing Instructions

Applicable roles: Developer, Organization (top-level user), Sub-user Updated: 2026-07-14

This document explains how to fill in the model field when making calls, which route the request takes, and where to find the call name.

1. Basic Routing: Calling by Model Name

In the vast majority of cases, you only need to fill the model field with the model name (such as gpt-4o or claude-sonnet-4-6), and the system automatically selects a routing group for you.

Route Resolution Priority

When you call by model name, the system looks up which group the model should use in the following order, stopping at the first match:

• A match at any layer above routes to that group, and no further lookup is performed
• If none of the four layers match, the call is rejected
• When the selected channel is unavailable, the platform returns an error directly — it does not automatically switch channels, downgrade, or fall back

Default Route Configuration

Organizations and sub-users can specify which group each model name defaults to, without binding it separately on every Key. The configuration entry is in the console; it can be set per model or in bulk by provider.

The usage records show a route source label for each call (Key-bound group / sub-user default / organization default / platform default), making it easy to trace how the route was resolved.

Default model configuration page:

If the group in the default route configuration has been removed or no longer includes the model, the call will error out rather than silently falling back to another group. In this case, you need to reconfigure the default route.

2. Advanced Routing: Calling by Group Identifier (must be enabled)

The platform provides an advanced routing capability — group-identifier routing. Once enabled, you can prefix the model name with a group identifier (such as 5MHXZWKA/gpt-4o) to precisely "name" a specific group to use, unaffected by Key bindings or default route configurations.

Enablement Conditions

Group-identifier routing is disabled by default and requires both of the following conditions to take effect:

1. The platform has enabled the global group-identifier routing switch
2. The organization (primary user) has enabled group-identifier routing in its own account

Once both switches are on, the organization and all of its sub-users can use group-identifier call names.

Group-Identifier Call Name Format

<group identifier>/<model name>

Example: 5MHXZWKA/gpt-4o

• 5MHXZWKA is the group's identifier — a short string identifier the platform automatically assigns to each routing group, which remains unchanged after creation
• gpt-4o is the model name
• On call, the request is fixed to route to the group corresponding to that group identifier, independent of the Key-bound group and default route configuration

The "Call Guide" Page

The "Call Guide" entry in the left-hand menu of the console is always visible. This page lists currently available models by group. Once group-identifier routing is enabled, each model provides two copy buttons side by side — model name and with group identifier:

• Model name button: copies the model name (such as claude-sonnet-4-6), using basic routing
• Group identifier button: copies the call name with the group identifier (such as 5MHXZWKA/claude-sonnet-4-6), using group-identifier routing

The page supports switching between provider tabs, keyword search, and filtering by dedicated/public groups.

When group-identifier routing is not enabled, the Call Guide page does not display group-identifier call names, and calls with a group-identifier prefix are rejected. Model names can also be obtained from the Model Marketplace (no login required) or via the /v1/models API.

Dispatch Group Allowlist (organization-configurable only)

After enabling group-identifier routing, an organization can also configure a "Dispatch Group Allowlist" for a Key to restrict which groups group-identifier calls can reach. This is an advanced option that sub-users cannot configure and that most scenarios do not require.

3. Complete Route Resolution Flow

When the platform receives a request, it first checks whether the model field contains a group-identifier prefix (contains /):

Does the model field contain "/" ?
├── Yes (e.g. 5MHXZWKA/gpt-4o)
│   └── Is group-identifier routing enabled?
│       ├── Yes → parse the group identifier, route to the corresponding group
│       └── No → reject (group-identifier routing not enabled)
└── No (e.g. gpt-4o)
    └── Look up by priority: Key-bound group → sub-user default → organization default → platform default
        ├── Match → route to that group
        └── No match at all → reject

4. Which to Use in Which Scenario

5. Call Examples

Model name (basic routing):

curl YOUR_API_BASE_URL/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "你好"}]
  }'

With group identifier (group-identifier routing, must be enabled):

curl YOUR_API_BASE_URL/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "5MHXZWKA/gpt-4o",
    "messages": [{"role": "user", "content": "你好"}]
  }'

For general rules such as endpoints, authentication, and streaming, see API Call Basics.

6. FAQ

Q: Do I have to enable group-identifier routing? A: No. For most scenarios, the model name is sufficient, and the system automatically resolves the route based on the Key-bound group or default route configuration. Group-identifier routing is an advanced capability that you enable as needed.

Q: Is there any billing difference between using a group identifier and a model name? A: Billing is priced according to the group actually matched. It is independent of how the call name is written and depends on which group the request ultimately routes to.

Q: Can I mix model-name and group-identifier calls on the same Key? A: Yes (when group-identifier routing is enabled). The platform determines the route for each request based on whether its model includes a group identifier.

Q: What should I do if a group-identifier call reports "group unreachable"? A: This means the group corresponding to that group identifier is not within your account's available scope, or the channel is currently unavailable. Confirm the available scope or contact the platform.

Q: The default route is configured, but the call errors out? A: Check whether the configured group still includes the model — after a group is removed or a model is taken out, the corresponding default route configuration becomes invalid and must be reconfigured.

Q: What is the "route source" in the usage records? A: It indicates which layer this call's route was resolved through (group identifier / Key-bound group / sub-user default / organization default / platform default), making it easy to trace how the route was resolved.

Q: What happens to existing group-identifier calls after group-identifier routing is disabled? A: They are rejected. After group-identifier routing is disabled, all calls with a group-identifier prefix are no longer recognized, and you must switch to model names.