The bundled minimax plugin registers two chat providers plus six capabilities: image generation, music generation, video generation, image understanding, speech (T2A v2), and web search.

Provider ID Auth Capabilities
minimax API key Text, image generation, music generation, video generation, image understanding, speech, web search
minimax-portal OAuth Text, image generation, music generation, video generation, image understanding, speech

Referral link for MiniMax Coding Plan (10% off): MiniMax Coding Plan

Built-in catalog

Model Type Description
MiniMax-M3 Chat (reasoning) Default hosted reasoning model
MiniMax-M3.1-Flash-Preview Chat (reasoning) Token Plan preview with adjustable effort
MiniMax-M2.7 Chat (reasoning) Previous hosted reasoning model
MiniMax-M2.7-highspeed Chat (reasoning) Faster M2.7 reasoning tier
MiniMax-VL-01 Vision Image understanding model
image-01 Image generation Text-to-image and image-to-image editing
music-2.6 Music generation Default music model
MiniMax-Hailuo-2.3 Video generation Text-to-video and image-to-video flows

Model refs follow the auth path: minimax/<model> for API-key setups, minimax-portal/<model> for OAuth setups.

MiniMax-M3.1-Flash-Preview supports text and image input with a 1,000,000-token context window. MiniMax currently offers it only through Token Plan and MiniMax Code; availability depends on your account. Its bundled cost fields are zero because MiniMax has not published per-token pricing for the preview, not because the service is free. MiniMax-M3 remains the default model.

MiniMax M3 and M3.1 Flash Preview are preferred Code Mode models on both API-key and OAuth routes. With no global Code Mode setting, the automatic tier can engage it; explicit agent or model settings still take precedence.

Getting started

OAuth (Coding Plan)

**Best for:** quick setup with MiniMax Coding Plan via OAuth, no API key required.

International

Run onboarding

        ```bash
        apus onboard --auth-choice minimax-global-oauth
        ```

        Resulting provider base URL: `api.minimax.io`.

Verify the model is available

        ```bash
        apus models list --provider minimax-portal
        ```

China

Run onboarding

        ```bash
        apus onboard --auth-choice minimax-cn-oauth
        ```

        Resulting provider base URL: `api.minimaxi.com`.

Verify the model is available

        ```bash
        apus models list --provider minimax-portal
        ```

OAuth setups use the `minimax-portal` provider id. Model refs follow the form `minimax-portal/MiniMax-M3`.

Apus refreshes expired OAuth access tokens at the regional MiniMax account endpoint that issued them. It refuses the refresh, and asks you to run `apus models auth login --provider minimax-portal` again, when the saved sign-in predates refresh support (it does not record its region) or when `models.providers.minimax-portal.baseUrl` now points to the other region.

API key

**Best for:** hosted MiniMax with Anthropic-compatible API.

International

Run onboarding

        ```bash
        apus onboard --auth-choice minimax-global-api
        ```

        This configures `api.minimax.io` as the base URL.

Verify the model is available

        ```bash
        apus models list --provider minimax
        ```

China

Run onboarding

        ```bash
        apus onboard --auth-choice minimax-cn-api
        ```

        This configures `api.minimaxi.com` as the base URL.

Verify the model is available

        ```bash
        apus models list --provider minimax
        ```

### Config example

```json5
{
  env: { vars: { MINIMAX_API_KEY: "sk-..." } },
  agents: { defaults: { model: { primary: "minimax/MiniMax-M3" } } },
  models: {
    mode: "merge",
    providers: {
      minimax: {
        baseUrl: "https://api.minimax.io/anthropic",
        apiKey: "${MINIMAX_API_KEY}",
        api: "anthropic-messages",
        models: [
          {
            id: "MiniMax-M3",
            name: "MiniMax M3",
            reasoning: true,
            input: ["text", "image"],
            compat: { codeMode: "preferred" },
            cost: { input: 0.6, output: 2.4, cacheRead: 0.12, cacheWrite: 0 },
            contextWindow: 1000000,
            maxTokens: 131072,
          },
          {
            id: "MiniMax-M2.7",
            name: "MiniMax M2.7",
            reasoning: true,
            input: ["text"],
            cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0.375 },
            contextWindow: 204800,
            maxTokens: 131072,
          },
          {
            id: "MiniMax-M2.7-highspeed",
            name: "MiniMax M2.7 Highspeed",
            reasoning: true,
            input: ["text"],
            cost: { input: 0.6, output: 2.4, cacheRead: 0.06, cacheWrite: 0.375 },
            contextWindow: 204800,
            maxTokens: 131072,
          },
        ],
      },
    },
  },
}
```

MiniMax-M2.x's Anthropic-compatible streaming endpoint emits `reasoning_content` in OpenAI-style delta chunks instead of native Anthropic thinking blocks, which leaks internal reasoning into visible output if thinking is left enabled implicitly. Apus disables M2.x thinking by default unless you explicitly set `thinking` yourself. MiniMax-M3 (and forward-compatible M3.x) is exempt: M3 emits proper Anthropic thinking blocks and requires thinking active to produce visible content, so Apus keeps M3 on the provider's adaptive thinking path. See the Thinking defaults section under Advanced configuration below.

API-key setups use the `minimax` provider id. Model refs follow the form `minimax/MiniMax-M3`.

Configure via apus configure

Launch the wizard

```bash
apus configure
```

Select Model/auth

Choose **Model/auth** from the menu.

Choose a MiniMax auth option

| Auth choice            | Description                        |
| ----------------------- | ----------------------------------- |
| `minimax-global-oauth` | International OAuth (Coding Plan)  |
| `minimax-cn-oauth`     | China OAuth (Coding Plan)          |
| `minimax-global-api`   | International API key              |
| `minimax-cn-api`       | China API key                      |

Pick your default model

Select your default model when prompted.

Capabilities

Image generation

The MiniMax plugin registers the image-01 model for the image_generate tool on both minimax and minimax-portal, reusing the same MINIMAX_API_KEY or OAuth auth as the text models.

{
  agents: {
    defaults: {
      mediaModels: { image: { primary: "minimax/image-01" } },
    },
  },
}

Image generation always uses MiniMax's dedicated image endpoint (/v1/image_generation) and ignores models.providers.minimax.baseUrl, since that field configures the chat/Anthropic-compatible base URL instead. Set MINIMAX_API_HOST=https://api.minimaxi.com to route image generation through the CN endpoint; the default global endpoint is https://api.minimax.io.

See Image Generation for shared tool parameters, provider selection, and failover behavior.

Text-to-speech

The bundled minimax plugin registers MiniMax T2A v2 as a speech provider for tts.

Setting Env var Default Description
tts.providers.minimax.baseUrl MINIMAX_API_HOST https://api.minimax.io MiniMax T2A API host.
tts.providers.minimax.model MINIMAX_TTS_MODEL speech-2.8-hd TTS model id.
tts.providers.minimax.voiceId MINIMAX_TTS_VOICE_ID English_expressive_narrator Voice id used for speech output.
tts.providers.minimax.speed 1.0 Playback speed, 0.5..2.0.
tts.providers.minimax.vol 1.0 Volume, (0, 10].
tts.providers.minimax.pitch 0 Integer pitch shift, -12..12.

Music generation

The bundled MiniMax plugin registers music generation through the shared music_generate tool for both minimax and minimax-portal.

{
  agents: {
    defaults: {
      mediaModels: { music: { primary: "minimax/music-2.6" } },
    },
  },
}

See Music Generation for shared tool parameters, provider selection, and failover behavior.

Video generation

The bundled MiniMax plugin registers video generation through the shared video_generate tool for both minimax and minimax-portal.

{
  agents: {
    defaults: {
      mediaModels: { video: { primary: "minimax/MiniMax-Hailuo-2.3" } },
    },
  },
}

See Video Generation for shared tool parameters, provider selection, and failover behavior.

Image understanding

The MiniMax plugin registers image understanding separately from the text catalog:

Provider ID Default image model PDF text extraction
minimax MiniMax-VL-01 MiniMax-M2.7
minimax-portal MiniMax-VL-01 MiniMax-M2.7

That is why automatic media routing can use MiniMax image understanding even when the bundled text-provider catalog also includes M3 image-capable chat refs. PDF understanding uses MiniMax-M2.7 for text extraction only; MiniMax does not register a PDF-to-image conversion path.

Web search

The MiniMax plugin also registers web_search through the MiniMax Token Plan search API (/v1/coding_plan/search).

Config lives under plugins.entries.minimax.config.webSearch.*.

See MiniMax Search for full web search configuration and usage.

Advanced configuration

Configuration options 
| Option | Description |
| --- | --- |
| `models.providers.minimax.baseUrl` | Prefer `https://api.minimax.io/anthropic` (Anthropic-compatible); `https://api.minimax.io/v1` is optional for OpenAI-compatible payloads |
| `models.providers.minimax.api` | Prefer `anthropic-messages`; `openai-completions` is optional for OpenAI-compatible payloads |
| `models.providers.minimax.apiKey` | MiniMax API key (`MINIMAX_API_KEY`) |
| `models.providers.minimax.models` | Define `id`, `name`, `reasoning`, `contextWindow`, `maxTokens`, `cost` |
| `agents.defaults.models` | Per-model aliases, parameters, and metadata |
| `agents.defaults.modelPolicy.allow` | Optional explicit model allowlist |
| `models.mode` | Keep `merge` if you want to add MiniMax alongside built-ins |
Thinking defaults 
On `api: "anthropic-messages"`, Apus injects `thinking: { type: "disabled" }` for MiniMax M2.x models unless an earlier wrapper already set the `thinking` field in the payload. This prevents M2.x's streaming endpoint from emitting `reasoning_content` in OpenAI-style delta chunks, which would leak internal reasoning into visible output.

MiniMax-M3 is exempt: M3 returns an empty `content` array with `stop_reason: "end_turn"` when thinking is disabled, so Apus removes the implicit disabled default for M3 and, when a thinking level is set, forces `thinking: { type: "adaptive" }` instead.

`MiniMax-M3.1-Flash-Preview` requires adaptive thinking. Apus sends the selected level as `output_config.effort`; `/think low` through `/think max` select its five supported efforts. The default is `max`, and `off` is not offered because MiniMax rejects disabled thinking with HTTP 400. See [MiniMax's Anthropic API contract](https://platform.minimax.io/docs/api-reference/text-anthropic-api).

Available thinking levels per model family:

| Model family   | Levels                                   | Default    |
| -------------- | ----------------------------------------- | ---------- |
| `MiniMax-M3`   | `off`, `adaptive`                        | `adaptive` |
| `MiniMax-M3.1-Flash-Preview` | `low`, `medium`, `high`, `xhigh`, `max` | `max` |
| `MiniMax-M2.x` | `off`, `minimal`, `low`, `medium`, `high` | `off`      |
Fast mode 
`/fast on` or `params.fastMode: true` rewrites `MiniMax-M2.7` to `MiniMax-M2.7-highspeed` on the Anthropic-compatible stream path (`api: "anthropic-messages"`, provider `minimax` or `minimax-portal`).
Fallback example 
**Best for:** keep your strongest latest-generation model as primary, fail over to MiniMax M2.7. Example below uses Opus as a concrete primary; swap to your preferred latest-gen primary model.

```json5
{
  env: { vars: { MINIMAX_API_KEY: "sk-..." } },
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": { alias: "primary" },
        "minimax/MiniMax-M2.7": { alias: "minimax" },
      },
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.7"],
      },
    },
  },
}
```
Coding Plan usage details 
- Coding Plan usage API: `https://api.minimaxi.com/v1/token_plan/remains` or `https://api.minimax.io/v1/token_plan/remains` (requires a coding plan key).
- Usage polling derives the host from `models.providers.minimax-portal.baseUrl` or `models.providers.minimax.baseUrl` when configured, so global setups using `https://api.minimax.io/anthropic` poll `api.minimax.io`. Missing or malformed base URLs keep the CN fallback for compatibility.
- Apus normalizes MiniMax coding-plan usage to the same `% left` display used by other providers. MiniMax's raw `usage_percent` / `usagePercent` fields are remaining quota, not consumed quota, so Apus inverts them. Count-based fields win when present.
- When the API returns `model_remains`, Apus prefers the chat-model entry, derives the window label from `start_time` / `end_time` when needed, and includes the selected model name in the plan label so coding-plan windows are easier to distinguish.
- Usage snapshots treat `minimax`, `minimax-cn`, `minimax-portal`, and `minimax-portal-cn` as the same MiniMax quota surface, and prefer stored MiniMax OAuth before falling back to Coding Plan key env vars.

Notes

See Model providers for provider rules.

Troubleshooting

"Unknown model: minimax/MiniMax-M3" 
This usually means the **MiniMax provider is not configured** (no matching provider entry and no MiniMax auth profile/env key found). Fix by:

- Running `apus configure` and selecting a **MiniMax** auth option, or
- Adding the matching `models.providers.minimax` or `models.providers.minimax-portal` block manually, or
- Setting `MINIMAX_API_KEY`, `MINIMAX_OAUTH_TOKEN`, or a MiniMax auth profile so the matching provider can be injected.

Make sure the model id is **case-sensitive**:

- API-key path: `minimax/MiniMax-M3`, `minimax/MiniMax-M2.7`, or `minimax/MiniMax-M2.7-highspeed`
- OAuth path: `minimax-portal/MiniMax-M3`, `minimax-portal/MiniMax-M2.7`, or `minimax-portal/MiniMax-M2.7-highspeed`

Then recheck with:

```bash
apus models list
```

More help: Troubleshooting and FAQ.

Related

Model selection

Choosing providers, model refs, and failover behavior.

Image generation

Shared image tool parameters and provider selection.

Music generation

Shared music tool parameters and provider selection.

Video generation

Shared video tool parameters and provider selection.

MiniMax Search

Web search configuration via MiniMax Token Plan.

Troubleshooting

General troubleshooting and FAQ.