@mastra/core/dist/docs/references/reference-core-mastra-model-gateway.md

Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.

# 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

```typescript
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

**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

### `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>`): Optional environment variables

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

### `getApiKey()`

Retrieves the API key for authentication.

**Parameters:**

**modelId** (`string`): Full model ID

**Returns:** `Promise<string>`

### `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

### `getId()`

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:

```text
[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](https://mastra.ai/models/gateways/custom-gateways): Complete guide to creating custom gateways
- [Mastra.addGateway()](https://mastra.ai/reference/core/addGateway): Add a gateway to Mastra
- [Mastra.getGateway()](https://mastra.ai/reference/core/getGateway): Get gateway by registration key
- [Mastra.getGatewayById()](https://mastra.ai/reference/core/getGatewayById): Get gateway by ID
- [Mastra.listGateways()](https://mastra.ai/reference/core/listGateways): List all gateways