# MiniMax API Patterns — Verified Hands-On Reference

> **Aggregated copy** of `~/own/amonic/minimax/api-patterns/CLAUDE.md` (source-of-truth — read-only). The 39 sibling `./<name>.md` references resolve correctly within this plugin's `references/api-patterns/` directory once Phase B aggregation completes those files (iters 8-12). Aggregated 2026-04-29 (iter-7 of cc-skills minimax aggregation campaign).

Sub-spoke of [`../CLAUDE.md`](~/own/amonic/minimax/CLAUDE.md). One file per `/v1/<endpoint>` capturing verified hands-on patterns: minimum-viable request shape, full response anatomy, idiomatic usage snippets, known failure modes.

This directory is **autonomously populated** by the `/autonomous-loop` campaign in [`../LOOP_CONTRACT.md`](~/own/amonic/minimax/LOOP_CONTRACT.md). Each iteration probes one endpoint; findings land here.

## Files in this directory

| File                                                                                   | Endpoint covered                                                     | Status                                                                                                 |
| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| [`models-endpoint.md`](./models-endpoint.md)                                           | `GET /v1/models` — model catalog                                     | ✅ verified 2026-04-28                                                                                 |
| [`chat-completion-minimal.md`](./chat-completion-minimal.md)                           | `POST /v1/chat/completions` — minimum-viable shape                   | ✅ verified 2026-04-29 (`<think>` stripping required)                                                  |
| [`chat-completion-system-prompt.md`](./chat-completion-system-prompt.md)               | system role weighting                                                | ✅ verified 2026-04-29 (T3.10 RESOLVED — see system-token-scaling.md)                                  |
| [`chat-completion-system-token-scaling.md`](./chat-completion-system-token-scaling.md) | system-role billing model (T3.10 resolution)                         | ✅ verified 2026-04-29 (hybrid: replacement + ~70% discount)                                           |
| [`rate-limits.md`](./rate-limits.md)                                                   | rate-limit headers + burst tolerance (T3.1)                          | ✅ verified 2026-04-29 (NO rate-limit headers; per-endpoint asymmetry)                                 |
| [`errors-and-responses.md`](./errors-and-responses.md)                                 | error response shape catalog (T3.2)                                  | ✅ verified 2026-04-29 (two envelopes; no HTTP 404 or 413)                                             |
| [`context-window-boundary.md`](./context-window-boundary.md)                           | context window ceiling probe (T3.3)                                  | ✅ verified 2026-04-29 (~200K tokens; 3.6 chars/token English)                                         |
| [`chat-completion-multi-turn.md`](./chat-completion-multi-turn.md)                     | multi-turn state                                                     | ✅ verified 2026-04-29 (stateless)                                                                     |
| [`chat-completion-streaming.md`](./chat-completion-streaming.md)                       | `stream: true` SSE chunk shape                                       | ✅ verified 2026-04-29 (coarse chunks, no usage)                                                       |
| [`chat-completion-json.md`](./chat-completion-json.md)                                 | `response_format: {type: "json_object"}`                             | ✅ verified 2026-04-29 (silently dropped)                                                              |
| [`chat-completion-temperature.md`](./chat-completion-temperature.md)                   | determinism floor + temperature sweep                                | ✅ verified 2026-04-29 (temp=0 NOT deterministic)                                                      |
| [`chat-completion-stop.md`](./chat-completion-stop.md)                                 | `stop` sequence behavior                                             | ✅ verified 2026-04-29 (silently ignored)                                                              |
| [`chat-completion-max-tokens.md`](./chat-completion-max-tokens.md)                     | upper bound + reasoning interaction                                  | ✅ verified 2026-04-29 (server doesn't enforce)                                                        |
| [`chat-completion-tokens.md`](./chat-completion-tokens.md)                             | usage object + token math reconciliation                             | ✅ verified 2026-04-29 (server strips `<think>` on assistant replay)                                   |
| [`chat-completion-tools.md`](./chat-completion-tools.md)                               | function calling / tool use                                          | ✅ verified 2026-04-29 (tools honored; tool_choice silently dropped)                                   |
| [`chat-completion-name-field.md`](./chat-completion-name-field.md)                     | `messages[].name` field oddity                                       | ✅ verified 2026-04-29 (silently dropped; response always "MiniMax AI")                                |
| [`vision-image-url.md`](./vision-image-url.md)                                         | image content blocks                                                 | ✅ verified 2026-04-29 (silently dropped — M2.7 is text-only)                                          |
| [`web-search.md`](./web-search.md)                                                     | built-in `web_search` tool type discovery                            | ✅ verified 2026-04-29 (HTTP 400 — first 400 in campaign; not on this tier)                            |
| [`audio-tts.md`](./audio-tts.md)                                                       | `/v1/t2a_v2` TTS endpoint                                            | ✅ verified 2026-04-29 (endpoint discovered; all models plan-gated)                                    |
| [`video-generation.md`](./video-generation.md)                                         | `/v1/video_generation` async TTV endpoint                            | ✅ verified 2026-04-29 (endpoint discovered; async via task_id; plan-gated)                            |
| [`embeddings.md`](./embeddings.md)                                                     | `/v1/embeddings` (hybrid URL+body)                                   | ✅ verified 2026-04-29 (NOT plan-gated; RPM-throttled; pending vector retrieval)                       |
| [`files.md`](./files.md)                                                               | `/v1/files/{list,upload,delete}` Files API (sub-resource naming)     | ✅ verified 2026-04-29 (FULL CRUD works; no rate limits)                                               |
| [`concurrency.md`](./concurrency.md)                                                   | concurrent request behavior (T3.4)                                   | ✅ verified 2026-04-29 (TRUE parallelism up to p=10; soft ceiling beyond)                              |
| [`chat-completion-tps.md`](./chat-completion-tps.md)                                   | tokens/sec emission rate measurement (T3.5)                          | ✅ verified 2026-04-29 (~50 TPS asymptotic, NOT Plan's claimed 100)                                    |
| [`sensitivity-flags.md`](./sensitivity-flags.md)                                       | content moderation flag triggers (T3.6)                              | ✅ verified 2026-04-29 (NEGATIVE — flags inert)                                                        |
| [`model-aliasing.md`](./model-aliasing.md)                                             | plain M2.7 vs M2.7-highspeed comparison (T3.7)                       | ✅ verified 2026-04-29 (DISTINCT models; plain FASTER for short outputs)                               |
| [`finmath-accuracy.md`](./finmath-accuracy.md)                                         | financial math numerical accuracy (F1)                               | ✅ verified 2026-04-29 (accurate at adequate budget; Black-Scholes unsolvable)                         |
| [`trade-signal-json.md`](./trade-signal-json.md)                                       | trade signal JSON output via prompt engineering (F2)                 | ✅ verified 2026-04-29 (6/6 PRODUCTION-READY — 100% parse + structural + semantic)                     |
| [`finconcepts-knowledge.md`](./finconcepts-knowledge.md)                               | financial concept understanding (F3)                                 | ✅ verified 2026-04-29 (6/6 graduate-level theory; auto-grading caveat documented)                     |
| [`long-context-10k.md`](./long-context-10k.md)                                         | long-context 10-K needle-in-haystack (F4)                            | ✅ verified 2026-04-29 (4/4 full retrieval at 27K tokens; citations fabricated)                        |
| [`code-generation-validation.md`](./code-generation-validation.md)                     | backtesting.py code generation case study (F5)                       | ✅ verified 2026-04-29 (0/3 runtime — imports hallucinated; sandbox validation mandatory)              |
| [`financial-tool-use.md`](./financial-tool-use.md)                                     | financial tool use + agent loop (F6)                                 | ✅ verified 2026-04-29 (4/4 correct orchestration; weather-trap refused; ~2× redundancy on multi-step) |
| [`pattern-recognition.md`](./pattern-recognition.md)                                   | time-series chart pattern recognition (F7)                           | ⚠️ verified 2026-04-29 (DO NOT USE — 2/5 correct + random-walk trap triggered hallucination)           |
| [`portfolio-optimization.md`](./portfolio-optimization.md)                             | Markowitz portfolio optimization (F8)                                | ⚠️ verified 2026-04-29 (math saturates 8K reasoning; explains framework with KKT — Python for math)    |
| [`risk-metrics-chain.md`](./risk-metrics-chain.md)                                     | risk metrics chain VaR/CVaR/Calmar/Sortino/MDD-duration (F9)         | ⚠️ verified 2026-04-29 (saturates even SINGLE-metric on N=252; data volume drives saturation)          |
| [`mandarin-cross-language.md`](./mandarin-cross-language.md)                           | Mandarin financial content + cross-language asymmetry (F10/T4.3)     | ✅ verified 2026-04-29 (quality matches/exceeds English; political content filters by language)        |
| [`prompt-caching.md`](./prompt-caching.md)                                             | hybrid prompt caching (T4.1) — auto + explicit cache_control         | ✅ verified 2026-04-29 (hybrid OpenAI+Anthropic; 96.4% explicit hit; cost not latency benefit)         |
| [`cache-read-semantics.md`](./cache-read-semantics.md)                                 | cache-read semantics (T4.2) — threshold + prefix-match + TTL         | ✅ verified 2026-04-29 (threshold 264-597 pt; prefix-match works; TTL ≥ 3min; cross-session)           |
| [`model-upgrade-detection.md`](./model-upgrade-detection.md)                           | model-upgrade detection tooling (T4.4) — `mise run mm:check-upgrade` | ✅ shipped 2026-04-29 (bin/ + mise/ + locked snapshot; 5/5 tests pass; bash set-e bug captured)        |

## Fixtures

Raw API responses are persisted under [`fixtures/`](../fixtures/) so future sessions can diff against them when MiniMax upgrades models or changes response shapes. Naming: `<endpoint>-<descriptor>-<YYYY-MM-DD>.json`.

## Conventions across patterns

1. **Shell-quoting safety**: every example uses a `cat > /tmp/<name>.json << 'JSON'` heredoc + `curl --data @/tmp/<name>.json` pattern. Never inline JSON in `-d '...'` for non-trivial bodies. (Reason: discovered the hard way in iter-0.)
2. **Capture headers**: every probe uses `curl -D /tmp/<name>.headers` to record response headers. MiniMax sends non-standard `trace-id`, `minimax-request-id`, `alb_receive_time`, `alb_request_id` that are useful for support correlation but not in OpenAI's standard.
3. **Decode timestamps**: any `created` field is Unix epoch UTC. Decode in fixtures via `datetime.datetime.fromtimestamp(ts, tz=datetime.timezone.utc).isoformat()`.
4. **Mark provenance**: every pattern doc ends with the request-id + minimax-request-id + trace-id from the verifying call, so you can correlate to MiniMax billing/support if needed.
5. **No live keys in commits**: probes use `op read "op://<vault>/<item>/password"` — the resulting `$API_KEY` is process-scoped and never written to a file.
