> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modellix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Use Modellix LLM with Mastra

> Point Mastra agents at Modellix with a custom OpenAI-compatible model url, apiKey, and gateway-style provider/name IDs.

Use [Mastra](https://mastra.ai/models) against the Modellix LLM gateway. Mastra is not a built-in Modellix provider — configure a [custom OpenAI-compatible endpoint](https://mastra.ai/models#use-local-models-with-mastra) with `url` set to `https://llm.modellix.ai/v1`, or pass a [Vercel AI SDK](/llm/sdk/vercel-ai-sdk) provider instance as `model`.

<Note>
  This page covers **LLM text** only (`https://llm.modellix.ai`).

  Modellix expects full `provider/name` Model IDs in the request body (for example `openai/gpt-5.5`). Treat Modellix as a **gateway**: use a three-part `id` (`modellix/<provider>/<name>`) so Mastra forwards `openai/gpt-5.5` upstream. See [Models & Pricing](/llm/overview#models-and-pricing).
</Note>

## Set Up Mastra

<Steps>
  <Step title="Install Mastra">
    Follow the [Mastra getting started](https://mastra.ai/docs) flow for your app, or add the core package to an existing TypeScript project:

    ```bash theme={null}
    npm install @mastra/core
    ```

    For the AI SDK provider path below, also install:

    ```bash theme={null}
    npm install ai @ai-sdk/openai-compatible
    ```
  </Step>

  <Step title="Set Credentials">
    Create a Modellix API key in the [console](https://modellix.ai/console/api-key):

    ```bash theme={null}
    export MODELLIX_API_KEY="mdlx-xxxxxxxx"
    ```

    | Setting                       | Value                                                                 |
    | ----------------------------- | --------------------------------------------------------------------- |
    | `apiKey` / `MODELLIX_API_KEY` | Modellix API Key                                                      |
    | `url` / `baseURL`             | `https://llm.modellix.ai/v1` (OpenAI-compatible base; include `/v1`)  |
    | Model ID                      | Gateway form `modellix/<provider>/<name>`, or AI SDK `openai/gpt-5.5` |

    <Warning>
      Do not set `url` to a full `/chat/completions` path — use the `/v1` base only. Do not point Mastra at the media host (`https://api.modellix.ai`). A plain string like `model: "openai/gpt-5.5"` routes to OpenAI's built-in provider, not Modellix.
    </Warning>
  </Step>

  <Step title="Configure a Custom OpenAI-Compatible Model (Recommended)">
    Pass an object to `model` with `id`, `url`, and `apiKey`:

    ```typescript theme={null}
    import { Agent } from "@mastra/core/agent";

    const agent = new Agent({
      id: "modellix-agent",
      name: "Modellix Agent",
      instructions: "You are a concise coding assistant.",
      model: {
        // Gateway form: Mastra sends openai/gpt-5.5 to Modellix
        id: "modellix/openai/gpt-5.5",
        url: "https://llm.modellix.ai/v1",
        apiKey: process.env.MODELLIX_API_KEY,
      },
    });

    const result = await agent.generate("Introduce yourself in one sentence.");
    console.log(result.text);
    ```

    Other catalog examples:

    | Mastra `id`                          | Upstream Model ID           |
    | ------------------------------------ | --------------------------- |
    | `modellix/openai/gpt-5.5`            | `openai/gpt-5.5`            |
    | `modellix/anthropic/claude-sonnet-5` | `anthropic/claude-sonnet-5` |
    | `modellix/google/gemini-3.6-flash`   | `google/gemini-3.6-flash`   |

    Traffic still uses Chat Completions on `https://llm.modellix.ai/v1`.
  </Step>

  <Step title="Optional: Use createOpenAICompatible">
    Mastra accepts AI SDK language models anywhere a `"provider/model"` string works:

    ```typescript theme={null}
    import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
    import { Agent } from "@mastra/core/agent";

    const modellix = createOpenAICompatible({
      name: "modellix",
      apiKey: process.env.MODELLIX_API_KEY,
      baseURL: "https://llm.modellix.ai/v1",
    });

    const agent = new Agent({
      id: "modellix-agent",
      name: "Modellix Agent",
      instructions: "You are a concise coding assistant.",
      model: modellix("openai/gpt-5.5"),
    });
    ```

    Same pattern as the [Vercel AI SDK](/llm/sdk/vercel-ai-sdk) guide. You can also put this model in Mastra [fallback chains](https://mastra.ai/models#model-fallbacks).
  </Step>

  <Step title="Optional: Fallbacks Across Catalog IDs">
    Keep several Modellix models on the same gateway URL:

    ```typescript theme={null}
    const agent = new Agent({
      id: "resilient-agent",
      name: "Resilient Agent",
      instructions: "You are a helpful assistant.",
      model: [
        {
          model: {
            id: "modellix/openai/gpt-5.5",
            url: "https://llm.modellix.ai/v1",
            apiKey: process.env.MODELLIX_API_KEY,
          },
          maxRetries: 2,
        },
        {
          model: {
            id: "modellix/google/gemini-3.6-flash",
            url: "https://llm.modellix.ai/v1",
            apiKey: process.env.MODELLIX_API_KEY,
          },
          maxRetries: 2,
        },
      ],
    });
    ```
  </Step>
</Steps>

## Troubleshooting

| Symptom               | Check                                                                                                  |
| --------------------- | ------------------------------------------------------------------------------------------------------ |
| Still hitting OpenAI  | `model` is a custom `{ id, url, apiKey }` object or AI SDK provider — not a bare `"openai/..."` string |
| 401 Unauthorized      | `apiKey` / `MODELLIX_API_KEY` is a valid Modellix key                                                  |
| Model not found / 404 | Upstream ID is full `provider/name`; gateway `id` is `modellix/<provider>/<name>`                      |
| Wrong path            | `url` / `baseURL` is `https://llm.modellix.ai/v1` (include `/v1`, no `/chat/completions`)              |
| Bare model name sent  | Use gateway-style `id` (three segments) so Modellix receives `openai/gpt-5.5`                          |

## Related

* [Mastra model providers](https://mastra.ai/models) — custom OpenAI-compatible `url`, gateways, fallbacks
* [Vercel AI SDK](/llm/sdk/vercel-ai-sdk) — `createOpenAICompatible` details
* [OpenAI SDK](/llm/sdk/openai-sdk) — same `/v1` gateway without Mastra
* [Models & Pricing](/llm/overview#models-and-pricing) — Model IDs and rates
* [LLM API guide](/llm/api/api) — protocols and curl examples