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

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