AI Agent - Aug 5, 2026

Google API Gateway Model Routing OpenAPI Configuration

Quick answer

Google’s Public Preview example uses an OpenAPI 3.0.4 document with three layers:

  1. x-google-api-management.backends defines exact Vertex AI backend addresses, deadlines, and path translation;
  2. x-google-api-management.ai.models.routing.routers defines a default model and virtual model rules;
  3. an operation sets x-google-model-router to bind that endpoint to one router.

Source-parity skeleton

openapi: 3.0.4
info:
  title: model-router
  version: 1.0.0

x-google-api-management:
  backends:
    default-model:
      address: https://aiplatform.googleapis.com/EXACT_VERTEX_PATH
      deadline: 60.0
      pathTranslation: CONSTANT_ADDRESS
    alternate-model:
      address: https://aiplatform.googleapis.com/EXACT_VERTEX_PATH
      deadline: 60.0
      pathTranslation: CONSTANT_ADDRESS
  ai:
    models:
      routing:
        routers:
          primary-router:
            defaultModel:
              backend: default-model
              targetModel: publisher/default-model-id
            rules:
              - model: "alternate"
                backend: alternate-model
                targetModel: publisher/alternate-model-id

paths:
  /v1/chat:
    post:
      operationId: routeChat
      x-google-model-router: primary-router
      responses:
        "200":
          description: OK

Replace every placeholder with a current, supported Vertex AI MaaS path. The launch example uses different native backend paths for Gemini generateContent, Claude rawPredict, and the OpenAI-compatible OSS-GPT endpoint; do not assume one suffix applies to every publisher.

Configuration review

  • Every backend referenced by a router uses the same hostname.
  • Backend names, router names, backend references, and operation bindings match exactly.
  • targetModel values match the backend model actually invoked.
  • The default is an intentional, evaluated model.
  • Deadlines, authentication, locations, and path translation are reviewed.
  • The client always includes a valid model field.
  • The OpenAPI document and deployed API config have immutable revisions.

The generic OpenAPI 3.x extension documentation also notes that API Gateway does not enforce every schema rule. Validate request bodies and allowed model values at the application or policy boundary instead of assuming the OpenAPI schema is a runtime validator.

Use the model-target guide for publisher path differences and the troubleshooting guide for the host and protocol gates.

Frequently asked questions

Where are model routers defined in OpenAPI 3.x?

Google’s launch example defines backends and ai.models.routing.routers under the root x-google-api-management block.

How is an API operation connected to a model router?

Set x-google-model-router on the operation to the name of a router defined in x-google-api-management.

What happens when no routing rule matches?

The router uses its configured defaultModel backend and target model. Test the default deliberately rather than treating it as an accidental fallback.

Official sources

Source check: August 5, 2026. Verify the live syntax, model paths, project and location, authentication, deadlines, and Preview limitations before deploying.