MastraModelGateway

Abstract base class for implementing custom model gateways. Gateways handle provider-specific logic for accessing language models, including provider configuration, authentication, URL construction, and model instantiation.

Use MastraModelGatewayInterface when you want to provide a plain object gateway instead of extending the base class.

Class overview

import { MastraModelGateway, type ProviderConfig } from '@mastra/core/llm'
import { createOpenAICompatible } from '@ai-sdk/openai-compatible-v5'
import type { LanguageModelV2 } from '@ai-sdk/provider-v5'

class MyCustomGateway extends MastraModelGateway {
  readonly id = 'custom'
  readonly name = 'My Custom Gateway'

  async fetchProviders(): Promise<Record<string, ProviderConfig>> {
    return {
      'my-provider': {
        name: 'My Provider',
        models: ['openai/gpt-5.6-sol', 'anthropic/claude-sonnet-4-6'],
        apiKeyEnvVar: 'MY_API_KEY',
        gateway: this.id,
      },
    }
  }

  buildUrl(modelId: string, envVars?: Record<string, string>): string {
    return 'https://api.my-provider.com/v1'
  }

  async getApiKey(modelId: string): Promise<string> {
    const apiKey = process.env.MY_API_KEY
    if (!apiKey) throw new Error('MY_API_KEY not set')
    return apiKey
  }

  async resolveLanguageModel({
    modelId,
    providerId,
    apiKey,
  }: {
    modelId: string
    providerId: string
    apiKey: string
  }): Promise<LanguageModelV2> {
    const baseURL = this.buildUrl(`${providerId}/${modelId}`)
    return createOpenAICompatible({
      name: providerId,
      apiKey,
      baseURL,
    }).chatModel(modelId)
  }
}

Required properties

id:

string

Unique identifier for the gateway. This ID is used as the prefix for all providers from this gateway (e.g., "netlify/anthropic"). Exception: models.dev is a provider registry and doesn't use a prefix.

name:

string

Human-readable name for the gateway.

Required methods

fetchProviders()

Fetches provider configurations from the gateway.

Returns: Promise<Record<string, ProviderConfig>>

ProviderConfig Structure:

name:

string

Display name of the provider

models:

string[]

Array of available model IDs

apiKeyEnvVar:

string | string[]

Environment variable(s) for API key

gateway:

string

Gateway identifier

url?:

string

Optional base API URL

apiKeyHeader?:

string

Optional custom auth header name

docUrl?:

string

Optional documentation URL

pricing?:

Record<string, ModelPricing>

Prices per model ID in USD per 1 million tokens, with the same keys as a models.dev cost (input, output, cache_read, cache_write, reasoning, input_audio, output_audio). Optional tiers hold long-context rates. @mastra/observability uses them for cost metrics when models.dev has no price for the model.

buildUrl()

Builds the API URL for a specific model/provider combination.

If your provider URL contains placeholders such as ${ACCOUNT_ID}, resolve them inside buildUrl() from envVars or process.env before returning the final URL.

Parameters:

modelId:

string

Full model ID (e.g., "custom/my-provider/model-1")

envVars:

Record<string, string>

Environment variables available to the gateway

Returns: string | undefined | Promise<string | undefined>

getApiKey()

Retrieves the API key for authentication.

Parameters:

modelId:

string

Full model ID

Returns: Promise<string>

resolveAuth()

Resolves credentials before Mastra creates the language model. Implement this optional hook when a gateway owns authentication. If omitted, Mastra falls back to getApiKey().

Parameters:

request:

GatewayAuthRequest

Incoming request context containing gatewayId, providerId, modelId, and routerId for the gateway to inspect and validate.

Returns: GatewayAuthResult | undefined | Promise<GatewayAuthResult | undefined>

A GatewayAuthResult may include apiKey, bearerToken, headers, and an optional source field to trace where auth came from.

resolveLanguageModel()

Creates a language model instance.

Parameters:

modelId:

string

The model ID

providerId:

string

The provider ID

apiKey:

string

The API key for authentication

headers?:

Record<string, string>

Additional headers to send with model requests

transport?:

'auto' | 'websocket' | 'fetch'

Transport for OpenAI Responses API requests

responsesWebSocket?:

ResponsesWebSocketOptions

WebSocket options used when transport is websocket

Returns: GatewayLanguageModel | Promise<GatewayLanguageModel>, where GatewayLanguageModel is LanguageModelV2 | LanguageModelV3 | LanguageModelV4 (AI SDK v5, v6, and v7 models).

Instance methods

getId()

Deprecated: Use the id property instead.

Returns the gateway's unique identifier.

Returns: string - The gateway's id property

Model ID format

For true gateways, the gateway ID is used as a prefix and models are accessed using this format:

[gateway-id]/[provider]/[model]

Examples:

• Gateway with id = 'custom': 'custom/my-provider/model-1'

Built-in implementations

• NetlifyGateway - Netlify AI Gateway integration
• ModelsDevGateway - Registry of OpenAI-compatible providers

Related

• Custom Gateways Guide: Complete guide to creating custom gateways
• Mastra.addGateway(): Add a gateway to Mastra
• Mastra.getGateway(): Get gateway by registration key
• Mastra.getGatewayById(): Get gateway by ID
• Mastra.listGateways(): List all gateways