Start here · Step 1: What Gatewayz is
What is Gatewayz? One API key for many AI models
What Gatewayz is: one API key and one neutral endpoint for AI models from several providers. What it does, what it does not do, and the trade-offs.
Last updated · 9 min read · Gatewayz
Gatewayz is one API key and one neutral endpoint for AI models from several providers. You send a request that names a model, Gatewayz forwards it to the provider that serves that exact model, and you pay per token from one prepaid balance. It has no model of its own and does not choose a model for you.
What is Gatewayz, in plain terms?
Gatewayz is an inference layer: a service that sits between your software and the companies that run AI models, and owns the contract between the two. Your application talks to one address, and Gatewayz talks to the providers.
Without a layer like this, a team that uses models from three providers typically holds three accounts, three sets of credentials, three billing relationships and three slightly different request formats. Each provider has its own way of naming models, reporting usage and signalling errors. None of that is hard on its own. Together it becomes glue code that someone has to write, test and keep current.
Gatewayz replaces that glue with one integration. The request still reaches the provider that runs the model, and the provider still does the computation. What changes is how many relationships your code has to manage. If the word inference is new to you, What is AI inference? explains what actually happens when a model answers a request.
What does Gatewayz actually do?
It provides one integration point with a small number of predictable behaviors. Each one is described below.
One key and one balance
You create an API key at beta.gatewayz.ai and send it in an Authorization: Bearer header. The same key works for every model in the catalog. Usage is drawn from one prepaid balance, billed per token at the provider's list price plus a routing fee. See /pricing for how billing works.
Two request formats
Gatewayz accepts two widely used request formats:
- The OpenAI-compatible Chat Completions format at
https://api.gatewayz.ai/v1/chat/completions. Any SDK or tool that lets you set a base URL can point athttps://api.gatewayz.ai/v1. - The native Anthropic Messages API format at
https://api.gatewayz.ai/v1/messages. The Anthropic SDK and Claude Code use the hosthttps://api.gatewayz.aias their base URL.
The formats themselves are defined by the providers. The OpenAI Chat Completions reference and the Anthropic Messages reference describe the request and response shapes in full.
A minimal request in the OpenAI-compatible format looks like this:
curl https://api.gatewayz.ai/v1/chat/completions \
-H "Authorization: Bearer $GATEWAYZ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "anthropic/claude-sonnet-4-6",
"messages": [{"role": "user", "content": "Summarize this paragraph in one sentence."}]
}'Changing anthropic/claude-sonnet-4-6 to openai/gpt-5-mini sends the same request to a different provider. Nothing else in the call changes.
Provider-namespaced model ids
Model ids carry the provider in front, for example openai/gpt-5, anthropic/claude-haiku-4-5-20251001 or moonshot/kimi-k2.6. The prefix removes ambiguity when two providers use similar names. The full list is public at https://api.gatewayz.ai/v1/models and needs no key.
An alias such as claude-sonnet-4-5 resolves to exactly one dated snapshot. If a name cannot be resolved to one model, the request is refused with 400 model_not_found. Resolution, not substitution explains why that refusal is deliberate.
Machine-readable errors
Every error returns the same body shape, shown here with the message and type elided:
{"error": {"message": "...", "type": "...", "code": "request_cap_exhausted"}}The status code tells a program whether retrying can help, and the code field tells it what to change:
| Status | Code | Meaning | Retry? |
|---|---|---|---|
| 400 | model_not_found | Unknown model id | No, fix the id |
| 401 | invalid_api_key | Key missing or invalid | No, fix the key |
| 402 | request_cap_exhausted | This key's request cap is spent | No, raise the cap |
| 402 | insufficient_credits | Account balance is empty | No, add credits |
| 429 | Rate limited | Yes, after a pause | |
| 5xx | Upstream or server failure | Yes, with backoff |
A stream that fails partway ends with an explicit error event, so a client can tell a truncated answer from a complete one. The general principles behind status classes are defined in RFC 9110, and Who reads the error? covers why this matters for agents.
Per-key request caps
Each key can carry a request cap, set as max_requests when you create or update the key. When the cap is spent, requests on that key return 402 request_cap_exhausted until the cap is raised. Keys can also be deactivated or deleted. Giving each agent or environment its own capped key limits how much any one of them can spend by mistake.
What does Gatewayz not do?
It does not replace the provider, pick your model, keep your prompts or swap models behind your back. Being clear about these limits is as important as listing features.
- It has no model of its own. Every response is produced by a model from a provider in the catalog, never by a Gatewayz model.
- It does not choose your model. The model field in your request decides which model runs. There is no hidden layer that rewrites it based on price or load.
- It does not store prompt or completion content on ordinary API calls. What it records is billing metadata: token counts, cost, model, status and timing. The provider that runs the model still receives your prompt, as it would if you called it directly. The /security page has the details.
- It does not substitute a different model. An unknown id returns
400. The capability to fail over to another route serving the same model when one degrades is built, but it never changes which model answers.
Should you call providers directly or through Gatewayz?
It depends on how many providers you use and how much operational work you want to own. Here is an honest comparison.
| Consideration | Calling providers directly | Through Gatewayz |
|---|---|---|
| Accounts and keys | One per provider | One key for the catalog |
| Billing | Separate invoices and balances | One prepaid balance |
| Price per token | Provider list price | List price plus a routing fee |
| Request formats | Each provider's own API | OpenAI-compatible or Anthropic Messages |
| Newest provider-specific features | Available on day one | Available once supported by the layer |
| Network path | Your app to provider | Your app to Gatewayz to provider |
| Dependencies | The provider only | The provider and Gatewayz |
| Error handling | Varies by provider | One documented contract |
| Spending limits per key | Varies by provider | Per-key request caps |
| Data seen by third parties | The provider | The provider, plus billing metadata at Gatewayz |
The trade-offs cut both ways. Going direct avoids the routing fee and removes one hop and one dependency. If you only ever use one provider and already have its billing and error handling under control, that may be the right call.
Going through Gatewayz makes more sense when you use or test models from more than one provider, when you want a single balance and per-key limits across all of them, or when you run unattended software that benefits from one consistent error contract. The extra hop is real, and so is the dependency: if Gatewayz is unavailable, your calls through it are too. Weigh that against the integration work it removes.
Who is Gatewayz for?
It is for developers and teams who call models from more than one provider, or expect to. Typical cases include:
- A product team comparing models from different providers without opening several accounts.
- A developer running coding agents, such as Claude Code, who wants one balance and a spending cap per tool. See Run Claude Code through Gatewayz.
- A company running agents overnight, where predictable errors and hard per-key limits matter more than a person watching a dashboard.
If you want to try it, /start walks through getting a key and making a first call.
Common misconceptions about Gatewayz
A few assumptions come up often, and they are worth correcting directly.
- It is not a model. Asking what model Gatewayz is misreads the product. It is the layer in front of models.
- It is not a smart router. It does not decide that a cheaper or faster model is good enough for your request. You name the model.
- It is not a way to avoid a provider seeing your data. The provider still processes the prompt. Gatewayz reduces what the layer itself keeps, not what the provider receives.
- It does not make models free or discounted. Tokens are billed at list price plus a routing fee.
Frequently asked questions
Is Gatewayz an AI model?
No. Gatewayz has no model of its own. It is an inference layer that forwards your request to the provider that serves the model you named, such as OpenAI, Anthropic, xAI, Moonshot or Meta, and returns that model's response to you along with consistent billing and errors.
Do I need to change my code to use Gatewayz?
Usually very little. If your code uses the OpenAI SDK or any OpenAI-compatible client, you set the base URL to https://api.gatewayz.ai/v1, use your Gatewayz key and change model names to provider-namespaced ids. If you use the Anthropic SDK or Claude Code, you set the base URL to https://api.gatewayz.ai instead.
How much does Gatewayz cost?
You pay per token at the provider's list price plus a routing fee, drawn from one prepaid balance. Current details are on the pricing page.
Does Gatewayz store my prompts?
Not on ordinary API calls. Gatewayz records billing metadata such as token counts, cost, model, status and timing, not prompt or completion content. The model provider still receives your prompt in order to run it, so the provider's own data policies continue to apply.
What happens if I request a model that does not exist?
You get a 400 response with the code model_not_found. Gatewayz never runs a nearby or similar model in its place, because a silent swap would change both the output you tested and the price you budgeted.
Can Gatewayz pick the best model for my task?
No. Choosing a model is your decision, made in the model field of each request. Gatewayz makes the choice easier to act on by giving you one key for many providers, but it does not rank or select models for you.
Related
- What is AI inference?. What happens when a model answers a request.
- What is an AI gateway?. Why routing and a neutral endpoint matter.
- What is an inference layer?. How a gateway differs from a layer that owns the contract.
- Resolution, not substitution. Why an unknown model id is refused.
- Your first Gatewayz API request. Make a working call in a few minutes.