Skip to main content

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.

Class overview
Direct link to 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: ['model-1', 'model-2'],
        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
Direct link to 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
Direct link to Required methods

fetchProviders()
Direct link to 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

buildUrl()
Direct link to buildurl

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

Parameters:

modelId:

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

envVars?:

Record<string, string>
Optional environment variables

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

getApiKey()
Direct link to getapikey

Retrieves the API key for authentication.

Parameters:

modelId:

string
Full model ID

Returns: Promise<string>

resolveLanguageModel()
Direct link to resolvelanguagemodel

Creates a language model instance.

Parameters:

modelId:

string
The model ID

providerId:

string
The provider ID

apiKey:

string
The API key for authentication

Returns: Promise<LanguageModelV2> | LanguageModelV2

Instance methods
Direct link to Instance methods

getId()
Direct link to getid

Returns the gateway's unique identifier.

Returns: string - The gateway's id property

Model ID format
Direct link to 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
Direct link to Built-in implementations

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