--- lastModified: 2026-10-02 --- # Model Routing Model routing decides which provider serves each model Amp uses. By default Amp serves every model and bills your Amp credits. You can add your own connections so that some or all models go through your own API keys, subscriptions, or gateways instead, and your provider bills you directly. Manage your connections in [Model Routing](/settings/model-routing) in your personal settings. Workspace admins manage shared connections for every member in [Workspace Model Routing](/workspace/model-routing). The same operations are available from the CLI with `amp config model-providers` and from [Puck](/docs/puck), which can list, add, test, reorder, and edit your connections when you ask. > **Tip:** We strongly recommend letting Amp or Puck configure your model routing for you, since > they can try a configuration, test it, and fix it in a tight loop, which saves you a lot of time > compared with working through the details by hand. ## Connections A connection is one credential plus its settings. There are four kinds: - **API keys** for a single provider, such as Anthropic, Google AI Studio, Meta AI, OpenAI, or xAI. Usage bills to your account with that provider. - **Subscriptions**, such as a ChatGPT or ๐• Premium+/SuperGrok subscription. You sign in through your browser, and usage counts against the plan's limits. See [Use a ChatGPT Subscription](/docs/the-dial#use-a-chatgpt-subscription). Sign in with ChatGPT also signs you in to Amp, so each ChatGPT account can connect to only one Amp account. To use one ChatGPT account from several Amp accounts, choose **Add โ†’ ChatGPT (Legacy)** in personal Model Routing on each of them instead. - **Cloud platforms**, such as [Amazon Bedrock](/docs/model-routing/amazon-bedrock) and [Google Cloud Agent Platform (Vertex)](/docs/model-routing/google-cloud-agent-platform). Usage bills to your cloud account. Follow the linked guides to set up a connection. - **AI model routers and gateways**, such as OpenRouter, Vercel AI Gateway, Cloudflare AI Gateway, Ollama Cloud, OpenCode Go, and any OpenAI- or Anthropic-compatible endpoint through a Custom URL connection. These can serve models from many providers through one credential. They are available to all users on every tier. The **Add** menu in Model Routing lists the connection types available to you. Personal connections apply to your own threads. Workspace connections apply to every member's threads, and Enterprise workspace admins can forbid personal connections so that only the workspace's apply. See [Workspaces](/docs/collaborate/workspaces). Each connection has a **Check Access** button that verifies the credential with the provider. From the CLI, `amp config model-providers test ` does the same, and `amp config model-providers check-access --provider-model ` runs one short inference and reports which connection actually served it. ## Precedence For each model, Amp tries your connections in order and uses the first active one whose [model mapping](#model-mappings) includes that model. Anything no connection serves is served by Amp. The order is: 1. Your personal connections, from top to bottom as listed in Model Routing. 2. Your workspace's connections, from top to bottom. 3. Amp. Within a list, the order is the connection's priority: `0` is tried first. Drag a connection by its handle in Model Routing to move it, or set its priority directly: ```shell-session amp config model-providers list amp config model-providers set-priority 0 ``` Setting a priority that another connection already has moves that connection and the ones after it down one place, so `0` always means "try this connection first". `list` and `list --json` show the current priority of each connection. Two connections often cover the same model, for example a ChatGPT subscription and an OpenRouter router that both include `openai/gpt-5.6-sol`. The one higher in the list wins. To send only some models to a lower connection, exclude them from the higher connection's model mapping rather than reordering. The routing graph below the connection list shows which connection serves each model, so you can confirm the result after changing the order or a mapping. ## Painter If Google Painter is enabled for your account, open [Mode Dial](/settings/dial) in your personal settings and choose **Tune Modes โ†’ Painter**. Select **Nano Banana 2** instead of **Auto ยท Amp** and click **Save**. The choice applies to your web and CLI threads. Amp remains the default and uses Amp credits. Gemini requires an active **Google AI Studio** API key connection. Google bills image generation to the API project, separately from any Gemini consumer subscription. Workspace token fees still apply where applicable. A ChatGPT or Gemini subscription does not supply this API access. Your existing connection order, model mappings, and workspace policy decide which connection serves `google/gemini-3.1-flash-image`. If another connection takes priority, move the AI Studio connection above it or exclude this model from the higher connection. If the selected connection is not AI Studio, or the request fails, Painter reports an error instead of using Amp credits. Gemini supports image generation and editing with reference images, but not transparent backgrounds. Select **Auto ยท Amp** when you need a transparent result. You can return to Amp even if Google Painter is no longer enabled for your account. ## Activate and Deactivate Inactive connections are skipped during routing but keep their settings, so you can switch a connection off and on without re-entering its key. Expand the connection in Model Routing and use **Activate** or **Deactivate**, or: ```shell-session amp config model-providers activate amp config model-providers deactivate ``` Multiple API keys for the same provider can be active at once. Model mappings and priority determine which key serves each model. AI model routers and Custom URL connections can also be active together. Subscriptions allow only one active connection of each subscription type per user. For example, activating a ChatGPT subscription deactivates your other active ChatGPT subscription, but leaves your OpenAI API keys active. Deactivating a subscription can cost more than it saves, because Amp then serves those models with your credits. The CLI asks for `--yes` before it deactivates a subscription. ## Model Mappings A model mapping controls which models a connection serves and, for routers and Custom URLs, what model ID the provider receives. Leave it empty to use the connection type's default: for most types, every model the provider supports. Google Cloud Agent Platform and Amazon Bedrock connections serve no models until you choose some. Write one pattern per line, using Amp's canonical model IDs in `provider/model` form. The **Models** picker in the connection form searches the catalog and inserts an ID for you. ```text */* # include every model -anthropic/* # then exclude all Anthropic models anthropic/claude-fable-5 # but re-include this one moonshotai/kimi-k3 -> kimi-k3-turbo # include, and send kimi-k3-turbo to the provider ``` - `#` starts a comment; blank lines are ignored. - `*` is allowed only at the start or end of a pattern: `openai/*`, `*-mini`, or `*/*`. - A leading `-` excludes matching models. - The last matching line wins. Models that match no line are not served by the connection. - An exact include line may end with `-> providerModelID` to override the model ID sent to the provider. The line still takes part in matching. Arrows are not allowed on wildcard or exclude lines. Without an arrow, the connection type's default provider model ID is used. For Amazon Bedrock, wildcard matches apply only when Amp knows the Bedrock model ID. Otherwise, Amp skips that connection and follows the remaining routing order, which may use another provider or Amp credits. An exact model selection still reports an error if its Bedrock ID is unknown. Use `model -> bedrock-model-or-inference-profile-id` to supply the ID yourself. Once Amp adds a model's Bedrock ID, matching wildcards automatically route it through Bedrock. From the CLI, pass the same patterns comma- or newline-separated with `--model-mapping`, or `--clear-model-mapping` to return to the default: ```shell-session amp config model-providers edit-router --model-mapping "*/*,-openai/gpt-5.4" amp config model-providers edit-key --model-mapping "anthropic/claude-opus-4-6" ``` The connection form and `show` report nonblocking warnings about a mapping, for example a line that names a model the provider does not offer or an option the provider requires for it. A warning does not stop the connection from being saved or used. ### Custom URL Connections A Custom URL connection speaks one of four API formats. Enter the base URL, and Amp appends the API path for the format: - `chat-completions` (OpenAI Chat Completions API, the default) sends requests to `/chat/completions`. - `responses` (OpenAI Responses API) sends requests to `/responses`. - `anthropic-messages` (Anthropic Messages API) sends requests to `/v1/messages`. A base URL that already ends in `/v1` is accepted and not doubled. - `google-genai` (Google Generative AI) sends native Gemini requests to `/models/:streamGenerateContent?alt=sse`. Use `https://generativelanguage.googleapis.com/v1beta` for an AI Studio key. For a Vertex API key, use `https://aiplatform.googleapis.com/v1`; Amp sends those requests to `/publishers/google/models/:streamGenerateContent?alt=sse`. This format routes Gemini models only by default. Google Cloud Agent Platform still uses workload identity, not an API key, and can also serve Claude models. For example, a base URL of `https://api.example.com/v1` with `chat-completions` sends requests to `https://api.example.com/v1/chat/completions`, while `https://api.example.com` with `anthropic-messages` sends them to `https://api.example.com/v1/messages`. The connection form shows the exact request URL as you type. Amp warns if the base URL already contains the API path. The key is sent as `Authorization: Bearer ` for the OpenAI and Anthropic formats. Google Generative AI sends it as `x-goog-api-key` by default. To use a bearer token instead, enter `Bearer ` in the API key field. Amp then sends only `Authorization: Bearer `, not an API-key header. Use the **Headers** settings or `--headers` in the CLI when a provider needs additional headers. Query Parameters are available for the other formats, but not Google Generative AI. For a private Gemini model on a Vertex endpoint, choose `google-genai`, enter the base URL including the API version, and map the Gemini model your agent uses to the full endpoint resource: ```text google-vertex/gemini-3-flash-preview -> projects/your-project/locations/us-east5/endpoints/123 ``` With the base URL `https://us-east5-aiplatform.googleapis.com/v1`, this sends requests to `https://us-east5-aiplatform.googleapis.com/v1/projects/your-project/locations/us-east5/endpoints/123:streamGenerateContent?alt=sse`. Custom HTTPS hosts work too, provided they are reachable from Amp and implement the same Gemini API. Full resource paths beginning with `projects/` or `publishers/` are preserved. A mapping changes where that Gemini model runs; it does not change the model selected by your agent. Store the bearer token in the connection's API key field, not in thread settings or custom headers. Amp uses the supplied credential, not its own Google credentials. You must replace the token when it expires; Custom URL connections do not refresh OAuth tokens. Check Access on a Custom URL connection lists the provider's models when the mapping is broad, and sends a one-token request for the mapped model when the mapping names exactly one model. For Google Generative AI it sends a one-token Gemini request rather than listing models. Providers that respond to an invalid key with an HTTP 200 body containing an error are reported as failures with the provider's message.