MiniMax is a widely used large language model service for building AI applications. It provides chat completion APIs that can be used for dialogue systems, AI assistants, content generation tools, coding workflows, and other LLM-powered products.

However, MiniMax’s authentication rules are different from the standard OpenAI API in some scenarios. This often causes confusion for developers who are migrating OpenAI-based projects or integrating MiniMax for the first time.

The most common issues include missing GroupId, incorrect base_url, wrong model names, streaming configuration errors, and misleading authentication failures.

This guide explains the full MiniMax API integration workflow. It covers credential preparation, differences between legacy and newer interfaces, authentication rules, OpenAI SDK integration, streaming output, error diagnosis, and best practices for third-party tools.

For teams that manage multiple LLM services, a unified forwarding or gateway layer can also reduce repeated configuration work and simplify cross-model maintenance.

1. Preparation: Get the Required Credentials

Before calling the MiniMax API, developers need to obtain two key credentials from the MiniMax Open Platform:

  • API Key
  • Group ID

These two values are used for authentication, billing, quota management, and permission control. Their usage depends on the API version.

After logging in to the MiniMax Open Platform, go to the API Keys page in the console. Create a new API Key and copy it immediately. The full key is usually shown only once. If it is lost, it cannot be viewed again, and a new key must be generated.

The Group ID is a numeric identifier linked to an individual or team account. It is usually associated with billing, quota statistics, and access permissions. Developers can find it in the account profile or organization settings section.

One important detail is that MiniMax has used different official domains in different stages. Historical domains include:

platform.minimax.chat
platform.minimaxi.com

Before integration, always check the latest official documentation. This prevents connection failures caused by expired domains or outdated endpoint paths.

2. API Versions and Authentication Rules

MiniMax has maintained two types of chat completion interfaces:

  • The newer v2 interface
  • The legacy v1 interface

The biggest difference between them is authentication logic. This is also the most common reason for integration failure.

API Version Request Path Authentication Method Group ID Requirement
New v2 /v1/text/chatcompletion_v2 or compatible path based on official docs Bearer token in HTTP header Usually not required
Legacy v1 /v1/text/chatcompletion Bearer token in HTTP header + Group ID in URL query Required

The legacy v1 interface has a common trap.

If developers call the v1 interface without GroupId, the service may return an HTTP 401 error with MiniMax internal error code 1004, which means authentication failed.

This error is easy to misread. Many developers assume the API Key is wrong and repeatedly regenerate keys. In reality, the real problem may be that the GroupId query parameter is missing.

In standard API design, missing required parameters often return HTTP 400. MiniMax’s legacy v1 behavior is different, so it deserves special attention.

The v2 interface is simpler. It generally follows an OpenAI-compatible calling style. Developers only need to pass the API Key in the request header:

Authorization: Bearer YOUR_MINIMAX_API_KEY

For new projects, the v2 interface is recommended. It is easier to configure, more compatible with existing SDKs, and less likely to cause hidden authentication issues.

3. Code Implementation for Different API Versions

3.1 Recommended: Use OpenAI SDK with the v2 Interface

The v2 interface is designed to be compatible with OpenAI-style API calls. If your existing project already uses the OpenAI SDK, migration can usually be completed with only minor changes.

First, install or upgrade the OpenAI Python SDK:

pip install --upgrade openai

Basic example:

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_MINIMAX_API_KEY",
    base_url="https://api.minimax.chat/v1"
)

response = client.chat.completions.create(
    model="MiniMax-Text-01",
    messages=[
        {"role": "user", "content": "Hello"}
    ]
)

print(response.choices[0].message.content)

During migration, two parameters are most important:

api_key="YOUR_MINIMAX_API_KEY"
base_url="https://api.minimax.chat/v1"

The model field must use a valid MiniMax model ID. Do not directly copy model names from OpenAI, Claude, Gemini, or other providers.

If the model name is wrong, the request may fail even when the API Key and endpoint are correct.

For most OpenAI-based projects, the message structure can remain unchanged:

messages=[
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Explain MiniMax API authentication."}
]

This keeps migration simple and reduces code rewriting.

3.2 Legacy v1 Interface: Use API Key + Group ID

Some older projects may still rely on the legacy v1 interface. If migration costs are high, developers can continue to use it. However, they must follow the dual-authentication rule:

API Key + Group ID

The key point is that GroupId must be passed as a URL query parameter. It should not be placed in the request body or request header.

Example:

import requests

url = "https://api.minimax.chat/v1/text/chatcompletion"

query_params = {
    "GroupId": "YOUR_MINIMAX_GROUP_ID"
}

headers = {
    "Authorization": "Bearer YOUR_MINIMAX_API_KEY",
    "Content-Type": "application/json"
}

request_body = {
    "model": "MiniMax-Text-01",
    "messages": [
        {"role": "user", "content": "Hello"}
    ]
}

response = requests.post(
    url=url,
    params=query_params,
    headers=headers,
    json=request_body,
    timeout=60
)

print(response.status_code)
print(response.json())

For legacy projects, add clear comments in the code:

# Legacy MiniMax v1 interface.
# GroupId must be passed as a URL query parameter.

This prevents future maintainers from removing GroupId by mistake.

4. Streaming Output for Production Use

Streaming output is useful for chatbots, coding assistants, customer service systems, and other interactive applications.

Instead of waiting for the full response, the server sends generated content in fragments. This improves perceived response speed and makes the interface feel more responsive.

MiniMax’s OpenAI-compatible interface can work with SDK streaming mode.

Example:

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_MINIMAX_API_KEY",
    base_url="https://api.minimax.chat/v1"
)

stream_response = client.chat.completions.create(
    model="MiniMax-Text-01",
    messages=[
        {"role": "user", "content": "Write a short poem about spring."}
    ],
    stream=True
)

for chunk in stream_response:
    content = chunk.choices[0].delta.content or ""
    print(content, end="", flush=True)

In production, long streaming connections may occasionally disconnect because of network fluctuations.

A basic retry structure can improve stability:

from openai import OpenAI, APIConnectionError, RateLimitError
import time

client = OpenAI(
    api_key="YOUR_MINIMAX_API_KEY",
    base_url="https://api.minimax.chat/v1"
)

def call_with_retry():
    max_retries = 3

    for attempt in range(max_retries):
        try:
            stream_response = client.chat.completions.create(
                model="MiniMax-Text-01",
                messages=[
                    {"role": "user", "content": "Write a short poem about spring."}
                ],
                stream=True
            )

            for chunk in stream_response:
                content = chunk.choices[0].delta.content or ""
                print(content, end="", flush=True)

            return

        except RateLimitError:
            wait_time = 2 ** attempt
            print(f"\nRate limited. Retry after {wait_time}s.")
            time.sleep(wait_time)

        except APIConnectionError as error:
            wait_time = 2 ** attempt
            print(f"\nConnection error: {error}. Retry after {wait_time}s.")
            time.sleep(wait_time)

    raise RuntimeError("Request failed after multiple retries.")

call_with_retry()

For enterprise services, retry logic should also include logging, request IDs, timeout control, and alerting.

5. Common Errors and Troubleshooting

MiniMax returns internal error information in the response body. Developers should check both the HTTP status code and the MiniMax internal status_code.

5.1 Error Code 1004: Authentication Failed

Typical response:

{
  "base_resp": {
    "status_code": 1004,
    "status_msg": "authentication failed"
  }
}

Common causes:

  • Missing GroupId when calling the legacy v1 interface
  • Invalid API Key
  • Extra spaces in the Authorization header
  • Wrong request endpoint
  • Using an expired or deleted key

How to fix it:

If you are using the legacy v1 path:

/v1/text/chatcompletion

make sure the request includes:

?GroupId=YOUR_MINIMAX_GROUP_ID

If you are using the v2 interface, check that the header is correctly formatted:

Authorization: Bearer YOUR_MINIMAX_API_KEY

Also confirm that there are no invisible spaces before or after the API Key.

5.2 Error Code 1002: Rate Limit Exceeded

Typical cause:

Too many requests in a short period.

This usually corresponds to HTTP 429.

Common causes:

  • Free-tier QPS limit
  • Too many concurrent requests
  • No retry or queue mechanism
  • Long-running tasks occupying request capacity

Recommended solutions:

  • Add exponential backoff retry
  • Reduce concurrency
  • Use a request queue
  • Upgrade the account quota
  • Separate high-priority and low-priority traffic

Example retry delay strategy:

wait_time = min(2 ** attempt, 30)

This prevents the client from repeatedly hitting the service during rate limiting.

5.3 Error Code 1000: Invalid Request Body

This error usually means that the request body contains invalid parameters.

Common causes:

  • Wrong model name
  • Incorrect message format
  • Unsupported parameter
  • Invalid JSON structure
  • Passing fields from another provider’s API

A common mistake is copying a model name from another LLM provider. MiniMax uses its own model IDs. Always use the latest model list from the official documentation.

Also check the message format:

[
  {
    "role": "user",
    "content": "Hello"
  }
]

Avoid passing unsupported fields unless they are explicitly documented.

5.4 Incorrect base_url Configuration

Many developers mistakenly put the full endpoint path into base_url.

For SDK-based calls, base_url should usually point to the API root, not the full business endpoint.

Recommended format:

base_url="https://api.minimax.chat/v1"

Avoid this pattern:

base_url="https://api.minimax.chat/v1/text/chatcompletion_v2"

The SDK will build the final request path according to the method you call. If the full endpoint is placed in base_url, the final URL may be duplicated or malformed. This can result in 404 errors or unexpected request failures.

6. Usage Strategies for Different Scenarios

6.1 Individual Developers and Rapid Testing

For personal projects, prototypes, and quick validation, use:

v2 interface + OpenAI SDK

This setup is simple and familiar. It requires fewer custom configurations and avoids the legacy GroupId trap.

It is suitable for:

  • Chatbot prototypes
  • AI writing tools
  • Coding assistants
  • Lightweight internal tools
  • Model effect testing

6.2 Legacy Project Maintenance

If a production project already depends on the v1 interface, do not change it hastily.

Instead, do three things:

  1. Keep GroupId in the URL query.
  2. Add clear comments around the authentication logic.
  3. Plan gradual migration to the v2 interface.

This reduces the risk of sudden service interruption.

During refactoring, teams can wrap MiniMax calls into a separate client module. This makes future migration easier.

6.3 Multi-Model Management for Teams

Enterprise teams often use several LLM providers at the same time. Each provider may have different authentication rules, model names, base URLs, rate limits, and error formats.

Repeatedly configuring these details in every business system increases maintenance cost.

A unified forwarding or API gateway layer can centralize these configurations. Business code only needs to call one internal interface. Model switching can then be managed through configuration rather than code changes.

This is useful for teams that need:

  • Multi-model comparison
  • Fallback routing
  • Centralized API key management
  • Cost tracking
  • Unified logging
  • Environment isolation

6.4 Third-Party Tool Integration

Tools such as Cursor, Cherry Studio, and other AI development clients usually support OpenAI-compatible API settings.

When connecting MiniMax through the v2 interface, users generally need to configure only:

API Key
Base URL
Model name

Recommended values:

API Key: YOUR_MINIMAX_API_KEY
Base URL: https://api.minimax.chat/v1
Model: MiniMax-Text-01

The exact model name and endpoint should follow the latest MiniMax documentation.

After configuration, the usage experience is similar to standard OpenAI-compatible services.

7. Best Practices

MiniMax API integration is not difficult once the version difference is clear.

The main rule is simple:

Use v2 for new projects.
Use v1 only when maintaining legacy systems.

For stable integration, follow these best practices:

  1. Store API Keys securely Do not hard-code keys in frontend code, public repositories, or shared documents.

  2. Use environment variables Example:

    export MINIMAX_API_KEY="your_api_key"

  3. Confirm the correct API version Check whether the project uses v1 or v2 before debugging authentication errors.

  4. Do not forget Group ID in legacy v1 Missing GroupId is one of the most common causes of 1004 errors.

  5. Use official model IDs Do not reuse model names from OpenAI, Claude, Gemini, or other platforms.

  6. Keep base_url clean Use the API root instead of the full endpoint path when using SDKs.

  7. Enable streaming for interactive products Streaming improves user experience in chat and coding tools.

  8. Add retry logic for production Handle rate limits, network errors, and temporary service failures.

  9. Log request IDs and error bodies This makes troubleshooting easier when failures occur.

  10. Review official documentation regularly Domains, model names, and interface paths may change over time.

8. Conclusion

The main challenge of MiniMax API integration is not the chat request itself. The real difficulty lies in understanding the difference between the legacy v1 interface and the newer v2 interface.

The v2 interface is simpler and more compatible with OpenAI SDK workflows. It is the recommended choice for new projects. Developers only need to configure the API Key, base URL, and model name correctly.

The legacy v1 interface requires both API Key and Group ID. Its authentication failure message can be misleading, because a missing GroupId may appear as a 401 authentication error.

For production systems, streaming output, retry logic, secure key management, and clear error logging are essential. For teams managing multiple model providers, a unified gateway or forwarding layer can further reduce maintenance work.

A stable MiniMax integration should follow three principles:

Choose the right API version.
Configure authentication correctly.
Build defensive error handling.

With these practices, developers can integrate MiniMax into chatbots, coding assistants, workflow agents, and enterprise AI applications more efficiently and reliably.