MiniMax's text models expose an OpenAI-compatible API, so an existing OpenAI SDK usually needs only three changes: Base URL, API key, and model name. In practice, integration gets stuck on regional domains, model-name casing, reasoning content, and token parameters. This article follows the order "address — model — call — troubleshoot — migrate" to get your first call working.

The short version: the official OpenAI-compatible address ends in /v1, and the chat endpoint is /v1/chat/completions; model names must match official documentation exactly; new code should prefer max_completion_tokens and leave output budget for reasoning content.

Note: MiniMax is a trademark of its owner; this article is for technical explanation only. Model names, endpoints, context windows, and quotas are subject to MiniMax's official documentation and the model pricing page. Verify example model names in the console before using them in production.

1. Base URL: choose region and protocol first

MiniMax currently runs two domains — a China site and an international site — with three entry styles: OpenAI-compatible, Anthropic-compatible, and the native API. The most common choice is OpenAI-compatible: international https://api.minimax.io/v1, China https://api.minimax.cn/v1, with the chat endpoint POST /v1/chat/completions.

If you use the Anthropic SDK or a tool such as Claude Code, the official recommendation is the Anthropic-compatible entry: international https://api.minimax.io/anthropic, China https://api.minimax.cn/anthropic, with the messages endpoint POST /anthropic/v1/messages. The older native endpoint POST /v1/text/chatcompletion_v2 still exists, but new integrations should prefer the compatible interface for more consistent parameters and ecosystem support.

Scenario Base URL Typical endpoint
Official OpenAI-compatible (international) https://api.minimax.io/v1 POST /v1/chat/completions
Official OpenAI-compatible (China) https://api.minimax.cn/v1 POST /v1/chat/completions
Official Anthropic-compatible (international) https://api.minimax.io/anthropic POST /anthropic/v1/messages
Official Anthropic-compatible (China) https://api.minimax.cn/anthropic POST /anthropic/v1/messages
Native text endpoint https://api.minimax.io or https://api.minimax.cn POST /v1/text/chatcompletion_v2
ZSQH AI Gateway https://ai.zhongshangqihang.com/v1 POST /v1/chat/completions

The addresses in the table must come from the same platform as the key. A China-site key against an international address usually returns 401; a gateway key against an official address does the same. Another common mistake: the Base URL already includes /v1, and the request path appends it again, ending up as /v1/v1/chat/completions.

2. Model names: match case and version

As of October 2026, the current text models listed in official documentation are MiniMax-M3.1-Flash and MiniMax-M3, with a context window of 1,000,000 tokens. MiniMax-M3.1-Flash supports adjustable reasoning depth; MiniMax-M3 is a multimodal coding model of the same generation.

Previous-generation models remain listed: MiniMax-M2.7, MiniMax-M2.7-highspeed, MiniMax-M2.5, MiniMax-M2.5-highspeed, MiniMax-M2.1, MiniMax-M2.1-highspeed, and MiniMax-M2, with a 204,800-token context. There is also MiniMax-M2-her with a 64K context. Model names are case- and hyphen-sensitive; copy them instead of typing them by hand.

If you use the ZSQH AI Gateway, model names follow the model pricing page and may differ from official naming. Do not hardcode model names in code; keep them in environment variables or a configuration center so that switching changes configuration only.

3. curl: get one non-streaming request working

Set an environment variable MINIMAX_API_KEY with the key. The example uses the China-site OpenAI-compatible endpoint; for the international site, replace the domain with api.minimax.io, and for the gateway, replace it with the gateway address. Do not enable streaming yet; add it after confirming the response shape.

export MINIMAX_API_KEY="your-key"

curl "https://api.minimax.cn/v1/chat/completions" \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-M3.1-Flash",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Explain what a Base URL is in three sentences."}
    ],
    "max_completion_tokens": 512,
    "stream": false
  }'

In the returned JSON, choices[0].message.content is the final answer. With the M3 family, reasoning usually sits in the reasoning_content field while content holds only the final answer. Do not display the two as one blob unless your product is intended to show the reasoning process.

If you use the gateway, replace the address, key, and model name together. Changing only one of the three usually bounces between 401 and model not found.

4. Python: call with the OpenAI SDK

After installing openai, point base_url at MiniMax's compatible address. The example below keeps both the address and the model in environment variables so you can switch between official and gateway.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MINIMAX_API_KEY"],
    base_url=os.environ.get("MINIMAX_BASE_URL", "https://api.minimax.cn/v1"),
)

stream = client.chat.completions.create(
    model=os.environ.get("MINIMAX_MODEL", "MiniMax-M3.1-Flash"),
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Write a Python example that reads a CSV and counts its rows."},
    ],
    max_completion_tokens=1024,
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if not chunk.choices:
        continue
    delta = chunk.choices[0].delta
    if getattr(delta, "reasoning_content", None):
        print(delta.reasoning_content, end="")
    if delta.content:
        print(delta.content, end="")

In a streaming response, reasoning appears in delta.reasoning_content and the answer in delta.content; with stream_options.include_usage set to true, the final chunk carries usage. Different SDK versions may place unknown fields differently, so print a raw response once in a test environment before parsing.

5. Tokens and sampling parameters: don't just change max_tokens

For new integrations, prefer max_completion_tokens to control output length; max_tokens is marked as a legacy parameter in official documentation and may still be accepted, but new code should not rely on it. Reasoning tokens in the M3 family also count toward the output limit; set it too low and you will see finish_reason: "length" with empty content.

Common parameters:

  • temperature: controls randomness; the allowed range follows current documentation, and out-of-range values return 400.
  • top_p: defaults to 0.95 on the M3 family and 0.9 on M2.x; generally adjust only one of the two.
  • reasoning_effort: the M3 family supports low, medium, high, xhigh, and max, with max as default; lowering it reduces latency and output tokens.
  • thinking: MiniMax-M3.1-Flash forces reasoning on, and passing disabled returns 400; support on other models follows documentation.
  • n: only 1 is supported; parameters such as presence_penalty and frequency_penalty may be ignored.
  • Tool calling: use tools, not the legacy function_call; in multi-turn tool calls, pass the complete assistant message back into history, including tool_calls and reasoning content.

If latency is high, lower reasoning_effort first, then shorten input and output limits; do not switch models as the first move. Reasoning models usually trade quality and latency together, and with the right parameters many workloads do not need a smaller model.

6. Common errors: locate by status code

  • 401: key missing, malformed, or mismatched with the site or gateway. Check Authorization: Bearer and the Base URL.
  • 404: wrong path, or the Base URL has an extra or missing /v1. The OpenAI-compatible address ends with /v1; append /chat/completions.
  • model not found or model_not_found: model name misspelled, wrong case, or the account lacks access. Copy from documentation or the pricing page.
  • 400: out-of-range parameters, for example temperature out of range, thinking: disabled on M3.1-Flash, or an unsupported reasoning_effort value.
  • finish_reason: "length" with empty content: the output limit is too small; reasoning tokens consumed the budget. Raise max_completion_tokens.
  • 429: rate limited. Official documentation's reference is 200 RPM and 10,000,000 TPM for the M3 family, and 500 RPM and 20,000,000 TPM for M2.x; actual limits follow your account and console. Reduce concurrency and add backoff retries.
  • 5xx or timeouts: upstream fluctuation or network issues. Set timeouts, exponential backoff, and a fallback model; do not retry indefinitely.

Those rate-limit numbers are only the official documentation's reference values as of October 2026; they can differ by account, model, and endpoint. In production, trust the console and actual observations rather than saturating concurrency against documented numbers.

7. Migration checklist

  1. Confirm the target platform: official China site, official international site, or the ZSQH AI Gateway. Key and Base URL must come from the same platform.
  2. Change base_url: /v1 for OpenAI-compatible, /anthropic for Anthropic-compatible; do not mix them.
  3. Change model names: copy from official documentation or model pricing; mind case, hyphens, and version numbers.
  4. Change output parameters: prefer max_completion_tokens, and leave adequate budget for reasoning tokens.
  5. Check streaming parsing: read delta.content for the answer and delta.reasoning_content for reasoning; do not assume a single field.
  6. Check tool calls: use tools, and return the complete assistant message plus reasoning as officially required.
  7. Add timeouts, retries, and circuit breaking: exponential backoff for 429 and 5xx, plus a per-request timeout.
  8. Add logging and usage monitoring: record model name, latency, input and output tokens, and error codes; never log keys.
  9. Roll out gradually: switch one low-risk workload, compare quality and cost, then widen traffic.
  10. Prepare rollback: keep old configuration and old keys for a while, and clean up only after stability is confirmed.

This checklist also applies when migrating from OpenAI to MiniMax, or from direct official access to a gateway. Migration is not about changing one Base URL line; it is about verifying authentication, models, parameters, streaming parsing, and monitoring together.

8. Direct official access or a gateway?

If you use only MiniMax, have stable usage, and can complete official registration and billing directly, direct access is the shortest path. If you need several models, a unified bill, a unified key, or fewer configuration sets to maintain in mainland China network environments, a gateway fits better.

When choosing a gateway, confirm four things: which MiniMax models are supported, whether it is compatible with your endpoint style (OpenAI or Anthropic), whether billing rules are clear, and which support channel exists for incidents. Test with a small amount first, then move production traffic. Check models and billing on model pricing and create a test key from the sign-up page.

FAQ

What is the MiniMax API Base URL?

The international OpenAI-compatible address is https://api.minimax.io/v1, and the China site uses https://api.minimax.cn/v1. Anthropic-compatible entries use https://api.minimax.io/anthropic and https://api.minimax.cn/anthropic respectively. Use the site you registered on.

Is the MiniMax API compatible with the OpenAI SDK?

It is compatible with common chat endpoints. Point base_url at MiniMax's /v1 address and swap in MiniMax model names. Compatibility is not identity, though: reasoning fields, token parameters, and tool-calling details still differ.

Why is the content empty with finish_reason set to length?

The output limit was consumed by reasoning tokens. The M3 family counts reasoning toward the output budget; raise max_completion_tokens first, then check whether max_tokens is set too low.

Can reasoning be turned off?

MiniMax-M3.1-Flash forces reasoning on, and passing thinking: disabled returns 400. Whether other models support disabling it follows current official documentation; to reduce latency, lower reasoning_effort first.

What must change when migrating from OpenAI?

At minimum, change the key, Base URL, model names, and output parameters; then check streaming fields, tool calls, timeout and retry logic, and logging. We recommend running a non-streaming curl request first, then a streaming Python call, and finally a gradual rollout.

Next steps

Pick one model, get a non-streaming curl request working, then run a streaming call in Python; once content and reasoning_content both parse correctly, integrate your business logic. If you need a unified entry point, sign up for the ZSQH AI Gateway and check available models and billing on the model pricing page.

Related reading: