On this page
- 01What you'll set up
- 02How a model name becomes a provider
- 03Use a model name without a provider
- 04What decides the choice
- 05A worked example
- 06Connect the providers you want to choose between
- 07Narrow the choice with policy lists
- 08Use it from your SDK
- 09See the choice before you send
- 10See what was chosen
- 11Own keys first, credits as the backstop
- 12When a model cannot be served
- 13Keep it as code
- 14If something goes wrong
01
What you'll set up
The same model is often sold by more than one provider. Claude models run on Anthropic, Vertex AI, and Bedrock. GPT models run on OpenAI and Azure. In about ten minutes you will send a request by model name alone and let Cloptima choose the provider, with your policy and your credentials deciding what is possible.
- Requests that name a model, not a provider
- Credentials for the providers you want to choose between
- Policy lists that keep the choice inside what you allow
- A way to see the choice before you send, and after
You need an owner or admin role, a virtual key, and a policy bound to your traffic.
02
How a model name becomes a provider
When a request names only a model, Cloptima lists every provider that serves it and narrows the list in order. The first provider left is used.
1Model named
claude-opus-5-5
2Providers listed
Anthropic, Vertex AI, Bedrock
3Your rules applied
Policy lists, credentials, health
4Best price chosen
Your own keys first
5Request sent
To that provider
The rest of your pipeline sees an ordinary request to that one provider, so budgets, rate limits, guardrails, and caches all work as they always do.
03
Use a model name without a provider
Send the plain model name. Add a provider prefix only when you want to pin the request to one provider.
| Model field | What happens |
|---|---|
| claude-opus-5-5 | Cloptima chooses among Anthropic, Vertex AI, and Bedrock |
| anthropic/claude-opus-5-5 | The request goes to Anthropic |
| gpt-4o-mini | Cloptima chooses between OpenAI and Azure |
| openai/gpt-4o-mini | The request goes to OpenAI |
| gemini-2.5-flash | Cloptima chooses between Gemini and Vertex AI |
curl https://api.cloptima.ai/v1/ai/chat/completions \
-H "Authorization: Bearer $CLOPTIMA_VIRTUAL_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "claude-opus-5-5", "messages": [{"role": "user", "content": "Say hello"}]}'04
What decides the choice
Cloptima applies the same rules to every request, in this order.
| Step | Rule | Effect |
|---|---|---|
| 1 | Retired models | A provider that has retired the model is skipped |
| 2 | Your policy | On an enforcing policy, providers and models outside your lists are skipped |
| 3 | Health | A provider with an unhealthy route is skipped |
| 4 | Credentials | A provider you cannot reach, with your key or Cloptima credits, is skipped |
| 5 | Known price | Where credits pay, a provider with no known price is skipped |
| 6 | Funding | Your own keys are preferred over Cloptima credits |
| 7 | Cost | The lowest estimated cost for this request wins |
05
A worked example
Take a request for claude-opus-5-5 with about 1,000 input tokens and 500 output tokens. You have your own keys for Anthropic and Bedrock, and no credential for Vertex AI. The prices below are an illustration.
| Provider | Usable? | Estimated cost | Result |
|---|---|---|---|
| Anthropic | Yes, your key | $0.0300 | Eligible |
| Bedrock | Yes, your key | $0.0285 | Chosen: lowest cost you can use |
| Vertex AI | No credential | $0.0270 | Skipped, because you cannot reach it |
Add a Vertex AI credential and the same request goes to Vertex AI, because it is now usable and cheapest. Nothing in your code changes.
06
Connect the providers you want to choose between
Cloptima can only choose a provider you are able to use. Add credentials for each provider, or use Cloptima credits for the providers they cover.
- 1
Open Credentials & Keys
Go to AI → Credentials & Keys.
- 2
Add a credential for each provider
In Provider Credentials, choose + Add Credential and enter the key.
- 3
Bind credentials where you need them
On the policy, use Default upstream credential or a Per-provider credential override. A virtual key can carry its own per-provider override.
07
Narrow the choice with policy lists
Your policy is in charge. If the policy allows only some providers or models, Cloptima chooses only from those.
| Policy setting | Effect on the choice |
|---|---|
| Allowed providers | Only these providers can be chosen |
| Allowed models | Only these models can be chosen |
| Denied models | These models are never chosen. A deny wins |
Keep Claude on Bedrock
Your company runs Claude through Bedrock for data-residency reasons. Set Allowed providers to bedrock on the production policy. A request for claude-opus-5-5 now goes to Bedrock, whatever the other providers cost.
08
Use it from your SDK
Any OpenAI-compatible client works. Point it at the gateway and pass the plain model name.
from openai import OpenAI
client = OpenAI(base_url="https://api.cloptima.ai/v1/ai", api_key="clop_vk_...")
reply = client.chat.completions.create(
model="claude-opus-5-5", # no provider prefix: Cloptima chooses
messages=[{"role": "user", "content": "Summarize this ticket"}],
)
print(reply.choices[0].message.content)To pin one request to one provider, send anthropic/claude-opus-5-5 instead.
09
See the choice before you send
The Request Simulator shows which provider, model, and credential a request would use.
- 1
Open the Request Simulator
It is in AI → Policies.
- 2
Enter the model
Use the plain model name, such as claude-opus-5-5.
- 3
Select the virtual key
Credentials and policy bindings follow the key.
- 4
Read the result
You see the provider and model chosen and the credential source, and any reason the request would be blocked.
- 2Model
- claude-opus-5-5
- 3Virtual Key (optional)
- support-chatbot-prod
4Simulation result
| Request | anthropic/claude-opus-5-5 · Would be allowed |
| Matched policy | support-app-production · enforce |
| Model check | Allowed |
| Credential | anthropic-prod · Virtual key — global fallback |
10
See what was chosen
The Explorer shows where your requests actually went.
- Group by Provider to see how spend splits across providers
- Group by Model to see which models carry the bill
- Group by Credential Mode to see your own keys against Cloptima credits
A change in the split usually means prices or health changed, or you added a credential.
11
Own keys first, credits as the backstop
When you can reach a model through your own key and through Cloptima credits, your own key wins. Credits cover providers you have not connected.
| You have | The request uses |
|---|---|
| A key for Anthropic and credits | Your Anthropic key |
| Keys for Anthropic and Bedrock | The cheaper of the two for this request |
| Credits only | The cheapest provider the credits cover |
12
When a model cannot be served
If no provider is left, the request is refused before it reaches any provider, with a message that says why.
| Reason | Meaning | Fix |
|---|---|---|
| model_retired | Every provider that served the model has retired it | Choose a current model |
| model_no_eligible_provider | No provider that serves the model is usable | Connect a credential for one, or allow a provider that serves it |
| provider_credential_revoked | The credential bound to the request has been revoked | Bind an active credential |
| provider_credential_provider_mismatch | The bound credential belongs to a different provider | Bind a credential for a provider that serves the model |
These return HTTP 403 with the reason in the body.
13
Keep it as code
Provider lists live in Terraform with the rest of the policy.
resource "cloptima_llm_gateway_policy" "production" {
name = "production"
mode = "enforce"
allowed_providers = ["bedrock", "vertex_ai"]
denied_models = ["openai/gpt-4o"]
}14
If something goes wrong
Most surprises come from credentials or from which policy applies.
| What you see | Likely cause | Fix |
|---|---|---|
| Requests always go to the same provider | It is the only one you can use, or it is cheapest | Add a credential for another provider, or check the price |
| A provider is never chosen | The policy excludes it, or it has no credential | Check Allowed providers and the credential |
| 403 model_no_eligible_provider | No usable provider for the model | Connect a credential, or allow a provider |
| The choice changed overnight | Prices or health changed | Group by Provider in the Explorer and compare |
| Lists do not seem to apply | The policy is in Monitor only mode | Switch Mode to Enforce |