MiniMax M-series Production Wiring

OpenAI-compatible chat-completion endpoint at https://api.minimax.io/v1 with the M2.7-highspeed reasoning model (premium tier as of 2026-04-29). LOOKS LIKE OPENAI but silently drops 6 OpenAI parameters and exposes <think> reasoning traces inside content. Beyond chat-completion, the API is MiniMax-native (different URLs, different body shapes, different error envelopes — HTTP 200 + base_resp.status_code instead of HTTP 4xx).

The model itself is a competent qualitative judge + theory explainer + tool orchestrator for finance/quant work, but cannot do raw math on realistic data sizes (saturates reasoning budget) and hallucinates plausible details under input uncertainty (6 documented instances). For production: pair it with Python for math, sandbox validators for code, and deterministic detectors for pattern recognition.

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues. Source-of-truth campaign archive: ~/own/amonic/minimax/ (read-only reference; do not modify from this skill).

🆕 MiniMax-M3 is live (2026-06-01). This file covers M2.7. For M3 — native vision, reasoning_split clean output, response_format acceptance, ~1M input ceiling (reliable retrieval ≤ ~256K) / 524K output cap, n=1, and the docs-vs-reality discrepancies — use the sibling skill ../m3/SKILL.md and the evidence doc ../../references/M3-EMPIRICAL.md. The defensive snippets below (<think> strip, base_resp retry, cached-token reader) apply to M3 unchanged.

When to use M2.7 vs not — the decision table

Top 10 production rules

1. Always set a system prompt — it's at-most break-even, often net-positive. Long instructions in messages[0] get ~70% billing rate AND replace MiniMax's hidden ~30-token default. Detailed instructions belong in system role, NEVER user content.

2. Strip <think>...</think> from content before displaying. M-series exposes its reasoning trace inside the content string. Production: re.sub(r"<think>[\s\S]*?</think>\s*", "", content). Server-side stripping for billing on assistant replay (multi-turn doesn't double-bill).

3. max_tokens ≥ 1024 for non-trivial tasks. 512 is a silent-empty footgun. Reasoning consumes budget BEFORE visible content. Branch on finish_reason == "length" defensively.

4. Trust capability params, suspect control params. Honored: tools, messages, max_tokens, temperature, stream. Silently dropped: stop, tool_choice, response_format, streaming usage, image_url, messages[].name.

5. For JSON output, prompt-engineer it — response_format is silently dropped. Strict system prompt + temperature=0.2 + max_tokens=4096 + try/except json.loads = 100% reliability (6/6 verified).

6. Plain MiniMax-M2.7 for short-output workloads (<150 visible tokens); -highspeed for long-form. "Highspeed" is COUNTERINTUITIVELY slower for short outputs (Karakeep tagging at 5-15 tokens: plain is 2.5× faster).

7. Caching is COST-only on MiniMax, not LATENCY. Add cache_control: {type: "ephemeral"} to system messages for ~95% input-token cost reduction; don't expect interactive-UX latency benefits. Activates at ~600+ prompt_tokens. Prefix-match works (varied user + stable system gets ~70% hit rate).

8. Route financial math to Python — M2.7 saturates on QP / numerical integration / Sharpe on N≥50 returns. Pre-summarize aggregates (mean / stdev / n) and pass them; M2.7 handles the final-step formula. Define financial primitives as TOOLS for agent-loop orchestration.

9. NEVER trust M2.7-generated code without sandbox validation. compile() is INSUFFICIENT. M2.7 invents library imports (SMA, RSI, BollingerBands from backtesting.lib — none exist). Run in subprocess + capture exit code + iterative repair on failure.

10. NO HTTP 429 — rate-limited responses are HTTP 200 + base_resp.status_code=1002. Standard retry middleware that watches HTTP status WILL NOT catch this. Use code-prefix-based handler: 1xxx family = retry with backoff; 2xxx family = fix request, don't retry.

Canonical Tier F agentic stack (quant-LLM workflow)

F4: long-context retrieval         → M2.7 finds facts from filings/research
        ↓
F2: structured judgment as JSON    → M2.7 emits trade signal
        ↓
F6: tool orchestration             → M2.7 selects + calls tools (parallel + chained)
        ↓
F1+F8+F9: Python math layer        → numpy/scipy/cvxpy compute deterministically
        ↓
F3: textbook explanation           → M2.7 narrates the result with theory
        ↓
F5: sandbox-validated code         → M2.7 scaffolds; subprocess validates

The pattern: M2.7 for judgment / theory / orchestration; Python for math / validation / pattern detection. Never mix "explain + compute" in one prompt for complex problems — saturation is the failure mode.

Defensive code snippets (copy-paste ready)

Strip <think> tags + handle finish_reason

import re

def parse_minimax_response(response: dict) -> tuple[str, str | None]:
    """Returns (visible_content, error_class).
    error_class is None for normal responses; set when finish_reason indicates issues."""
    choice = response["choices"][0]
    raw_content = choice.get("message", {}).get("content", "")
    finish = choice.get("finish_reason")

    # Strip reasoning trace
    visible = re.sub(r"<think>[\s\S]*?</think>\s*", "", raw_content).strip()

    # Defensive: detect saturation (per iter-36/37 — empty visible + length finish)
    if finish == "length" and len(visible) < 50:
        usage = response.get("usage", {})
        reasoning_tokens = (usage.get("completion_tokens_details") or {}).get("reasoning_tokens", 0)
        max_tokens = usage.get("completion_tokens", 0)
        if reasoning_tokens >= max_tokens * 0.95:
            return visible, "saturated"
    if finish == "length":
        return visible, "truncated"
    return visible, None

Production-ready JSON output (no response_format reliance)

SYSTEM_PROMPT = """You are a trading signal generator. Output ONLY a JSON object with these exact 5 fields:
{
  "action": "long" | "short" | "flat",
  "confidence": <0.0 to 1.0>,
  "reasoning": "<one sentence explaining the setup>",
  "stop_loss_pct": <number, 0 if action=flat>,
  "take_profit_pct": <number, 0 if action=flat>
}
No markdown, no prose before or after, no code fences. Just the JSON object."""

# call with temperature=0.2, max_tokens=4096, model="MiniMax-M2.7-highspeed"
# then: signal = json.loads(parse_minimax_response(resp)[0])

Cache-friendly system prompt with prefix-match

def build_messages(user_input: str, stable_system: str) -> list[dict]:
    """stable_system varies per service but is constant per call. Cached after first call,
    re-used across varying user_input (~70% hit rate on prefix match)."""
    return [
        {
            "role": "system",
            "content": stable_system,
            "cache_control": {"type": "ephemeral"},  # Anthropic-style; honored by MiniMax
        },
        {"role": "user", "content": user_input},
    ]

# For short system prompts (<300 tokens), pad to ≥600 to ACTIVATE caching.
# Counterintuitive: more bytes = lower billable tokens once cached.

Rate-limit-aware retry (no HTTP 429 — parse base_resp)

import time

def call_with_retry(client_fn, body: dict, max_attempts: int = 5) -> dict:
    """MiniMax returns HTTP 200 + base_resp.status_code=1002 on rate limit.
    Standard HTTP-status-based middleware will NOT catch this."""
    for attempt in range(max_attempts):
        resp = client_fn(body)
        base_resp = resp.get("base_resp", {})
        code = base_resp.get("status_code", 0)
        if code == 0:
            return resp
        if code == 1002:  # rate limit
            time.sleep(2 ** attempt)
            continue
        if code in (1004, 2013, 2061):  # auth / params / plan-gated — don't retry
            raise RuntimeError(f"MiniMax error {code}: {base_resp.get('status_msg')}")
        raise RuntimeError(f"Unknown MiniMax error {code}: {base_resp.get('status_msg')}")
    raise RuntimeError("MiniMax rate limit persisted across max attempts")

Cached-token reader (handles both API shapes)

def get_cached_tokens(usage: dict) -> int:
    """MiniMax uses BOTH OpenAI-style (auto-cache) and Anthropic-style (explicit cache_control).
    Production parsers must handle BOTH variants."""
    pt_details = usage.get("prompt_tokens_details") or {}
    return (
        pt_details.get("cached_tokens", 0)               # OpenAI shape
        or usage.get("cache_read_input_tokens", 0)       # Anthropic shape
        or 0
    )

11 documented failure modes — defenses

Hallucination (6 instances) — fabricates plausible details under input uncertainty

Detection heuristic: reasoning_tokens > 2.5× baseline correlates with hallucination (per iter-35). Flag for review.

Saturation (4 instances) — exhausts reasoning budget on impossible math

Detection heuristic: is_saturated = (finish_reason=='length' AND len(visible)<50 AND reasoning_tokens >= 0.95*max_tokens). Don't retry with higher budget — route to Python instead.

Cross-language asymmetry (1 instance)

Defense: detect non-substantive responses (short + uncertainty language) for amonic services with multilingual users. Financial use cases unlikely to bite. International api.minimax.io applies Chinese-language-specific filtering on politically-sensitive content; English equivalents unfiltered.

API surface map (Plus-High-Speed plan)

Operational facts

OPS tooling — model-upgrade detection

The campaign produced an active tripwire: when MiniMax ships a new model, scheduled polling detects it and exits non-zero to force re-verification. See scripts/minimax-check-upgrade (ported in iter-16) and references/model-upgrade-detection.md.

# After install + lock-snapshot setup:
~/path/to/minimax-check-upgrade
# Exit 0 = no change (live matches locked snapshot)
# Exit 1 = upgrade detected (review diff before bumping lock)
# Exit 2 = fetch error

Recommended: schedule daily via launchd/cron. Add to CI as a pre-merge gate to refuse changes when the catalog has drifted without explicit lock review.

Deep references (drill into these for specifics)

• references/RETROSPECTIVE.md — the 41-iteration retrospective (TL;DR, top 10 rules, agentic stack, full failure-mode catalog, API surface, operational facts, open questions)
• references/quirks.md — use-case-organized critical findings (5 production-must-knows up front)
• references/api-patterns/INDEX.md — navigable TOC of 40 per-endpoint pattern docs
• references/api-patterns/<endpoint>.md — minimum-viable request/response shape, idiomatic snippets, known failure modes, reproducer commands, full provenance per probe
• references/fixtures/ — selected raw API responses for diffing against future API changes
• scripts/minimax-check-upgrade — model-upgrade detection executable
• templates/launchd-check-upgrade.plist — daily polling plist template

Quick-start for new amonic services

# 1. Set environment
export OPENAI_BASE_URL=https://api.minimax.io/v1
export OPENAI_API_KEY=<from 1Password>
export MINIMAX_MODEL=MiniMax-M2.7              # for tagging-style services
# OR: export MINIMAX_MODEL=MiniMax-M2.7-highspeed   # for long-form services

# 2. Verify wiring
curl -sS -X POST "$OPENAI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"model": "MiniMax-M2.7", "messages": [{"role": "user", "content": "Reply OK"}], "max_tokens": 200}' \
  | python3 -m json.tool | head -20

# 3. Add cache_control to your stable system prompt for ~95% input cost reduction (see snippet above)
# 4. Add the strip-<think> + finish_reason check to your response parser
# 5. Add base_resp.status_code rate-limit handler (no HTTP 429)
# 6. Run the plugin's scripts/minimax-check-upgrade as a local pre-merge gate

Provenance

Distilled from the 41-iteration minimax-m27-explore autonomous-loop campaign at ~/own/amonic/minimax/:

• 40 verified hands-on pattern docs (api-patterns/*.md)
• 1 quirks consolidation (quirks/CLAUDE.md — iter-11)
• 1 retrospective (RETROSPECTIVE.md — iter-42)
• 1 OPS tool with launchd plist (bin/minimax-check-upgrade + config/plists/)
• ~50 API response fixtures
• ~155 Non-Obvious Learnings, 35 critical findings, 11 documented failure modes, 4 error code families, 6 compat envelope categories

Campaign verified against MiniMax-M2.7-highspeed between 2026-04-28 and 2026-04-29. Re-verify against new model versions via bash scripts/minimax-check-upgrade (run from the plugin root).

Post-Execution Reflection

0. Locate yourself. — Confirm this SKILL.md is the canonical file before any edit.
1. What failed? — A wiring snippet stopped working, a parameter that was reported "silently dropped" now succeeds, or a base_resp.status_code mapping changed. Update the affected pattern doc + the table here so the next reader doesn't repeat the failure.
2. What drifted? — bash scripts/minimax-check-upgrade flagged a new model version, the OpenAI-compat envelope changed shape, or rate-limit / cache_control semantics shifted. Update the locked-snapshot pointer and the impacted sections.
3. Log it. — Append a dated line under "Provenance" (or a new "Evolution log" section) with trigger + fix + evidence so future iters can audit drift.