MiniMax M3.1 Flash GGUF: Hardware, Setup, and API Costs

For MiniMax M3.1 Flash GGUF, start with UD-Q2_K_XL and a 160 GiB+ memory budget. Prefer UD-Q4_K_XL at 256 GiB+ when your machine has enough memory. If you need to buy hardware for occasional coding work, price an API trial first.

These Unsloth planning estimates assume 16K text context and one server slot, as of 2026-11-06. Memory can span RAM and VRAM, or use unified memory. The complete path below serves a local API and connects it to OpenCode 1.

How much memory does M3.1 Flash need?

Budget for the complete quantized weights, plus runtime overhead. The original MiniMax model card specifies approximately 428B parameters, with 23B active per token. That active count reduces computation; it does not make this a 23B model to load.

Unsloth publishes these sizes and planning targets. Download sizes use decimal GB; memory figures use GiB.

Quant	Download size	Weight size	Planning target
UD-IQ1_M	129.4 GB	120.5 GiB	Tight-memory experiment; see below
UD-Q2_K_XL	143.9 GB	134.0 GiB	160 GiB+
UD-IQ3_XXS	160.0 GB	149.1 GiB	176 GiB+
UD-IQ3_S	175.5 GB	163.4 GiB	192 GiB+
UD-Q3_K_XL	194.0 GB	180.6 GiB	208 GiB+
UD-Q4_K_XL	249.4 GB	232.3 GiB	256 GiB+
UD-Q8_K_XL	259.1 GB	241.3 GiB	272 GiB+

Unsloth allows roughly 20–32 GiB beyond the weights for the key-value cache, runtime, and operating system. The cache stores attention state for the current context. Longer contexts, additional slots, vision, and speculative decoding need more memory.

The 1-bit weights alone leave only 7.5 GiB on a 128 GiB machine. That is below the stated overhead allowance. For Q2, use Unsloth’s more conservative 160 GiB recommendation.

Combined RAM and VRAM are a placement budget, not an interchangeable pool. CPU offloading must leave enough host RAM for the displaced weights. Keep sufficient disk space for the selected download as well.

The model’s advertised 1M context does not change these estimates into 1M-context requirements. Start at 16K and increase it after checking memory use.

Which quant should you choose?

Use Q2 for the first fit test, then compare Q4 on your actual coding tasks if memory permits. Choose a 3-bit variant when Q4 exceeds your budget.

Unsloth’s headline and category figures measure different scopes:

Unsloth-reported top-1 agreement	UD-Q2_K_XL	UD-Q4_K_XL
Weighted headline summary	91.5%	98.0%
Coding	91.2%	97.6%
General chat	88.5%	97.3%
Math	95.7%	99.0%

The headline weights seven categories. The chat and math rows describe individual categories, which explains why Q2 has both 91.5% and 88.5% figures.

Top-1 agreement measures whether the quantized model selects the same highest-ranked token as the reference. It is not a coding-task pass rate. A 91.2% coding figure does not mean 91.2% of repository changes will pass their tests.

Treat 1-bit as an experiment under tight memory constraints, despite its approximately 89.9% headline agreement. Validate file edits, tool arguments, and multi-step behavior before relying on any quant.

Q8 adds 9.7 GB over Q4. Unsloth describes it as a lossless conversion of the released weights, retaining mixed NVFP4 and BF16 formats. The “8-bit” label therefore does not describe a uniform precision for every tensor.

Which runtime fits your hardware?

Choose a checkpoint and recipe designed for your runtime. A memory result from EXL3 does not establish that the corresponding GGUF will fit.

The following routes were checked as of 2026-11-06:

Hardware	Route to investigate	Practical boundary
Apple Silicon	MLX-community oQ3e checkpoint with oMLX	The checkpoint totals 196.152 GB / 182.681 GiB, including its draft and vision components. Add runtime and context memory.
One DGX Spark	vcruz305’s SAGE-EXL3 recipe	Targets a 128 GB GB10 system with pinned components, gated checkpoint access, text-only serving, and one decode stream.
AMD Instinct	AMD’s Quark MXFP4 checkpoint	The documented configuration names MI350/MI355, Linux, ROCm 7.2.3, and a four-GPU tensor-parallel example. It is not a generic Radeon recipe.
Four RTX 3090 cards	Custom inference credited in MiniMax’s November 1 community post	MiniMax attributes @superalesha’s approach to quantized weights, expert caching, and system RAM. The acknowledgement supplies no portable performance guarantee.

For a first GGUF deployment, follow the explicit llama.cpp path below. Before commercial deployment, review the MiniMax Community License, including its attribution and notice conditions.

Build llama.cpp and start a 16K server

Use the MiniMax support branch linked by Unsloth. As of 2026-11-06, llama.cpp PR #31192 remained open and unmerged. This example pins its observed head commit.

Build and download

Use Bash on Ubuntu or WSL with the NVIDIA CUDA toolkit already installed. Install the remaining prerequisites, then build the server:

sudo apt-get update
sudo apt-get install -y build-essential cmake git libssl-dev python3-venv curl jq

git clone https://github.com/ggml-org/llama.cpp
git -C llama.cpp fetch origin pull/31192/head:minimax-m31
git -C llama.cpp checkout --detach 6b95a9908d2c7b242817a447708aec38e937e2c0

cmake llama.cpp -B llama.cpp/build \
  -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_SHARED_LIBS=OFF \
  -DGGML_CUDA=ON
cmake --build llama.cpp/build --config Release -j --target llama-server

On macOS, install Xcode command line tools, CMake, Python, and jq; skip the apt-get commands. Change -DGGML_CUDA=ON to -DGGML_CUDA=OFF. The build documentation enables Metal by default on macOS.

Download all four Q2 shards through the Hugging Face CLI:

python3 -m venv .venv-m31
source .venv-m31/bin/activate
python -m pip install -U huggingface_hub

hf download unsloth/MiniMax-M3.1-Flash-GGUF \
  --local-dir unsloth/MiniMax-M3.1-Flash-GGUF \
  --include "UD-Q2_K_XL/*"

Keep the shards together. The server loads the complete set when you point it at the first shard.

Start and verify

Start with one slot, explicit 16K context, and ordinary text decoding:

./llama.cpp/build/bin/llama-server \
  --model unsloth/MiniMax-M3.1-Flash-GGUF/UD-Q2_K_XL/MiniMax-M3.1-Flash-UD-Q2_K_XL-00001-of-00004.gguf \
  --alias m31-local \
  --ctx-size 16384 \
  --parallel 1 \
  --n-gpu-layers auto \
  --jinja \
  --flash-attn on \
  --temp 1.0 \
  --top-p 0.95 \
  --top-k 0 \
  --min-p 0.0 \
  --chat-template-kwargs '{"reasoning_effort":"high"}' \
  --host 127.0.0.1 \
  --port 8080

The PR specifies Jinja, Flash Attention, and one slot for this sparse-attention path. The llama-server options support automatic GPU-layer allocation.

This command adds neither a vision projector nor a DSpark draft. It has no API key configured and listens only on the local loopback address.

If VRAM allocation fails, reduce the GPU-layer count and check available host RAM. If total memory is insufficient, choose a smaller quant or add memory. Offloading cannot remove the weight-storage requirement.

In a second Bash terminal, check readiness:

curl -sS -i http://127.0.0.1:8080/health

Proceed when the response is HTTP 200 with {"status":"ok"}. HTTP 503 with Loading model means initialization is still running.

Then discover the model and request a response:

curl -sS http://127.0.0.1:8080/v1/models | jq '.data[].id'

curl -sS http://127.0.0.1:8080/v1/chat/completions \
  -H 'Content-Type: application/json' \
  --data '{
    "model": "m31-local",
    "messages": [
      {"role": "user", "content": "Reply with LOCAL_OK."}
    ],
    "reasoning_effort": "low",
    "max_tokens": 4096,
    "stream": false
  }' | jq '{message: .choices[0].message, finish_reason: .choices[0].finish_reason}'

Check that model discovery includes m31-local and that message.content contains the requested answer. The request’s low effort overrides the server’s high default for this smoke test.

If finish_reason is length, the response exhausted its output allowance. Increase that allowance within the total context budget before treating missing final text as a model-loading failure.

Connect OpenCode 1 and verify a tool call

Use OpenCode’s documented custom-provider integration to connect the coding client. OpenCode runs file tools; llama-server generates the model responses.

This configuration follows the OpenCode 1 documentation. OpenCode 1 and OpenCode 2 share the opencode command, so use a separate environment if you already run V2.

For a new V1 installation, with Node.js and npm available:

npm install -g opencode-ai
opencode --version

Merge this configuration into opencode.json at your project root. It follows the official llama.cpp provider example:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "local": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "MiniMax local",
      "options": {
        "baseURL": "http://127.0.0.1:8080/v1"
      },
      "models": {
        "m31-local": {
          "name": "MiniMax M3.1 Flash Q2",
          "limit": {
            "context": 16384,
            "output": 4096
          }
        }
      }
    }
  }
}

No dummy API key is needed for this local configuration. The context limit matches the running server. The output limit is a chosen response budget, not the model’s maximum.

In a Node project containing package.json, run:

opencode run --model local/m31-local \
  "Read package.json with a file tool. Report scripts.test, or say it is missing. Do not edit files or run commands."

Look for an actual file-read tool step and compare the answer with the file. A statement that the model read the file is insufficient.

If the client cannot connect, check the /v1 base URL, model alias, and running server. If text works but tool execution fails, confirm --jinja and repeat this bounded check before attempting repository edits.

Keep the first session small. If tool definitions consume too much context, apply the measurement approach from the MCP context-cost guide before expanding the server window.

When should you use the API instead?

Start with the API when you would need new hardware for occasional use. Consider local deployment when you already own sufficient capacity or require local model execution.

As of 2026-11-06, MiniMax’s standard API tariff lists:

Billing item	USD per 1 million tokens
Uncached input	$0.15
Cached input read	$0.015
Output	$0.60

These are balance-based API usage charges. MiniMax also describes Flash’s rates as flat. Its cache formula bills new input, cache hits, and output without adding a separate cache-write item.

For an illustrative monthly workload of 20 million uncached input tokens and 2 million billed output tokens:

API token charge = 20 × $0.15 + 2 × $0.60
                 = $4.20 per month

This assumes text-only calls, no cache hits, and no paid server tools. Taxes and checkout fees are excluded.

For comparison, consider this illustrative local budget:

Hardware allocation = $3,000 ÷ 36 months
                    = $83.33 per month

Active electricity  = 0.15 kW × 60 hours × $0.20/kWh
                    = $1.80 per month

Local subtotal      = $85.13 per month

Every local input is an assumption. The calculation is not a quote for a verified machine or evidence that it finishes the workload in 60 hours. Add idle power, setup, maintenance, and any equipment upgrades before making a purchase decision.

Match reasoning effort when comparing actual runs. MiniMax’s API defaults to max, while this local server defaults to high. Use billed output usage, and evaluate cost per completed coding task with retries and failed tool steps included.

BetterToken also lists MiniMax-M3.1-Flash for pay-as-you-go access as of 2026-11-06. Its documented OpenAI-compatible base URL is https://www.bettertoken.ai/v1. Use its current prices when calculating that route.

If you already own the hardware, replace the illustrative allocation with your actual incremental costs. Then measure representative tasks: a local deployment becomes useful only when its fit, completion time, and accepted results meet your needs.