MODELS & ROUTING
Models, Providers & Routing in Antigravity Manager
Choose a model from your running Manager, send a short request, then add a routing rule if your client needs a different model name. This guide explains how to check the model used, fix access problems and control thinking settings.
Antigravity Tools 5.0.0 · Separate notes for 5.0.1-beta.6 · Updated
- Client modelThe name you select
- Routing ruleThe target Manager resolves
- AccountAccess and available quota
- Upstream modelThe model sent to the service
Which model handles your request?
Manager resolves the model name sent by your client, selects an account and prepares the upstream request. A custom rule or an account-specific replacement can change the model along the way.
For example, you can map a client name such as gpt-demo to a Gemini model. The client keeps sending that name, while Manager calls the configured Gemini target. An OpenAI-compatible connection lets the client use OpenAI’s request format with the models behind Manager.
Check the matching request in API Monitor Dashboard when you need to know which model was used. On supported OpenAI-compatible responses, X-Mapped-Model shows the routed name and X-Upstream-Model shows the model recorded at the upstream stage. If those headers are absent, inspect the matching logs and outbound payload using the request checks below.
1. Find models your gateway exposes
Open API Proxy → Model Config → Model Router to choose a target, or request GET /v1/models from the running proxy. Use the exact ID returned by your installation for the first test.
- Start the proxy and check that an account is enabled for API requests. The proxy setup guide covers the address, API key and first request.
- Refresh the account’s quota information if its model list is missing or stale.
- Select a text model with available quota and send a short greeting through your client. Leave tools, images and custom reasoning parameters off for this first request.
- Once that works, use the same model as the target of any custom alias.
List models and send an optional test with Python 3
Save this script as check_gateway_model.py. Run python3 check_gateway_model.py on macOS/Linux or py check_gateway_model.py on Windows. Enter the proxy URL and gateway key. The script lists model IDs; press Enter to finish, or enter an ID or alias to send one short request, which uses account quota.
import getpass
import http.client
import json
import sys
import urllib.error
import urllib.parse
import urllib.request
class NoRedirect(urllib.request.HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
root = input("Proxy URL [http://127.0.0.1:8045]: ").strip()
root = (root or "http://127.0.0.1:8045").rstrip("/")
try:
parts = urllib.parse.urlsplit(root)
except ValueError:
sys.exit("Invalid proxy URL.")
if (parts.scheme not in ("http", "https") or not parts.hostname
or parts.username is not None or parts.password is not None
or parts.query or parts.fragment):
sys.exit("Use an http(s) proxy URL without credentials, query or fragment.")
if root.endswith("/v1"):
root = root[:-3]
key = getpass.getpass("Manager API key (hidden): ").strip()
if not key:
sys.exit("Enter the API Proxy key.")
opener = urllib.request.build_opener(NoRedirect)
def send(path, payload=None):
headers = {"Authorization": "Bearer " + key}
data = None
if payload is not None:
data = json.dumps(payload).encode("utf-8")
headers["Content-Type"] = "application/json"
request = urllib.request.Request(root + path, data=data, headers=headers)
with opener.open(request, timeout=60) as response:
result = json.load(response)
for name in ("X-Mapped-Model", "X-Upstream-Model"):
value = response.headers.get(name)
if value:
print(name + ":", value)
return result
try:
result = send("/v1/models")
if not isinstance(result, dict) or not isinstance(result.get("data"), list):
sys.exit("Unexpected catalog format. Check the proxy URL.")
ids = [m["id"] for m in result["data"]
if isinstance(m, dict) and isinstance(m.get("id"), str)]
print("\n".join(ids) if ids else "The catalog is empty.")
model = input("Model to test (Enter to finish): ").strip()
if model:
answer = send("/v1/chat/completions", {
"model": model, "stream": False,
"messages": [{"role": "user", "content": "Reply with a short hello."}]
})
print(json.dumps(answer, indent=2, ensure_ascii=False))
except urllib.error.HTTPError as error:
sys.exit("HTTP " + str(error.code) + ". Check the matching request in Manager.")
except (OSError, http.client.HTTPException):
sys.exit("Connection failed or timed out. Check the proxy host, port and service.")
except (ValueError, UnicodeError):
sys.exit("Invalid URL or JSON response. Check the proxy address and request log.")The script accepts the proxy root or a URL ending in /v1. For an HTTPS gateway, use its configured HTTPS address. If you prefer your existing API client, use the request body below.
Why the model list can differ between accounts
The catalog combines model information collected from connected accounts. With Only Expose Quota Models off, Manager can also show custom aliases and a built-in list while account metadata is still loading. With it on, the list starts from account quota models; derived names without tier suffixes can still appear.
Check the chosen account’s access and quota when a listed model fails. For a newly available family such as Argon, refresh the account metadata and copy the ID it exposes. Use the quota guide to understand shared pools and refresh timing.
2. Add one model-routing rule
Use Custom Mappings in Model Router to connect a client’s model name to a working target. Begin with one exact rule so you can compare its result with the direct request.
- Save your current rules before changing them. Save Current Mapping opens the preset dialog; under Save Current Configuration, enter a name and click Save. Also keep a separate copy of important rules. Presets are stored in the current browser or app’s local storage.
- Under Add Mapping, enter the name your client sends in the original-model field, for example
gpt-demo. - Choose your working model in Select Target Model, then click Add. The rule is saved immediately.
- Set your client’s model to
gpt-demoand repeat the short request. Compare the mapped and upstream names with the direct-model test.
A rule with the same original name replaces that name’s current target. Applying a preset merges its rules into the active set and overwrites matching names; other rules remain. Review the full list after applying a preset.
Which rule takes priority in Manager 5.0.0?
- An official replacement for a retired model ID, when Manager has received one.
- An exact custom rule for the original string.
- A case-insensitive custom match, then a match using normalized Claude names.
- A wildcard rule. The matching pattern with the most characters other than
*wins. - Built-in handling of model IDs, aliases and reasoning tiers.
Avoid overlapping wildcard patterns of equal specificity and conflicting names that differ only by case. Make one rule more specific or use an exact rule. Moving rows in the displayed list cannot resolve a tied match.
For example, gpt-demo-* takes priority over gpt-* for gpt-demo-v2. Keep wildcard rules narrow: a broad rule changes every matching client request, including requests from other connected applications.
See which rule matches a model name
The examples below show how one set of rules selects its routing target. Choose targets from your own gateway’s catalog when adding equivalent rules; the account and final upstream model are checked when the request runs.
Show the example mapping rules
Each key is a client model name or pattern, and each value is its target. Enter these pairs through Custom Mappings, or merge the object into proxy.custom_mapping if you manage the configuration file yourself.
{
"gpt-demo": "gemini-3.1-pro-high",
"gpt-*": "claude-sonnet-4-6",
"gpt-demo-*": "gemini-3.1-pro-low",
"claude-opus-4-6": "claude-opus-4-6-thinking"
}4 examples
| Client sends | Routing target | Why this rule wins |
|---|---|---|
gpt-demo | gemini-3.1-pro-high | The exact rule takes priority over gpt-*. |
gpt-demo-v2 | gemini-3.1-pro-low | gpt-demo-* is more specific than gpt-*. |
GPT-DEMO | gemini-3.1-pro-high | The same exact rule matches after case normalization. |
anthropic/claude-opus-4.6 | claude-opus-4-6-thinking | The Claude name is normalized before matching the rule. |
An official retired-model replacement takes priority over these custom rules. On 5.0.1-beta.6, the inbound model check also rejects retired families before custom mapping.
Why does one model work while another fails?
Each model needs an eligible account, usable quota and a request format it accepts. Start with the error returned by the failing model, even when another model works with the same key.
- Opus or Pro fails while Flash works
- Refresh the account data and check that an enabled account exposes the exact target model with remaining quota. Manager uses model capability information when choosing accounts; it also considers quota and scheduling state. Follow the account setup and quota and pool checks.
- I have an Ultra or Pro subscription
- Check that account’s current model list. Subscription tier is one selection input; access to a particular model can differ between accounts. When model metadata is absent, the advanced-model selector can fall back to paid-tier checks.
- The error is 400 and names a parameter
- Inspect that field in the request. For example, an error naming
safety_settings[4]points to the fifth safety-settings entry. Retry a plain text request, then check the client’s model adapter and version before changing account routing. - The model returns 429 or 503
- Check the model’s quota, temporary rate limits and the matching request log. Use limit troubleshooting to distinguish an exhausted pool from a temporary upstream failure.
When can Manager choose a replacement model?
After selecting an account, Manager can use a compatible model ID advertised by that account. In 5.0.0, supported Gemini Pro aliases have an ordered list of same-family replacements. Image replacements stay within the requested Pro-image or Flash-image family.
If the requested model is available, it stays first. If no supported replacement is found, the original target continues through the request and may return an error. Check Dynamic-Model-Rewrite entries and the final request when investigating a changed model. Set an explicit custom rule if you deliberately want to switch to another family.
3. Choose who controls thinking settings
Open API Proxy → Model Config → Thinking Settings, then use Authority Source in Thinking Budget Control. Choose the source that should control reasoning settings for your requests.
| Authority source | What to configure |
|---|---|
| Gateway Authoritative Control | Set the model family’s mode and budgets in Manager. Client effort levels can select the corresponding gateway values. |
| Client Direct Control | Set thinking parameters in your client. Manager converts them for the upstream request; model-specific validation and adjustments still apply. |
For budget-based models, Default Mode (Upstream Adaptive) uses model defaults, while Custom Budget Mode (Recommended) exposes the family’s configured values. The Adaptive (-1) value asks Manager to use model defaults; the outgoing request can still contain a model-defined budget or level. Models that use named thinking levels follow their own level settings. Save changes with Save & Hot Reload Thinking Config.
Effort, thinkingLevel and thinkingBudget: which field should I use?
- Effort is a level requested by the client, such as low, medium or high. Its setting name depends on the client and protocol.
thinkingLevelcarries a named level in the upstream request.thinkingBudgetcarries a numeric token budget in the upstream request. A client may express it with a different name, such asbudget_tokens.
Use your client’s supported setting, then check Manager’s converted request. For example, a high-effort Claude request under gateway control can become the configured numeric budget. Avoid adding several alternative thinking fields to the same request.
- Save the current authority source, mode and family values.
- Keep the model and prompt fixed. Send one request with the current settings.
- Change one budget or effort setting, save, and send the same request again.
- Compare
generationConfig.thinkingConfigin the corresponding outbound requests and confirm that both answers finish. If a 400 names a thinking field, restore the working value and check that model’s limits.
Use the OpenCode variant instructions or Claude Code setup for client-specific settings. A numeric budget may be capped or adjusted alongside the output-token limit, so inspect the final fields when a value appears to be ignored.
Which provider and API key should the client use?
Choose the connection by its base URL. A profile pointing to Manager uses the gateway key; a profile pointing directly to another API service uses that service’s credentials and model list.
- Manager gateway: your client calls Manager’s proxy address, and Manager selects from its connected accounts.
- External API profile: OpenCode profiles created for services such as APIKEY.FUN use their own URL, key and quota. Select that profile’s provider/model reference in OpenCode.
- Direct OAuth plugin: the plugin handles authentication and accounts through its own provider configuration.
Keep the gateway key, external service key and OAuth account tokens in their respective settings. The client connection guide lists the appropriate protocol and base URL for each application.
What if an older guide tells me to configure z.ai?
For a direct z.ai connection, use the client’s supported provider setup with that service’s address and key. The Manager 5.0.0 configuration covered here has no z.ai-specific settings. Keep older z.ai configuration keys out of this gateway setup.
5.0.1-beta.6: model errors before forwarding
In 5.0.1-beta.6, Manager checks the requested model and pool quota before sending it upstream. Use the following checks for this prerelease; the rest of this guide uses 5.0.0.
| Error or condition | Next step |
|---|---|
| 404 · model not exist | Check for an empty, misspelled or retired model ID. Then inspect the custom target and refresh the model catalog. |
| 502 · no quota accounts | Refresh quota data and check that an eligible account has positive quota for the resolved model. Choose another working model or wait for that quota to reset. |
| Pool metadata is still empty after startup | Wait for account model data to load and retry. After checking missing and retired IDs, the gate allows requests while this data is absent. |
| An old alias stopped working | The retired-family check runs before custom mapping. Replace retired Claude versions below 4.6 and Gemini 2.x request names with a supported current ID; image families have separate handling. |
Keep the exact error message when diagnosing 404 or 502: other components can return those status codes too. See the 5.0.1-beta.6 release notes for the model-gate changes.
Check the model used for one request
Compare a direct-model request with the same request sent through your alias. Use the same client, protocol and prompt, and match each result to its timestamp in Manager’s API Monitor Dashboard.
For an OpenAI-compatible client, send this body to POST /v1/chat/completions with your Manager gateway key. Replace MODEL_ID with the working model first, then with your alias. The Python helper performs this request and prints the model headers when returned.
{
"model": "MODEL_ID",
"stream": false,
"messages": [
{ "role": "user", "content": "Reply with a short hello." }
]
}- Record the model your client sent and the matching routing rule.
- Compare
X-Mapped-ModelandX-Upstream-Modelwhere available. Check the selected account in the matching private log entry. - If the names differ, inspect the account-specific rewrite and converted outbound request. For thinking settings, inspect
generationConfig.thinkingConfig. - If the request fails, identify whether Manager rejected it locally or the upstream service returned the error. Use logs and diagnostics for collecting the relevant request details.
Keep keys, tokens, account identifiers and personal prompts out of shared logs. Use a short test prompt and remove unrelated request data before opening a Manager issue.
Undo routing and thinking changes
Remove the test rule with its delete control, or restore the previous target for the original name. Restore the authority source, thinking mode, budget values and client model you used before the test.
Reset Mapping clears all custom mappings, including a custom background-task rule. Use it when you intend to clear that entire set. To restore a saved preset exactly, also remove newer rules you no longer need: applying the preset merges it with the remaining rules.
Repeat the original short request after restoring settings. If it still fails, follow connection troubleshooting for reachability and authentication, or quota troubleshooting for model and pool limits.
Related guides and documentation
Continue with AI client setup, quotas and account rotation or the API reference. Return to the setup guide for the full installation path.