Skip to navigation

Choose a model

Every LLM request names a model in its model field. How you name it depends on the route: a route with a model router serves many providers and takes a <provider>/<model> name or an alias, and other routes take the provider’s own model name. This topic shows you how to name a model, list the models a route serves, and fix the errors you get for a model the gateway can’t serve. To send your first request, see Authenticate and send a request.

Prerequisites

Before you begin, make sure you have the following:

  • The base URL of an LLM route and a gateway key for it. For details, see Authenticate and send a request.
  • To know whether the route uses a model router. Ask your admin if you’re not sure. A route with a model router answers GET /v1/models with a list of <provider>/<model> names.

Name a model

RouteWhat to send in modelExample
With a model router<provider>/<model>, where <provider> is a provider name your admin set upopenai/gpt-5.5, anthropic/claude-sonnet-5-5
With a model routerAn alias, a name without / that your admin mapped to one or more providersclaude-sonnet-5-5
Without a model routerThe provider’s own model namegpt-4o-mini

On a model router route, the gateway splits the name at the first /, so openrouter/meta/llama-4 means the provider openrouter and the model meta/llama-4. Names are matched exactly: OpenAI/gpt-5.5, or a name with a leading space, doesn’t match openai/gpt-5.5.

The gateway sends the provider the model name it expects, gpt-5.5 for openai/gpt-5.5, and leaves the rest of your request as you sent it. It doesn’t translate between APIs, so a model works only on the endpoints its provider serves. For example, an Anthropic model answers on /v1/messages, and on /v1/chat/completions only if that provider also offers an OpenAI-compatible endpoint.

On a route without a model router, the gateway sends your model name to the provider unchanged, unless the route uses the Adaptive Model Router, which can replace it. If your admin restricted the route’s models, a model that isn’t allowed gets 400 with Model "<model>" is not allowed for service "<service>". The service is the connection’s name.

List the models

On a model router route, the gateway answers GET /v1/models itself. The list has every <provider>/<model> and alias that you can use with your gateway key, sorted by name:

curl "BASE_URL/v1/models" \
-H "fg-api-key: GATEWAY_KEY"
{
"object": "list",
"data": [
{ "id": "anthropic/claude-sonnet-5-5", "object": "model", "created": 0, "owned_by": "anthropic" },
{ "id": "claude-sonnet-5-5", "object": "model", "created": 0, "owned_by": "fabric" },
{ "id": "openai/gpt-5.5", "object": "model", "created": 0, "owned_by": "openai" }
]
}

An alias has owned_by set to fabric. If you can use none of the route’s models, the list is empty.

When the request has an anthropic-version header, as every Anthropic SDK request does, the list comes back in the Anthropic shape instead, with type, id, display_name, created_at, has_more, first_id, and last_id.

To look up one model, send GET /v1/models/<name>. You can send the / in the name as is or encoded as %2F, so /v1/models/openai/gpt-5.5 and /v1/models/openai%2Fgpt-5.5 both work. A name that isn’t in the list gets 404.

Check which model answered

On a model router route, every response from a provider has an x-fabric-model header with the <provider>/<model> that answered. When the gateway falls back to another provider or alias target, this header tells you which one served the request. On other routes, check the model field of the response.

Fix model errors

On a model router route, the gateway refuses the following requests before it calls any provider. The error comes back in the envelope of the endpoint you called. For the envelopes, see Use the OpenAI-compatible API and Use the Anthropic Messages API. A 401 from Key Auth isn’t in the envelope. It’s the plain text Unauthorized.

StatusMessageCauseFix
400`model` is requiredThe body has no model, or it’s empty or not a string.Add a model.
400request body must be a JSON objectThe body isn’t a JSON object.Send a JSON object.
413request body too largeThe body is larger than 10 MiB.Send a smaller request.
404model `<name>` not foundThe provider prefix doesn’t exist, the provider doesn’t serve that model, or the name has no / and isn’t an alias. The OpenAI envelope has code set to model_not_found.List the models with GET /v1/models, and use a name from the list.
400model `<name>` is not available on `<method> <path>` The model exists, but none of its providers serves the endpoint you called.Call an endpoint in the model’s own API format, for example /v1/messages for an Anthropic model.
403access denied for model `<name>` Your gateway key has no grant for any connection that serves the model.Ask your admin for access.

The 404 is the same whether the provider or the model is unknown, and no message lists the route’s models or connections.

Next steps