Models and routing
Use the public model catalog to choose a canonical creator/model ID, check endpoint and modality support, and understand how OpenGateway routes requests across providers.
Choose a model ID from the public catalog. Its creator prefix identifies the model; one model can have several providers that serve it.
Use canonical model IDs#
Every model ID has the form creator/model. The creator is the model owner shown as owned_by in GET /v1/models. Use the complete id from the catalog, for example openai/gpt-5-mini.
The creator prefix is not a provider preference. Keep it when sending a request, even when the catalog lists multiple providers for that model.
Read the model catalog#
GET /v1/models is public. Use it to find current IDs and check a model’s endpoint, modality, provider, and context information:
curl "https://apis.opengateway.ai/v1/models"
| Field | Meaning |
|---|---|
id | The canonical creator/model ID to send in the request’s model field. |
owned_by | The model creator; it matches the first segment of id. |
status | active means in service; deprecated models remain served during their deprecation period; retired models have been shut down and are not routable. |
endpoints | The API endpoints the model supports, such as chat_completions, responses, messages, embeddings, images_generations, images_edits, or decisions. Call an endpoint only when it is listed. |
providers | Provider entries for the model, each with an id and region. |
modalities | Supported input and output types. Values can include text, image, audio, video, embedding, or decision. |
context_window | The model’s declared context window, when available. |
A model’s endpoints and modalities can summarize support across its provider entries. That does not mean every listed provider supports every endpoint or modality; OpenGateway filters route candidates by the requested endpoint and whether the runtime can execute it. The model catalog does not include prices; see the model catalog page for current availability and pricing.
How provider routing works#
For a request, OpenGateway resolves the canonical model ID to its catalog entries, then keeps only entries visible to the key and able to execute the requested endpoint. It orders provider and region candidates using the model’s configured provider order and each provider’s active-region order. Routing policy may adjust which eligible candidate is attempted next; the response returns on the first successful attempt.
There is no request-level provider selection object. The providers field is discovery information, not a per-request instruction. To use another model after a failure, configure model IDs in extra.fallbacks; see fallbacks.
To inspect attempted routes, request extra.debug: ["routing"]. The response’s debug.routing entries show the attempted provider, region, and status; see debug mode.
Access and retired models#
An API key restricted by a model allowlist sees only its allowed models in GET /v1/models. Requests for an unknown or retired model ID fail with 400 model_not_found. A model that exists but does not support the requested endpoint can return 400 unsupported_endpoint; a model blocked by key or team access can return 401 model_access_denied. See API errors for the error codes.