كيفية استخدام واجهة برمجة تطبيقات ميني ماكس M3؟

MiniMax M3 هو نموذج رائد للاستدلال والبرمجة مع نافذة سياق تصل إلى 1,000,000 رمز. هذا الرقم هو العنوان الرئيسي. يمكنك إدخال مستودع كامل، أو سجلات أسبوع كامل، أو وثيقة تصميم طويلة وطلب منه الاستدلال على كل ذلك في مكالمة واحدة. إذا كنت تريد الخلفية حول ماهية النموذج وموقعه، فاقرأ ما هو MiniMax M3 أولاً.

هذا الدليل هو النسخة العملية. ستحصل على مفتاح API، وترسل طلبك الأول بثلاث طرق مختلفة، وتختبر كل خطوة في Apidog حتى تتمكن من رؤية الطلب والاستجابة الخامين قبل ربط أي شيء في التعليمات البرمجية الخاصة بك. قم بتنزيل Apidog إذا كنت ترغب في المتابعة.

المرجع الرسمي موجود في وثائق API الخاصة بـ MiniMax. احتفظ به مفتوحًا في علامة تبويب.

ما ستحتاجه

حساب MiniMax على platform.minimax.io.
مفتاح API (سنقوم بإنشاء واحد أدناه).
طريقة لدفع تكاليف الاستخدام: أرصدة الدفع حسب الاستخدام أو خطة اشتراك للرموز. كلاهما يعمل لنفس نقاط النهاية.

لا تحتاج إلى أي شيء آخر مثبت لأمثلة curl. لأمثلة SDK، ستحتاج إلى Python 3.8+ أو Node 18+.

الخطوة 1: احصل على مفتاح API الخاص بك

سجل الدخول إلى platform.minimax.io، وافتح قسم مفاتيح API في حسابك، وأنشئ مفتاحًا جديدًا. يصدر MiniMax نوعين من بيانات الاعتماد، والفرق مهم:

يتم فوترة مفتاح API العادي مقابل رصيد الدفع حسب الاستخدام الخاص بك.
يستخدم مفتاح الاشتراك أرصدة الرموز من خطتك (Plus، Max، أو Ultra). عندما تنفد رموز الخطة، تتوقف المكالمات على هذا المفتاح حتى تتجدد الخطة أو تنتقل إلى مفتاح الدفع حسب الاستخدام.

اختر ما يناسب طريقة الفوترة التي تريدها. انسخ المفتاح مرة واحدة وقم بتخزينه. لن تراه مرة أخرى.

لا تلصق المفتاح أبدًا مباشرة في الشيفرة المصدرية. بدلاً من ذلك، قم بتصديره كمتغير بيئة:

export MINIMAX_API_KEY="your-key-here"

هذا يحافظ على السرية بعيدًا عن سجل git الخاص بك وبعيدًا عن أي ملف قد تشاركه. إذا كنت تعمل أيضًا بمفاتيح API داخل محرر النصوص الخاص بك، فإن نفس قواعد النظافة تنطبق هناك. لقد غطينا التسربات الشائعة في أمان مفتاح API لإضافات VS Code.

الخطوة 2: أرسل طلبك الأول

عنوان URL الأساسي هو `https://api.minimax.io/v1` ومحادثة الدردشة موجودة على `POST https://api.minimax.io/v1/chat/completions`. المصادقة هي رمز حامل (bearer token): `Authorization: Bearer $MINIMAX_API_KEY`. سلسلة معرف النموذج هي `MiniMax-M3`.

هذه هي أصغر مكالمة مفيدة باستخدام curl. المهمة حقيقية، تطلب من النموذج إعادة هيكلة دالة:

curl https://api.minimax.io/v1/chat/completions \
 -H "Authorization: Bearer $MINIMAX_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"model":"MiniMax-M3","messages":[{"role":"user","content":"Refactor this function to be async."}]}'

لديك ثلاث طرق لاستدعاء M3. يوصي MiniMax باستخدام Anthropic SDK، لكن OpenAI SDK و HTTP الخام يعملان كلاهما على نفس نقطة النهاية. استخدم أيًا منهما تتحدث به مكدسك بالفعل.

هذا هو OpenAI SDK في Python. التغيير الوحيد عن إعداد OpenAI العادي هو `base_url`:

from openai import OpenAI

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

response = client.chat.completions.create(
 model="MiniMax-M3",
 messages=[
 {"role": "user", "content": "Refactor this function to be async."}
 ],
)

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

ونفس الفكرة في Node، مرة أخرى فقط إعادة توجيه `base_url`:

import OpenAI from "openai";

const client = new OpenAI({
 baseURL: "https://api.minimax.io/v1",
 apiKey: process.env.MINIMAX_API_KEY,
});

const response = await client.chat.completions.create({
 model: "MiniMax-M3",
 messages: [
 { role: "user", content: "Refactor this function to be async." },
 ],
});

console.log(response.choices[0].message.content);

إذا كنت قد استخدمت Qwen 3.7 API، فإن هذا النمط مألوف. معظم النماذج الرائدة تعرض الآن واجهة متوافقة مع OpenAI، لذا فإن تكلفة الترحيل هي سطر واحد. تغطي وثائق OpenAI Python SDK و وثائق Anthropic SDK خيارات العميل الكاملة.

الخطوة 3: اختبره وافحصه في Apidog

قبل أن تدمج هذه المكالمة داخل تطبيق، أرسلها يدويًا واقرأ الاستجابة الخام. هنا يثبت Apidog مكانه في الدورة.

أنشئ طلب HTTP جديدًا واضبط الطريقة على `POST` مع URL `https://api.minimax.io/v1/chat/completions`.
افتح لوحة البيئات وأضف متغيرًا باسم `MINIMAX_API_KEY` مع مفتاحك كقيمة. قم بتخزينه كمتغير بيئة حتى لا يبقى أبدًا في جسم الطلب أو في مجموعتك المشتركة.
في رؤوس الطلب، أضف `Authorization` بالقيمة `Bearer {{MINIMAX_API_KEY}}`. يقوم Apidog باستبدال المتغير وقت الإرسال.
اضبط الجسم على JSON خام والصق نفس الحمولة من مثال curl.
اضغط على إرسال وشاهد لوحة الاستجابة.

[لقطة شاشة: طلب واستجابة MiniMax-M3 في Apidog]

تخزين الرمز كمتغير بيئة يعني أنه يمكنك مشاركة الطلب مع زملائك في الفريق دون تسريب السر، ويمكنك تبديل المفاتيح (الدفع حسب الاستخدام مقابل الاشتراك) عن طريق تغيير متغير واحد. عندما تقوم بتشغيل البث لاحقًا، يعرض Apidog الأحداث المرسلة من الخادم فور وصولها، حتى تتمكن من تأكيد تنسيق البث قبل كتابة أي كود تحليل. فحص الاستجابة يدويًا يكتشف مفاجآت المخطط مبكرًا، وهذا هو الهدف الأساسي من اختبار نقطة نهاية قبل الوثوق بها.

الخطوة 4: تشغيل وإيقاف التفكير

M3 هو نموذج استدلالي. بشكل افتراضي، يعيد إجابة نهائية. يمكنك أيضًا أن تطلب منه الكشف عن استدلاله الوسيط، وهو أمر مفيد عندما تريد تصحيح الأخطاء لمعرفة سبب وصوله إلى نتيجة معينة أو إدخال الاستدلال في خطوة مراجعة.

باستخدام OpenAI SDK، قم بتمرير `reasoning_split` عبر `extra_body`:

from openai import OpenAI

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

response = client.chat.completions.create(
 model="MiniMax-M3",
 messages=[
 {"role": "user", "content": "Refactor this function to be async."}
 ],
 extra_body={"reasoning_split": True},
)

print(response.choices[0].message.reasoning_details[0]["text"]) # the thinking
print(response.choices[0].message.content) # the final answer

عندما يكون `reasoning_split` قيد التشغيل، يعود نص التفكير في `response.choices[0].message.reasoning_details[0]["text"]` وتبقى الإجابة النهائية في `response.choices[0].message.content`. حافظ على الفصل بين الاثنين في واجهة المستخدم الخاصة بك. أظهر للمستخدمين الإجابة، واحتفظ بالاستدلال للسجلات أو للتحقق.

قم بتشغيل التفكير للمشكلات الصعبة: إعادة هيكلة متعددة الخطوات، البحث عن الأخطاء الصعبة، أي شيء تريد فيه تدقيق السلسلة. قم بإيقافه للمكالمات البسيطة الحساسة للتأخير حيث تكلف رموز التفكير الإضافية وقتًا ومالًا لا تحتاج إلى إنفاقهما.

الخطوة 5: العمل مع سياق 1 مليون رمز

نافذة السياق الكبيرة هي السبب الرئيسي لاستخدام M3. يمكنك لصق ملف سجل كامل وطرح سؤال واحد عبر كل محتوياته:

with open("production-2026-05-30.log") as f:
 log_text = f.read()

response = client.chat.completions.create(
 model="MiniMax-M3",
 messages=[
 {
 "role": "user",
 "content": f"Find the root cause of the 502 spike at 14:20 UTC.\n\n{log_text}",
 }
 ],
)

هناك تفصيل متعلق بالفوترة يجب أن تعرفه. يفرض MiniMax سعرًا قياسيًا للمكالمات التي تحتوي على 512 ألف رمز إدخال أو أقل، وسعرًا أعلى للسياق الطويل بمجرد تجاوز المدخلات 512 ألف رمز. لذا، فإن القفزة من موجه بـ 400 ألف رمز إلى موجه بـ 600 ألف رمز ليست خطية. إنها تتجاوز عتبة تسعير.

الخلاصة العملية: لا تلقِ مليون رمز في السياق من باب العادة. أرسل الجزء الذي يحتاجه النموذج. إذا كنت تقوم بربط العديد من المكالمات في وكيل، فإن تقليم السياق لكل مكالمة هو أحد أكبر عوامل التأثير على فاتورتك. سنتعمق في ذلك في كيفية تقليل تكاليف رموز الوكيل.

الخطوة 6: استدعاء الأدوات والإدخال متعدد الوسائط

يتعامل M3 مع استدعاء الأدوات والإدخال متعدد الوسائط، لذا يمكنه تشغيل الوكلاء وقراءة الصور، وليس النص فقط.

بالنسبة لاستدعاء الأدوات، تقوم بتحديد الأدوات التي يسمح للنموذج باستدعائها، ثم تتعامل مع المكالمة التي يعيدها:

tools = [
 {
 "type": "function",
 "function": {
 "name": "run_tests",
 "description": "Run the test suite for a given module path.",
 "parameters": {
 "type": "object",
 "properties": {
 "module": {"type": "string"},
 },
 "required": ["module"],
 },
 },
 }
]

response = client.chat.completions.create(
 model="MiniMax-M3",
 messages=[
 {"role": "user", "content": "Fix the failing test in auth/session.py and confirm it passes."}
 ],
 tools=tools,
)

عندما يقرر النموذج استدعاء أداة، فإن الاستجابة تحمل مصفوفة `tool_calls`. يقوم الكود الخاص بك بتشغيل الدالة، ويلحق النتيجة كرسالة `tool`، ويستدعي API مرة أخرى حتى يتمكن النموذج من المتابعة. إتقان هذه المصافحة هو المكان الذي تكمن فيه معظم أخطاء الوكيل. أنماط الربط وأنماط الفشل تستحق القراءة قبل الشحن: ربط أدوات سير عمل الوكيل.

يساعد Apidog هنا أيضًا. يمكنك إعادة تشغيل التبادل متعدد الأدوار بالكامل (الطلب الأولي، استجابة استدعاء الأداة، نتيجة أداتك، المتابعة) كطلبات محفوظة منفصلة، بحيث يمكنك التحقق من كل قفزة من البداية إلى النهاية بدلاً من التخمين داخل وقت تشغيل وكيلك.

بالنسبة للإدخال متعدد الوسائط، تمرر محتوى الصورة في نفس مصفوفة الرسائل، جنبًا إلى جنب مع موجه النص الخاص بك، باتباع شكل أجزاء المحتوى القياسية. تحقق من مرجع API لأسماء الحقول الدقيقة، حيث تتطور هذه أسرع من نقاط نهاية النص.

التسعير والطبقات

هناك مؤشران منفصلان يتحكمان فيما تدفعه وسرعة الخدمة التي تتلقاها.

تحدد خطط الرموز ميزانية رصيدك. تتراوح مستويات الاشتراك بين Plus بسعر 20 دولارًا، و Max بسعر 50 دولارًا، و Ultra بسعر 120 دولارًا، وكل منها يجمع مجموعة أكبر من أرصدة الرموز التي يتم خصمها بواسطة مفتاح الاشتراك الخاص بك. بينما يتم دفع الفواتير لـ API Key العادي مقابل رصيدك بدلاً من ذلك.

تحدد مستويات الخدمة أولوية الجدولة. هناك اثنان: `standard` (الافتراضي) و `priority`. المستوى القياسي جيد لمعظم أعباء العمل. الأولوية مخصصة لحركة المرور الحساسة للتأخير أو المرتبطة باتفاقيات مستوى الخدمة (SLA) والتي لا يمكنها الانتظار في طابور خلف الآخرين.

يتراكم ذلك فوق المعدل القياسي مقابل معدل السياق الطويل من الخطوة 5، وتعتمد تكلفتك الفعلية على حجم الإدخال، الخطة، والمستوى معًا. للحصول على الأرقام الحالية لكل رمز، تحقق من صفحة MiniMax للتسعير والنموذج و وثائق API، حيث تتغير الأسعار المنشورة.

الأسئلة الشائعة

هل هناك طريقة مجانية لتجربة M3؟ نعم. يمكنك اختبار النموذج دون الالتزام بخطة، وهناك بعض الطرق المجانية. لقد جمعناها في كيفية استخدام MiniMax M3 مجانًا.

ما هي حزم SDK التي تعمل مع API؟ ثلاثة خيارات: HTTP الخام، و Anthropic SDK، و OpenAI SDK. توصي MiniMax بـ Anthropic SDK، ولكن جميع الثلاثة تستخدم نفس نقطة النهاية `https://api.minimax.io/v1/chat/completions`. بالنسبة لعملاء OpenAI و Anthropic، ما عليك سوى تغيير `base_url` للإشارة إلى MiniMax.

كيف يمكنني بث الاستجابات؟ أضف `"stream": true` إلى جسم طلبك. يعيد API أحداثًا مرسلة من الخادم، وكلا حزمتي SDK تعرضان مكررًا يمكنك التكرار عليه لقراءة الأجزاء عند وصولها. اختبر البث في Apidog أولاً حتى تتمكن من رؤية تنسيق الحدث قبل تحليله.

ما هو حد المعدل؟ تعتمد الحدود على مستوى حسابك وما إذا كنت تستخدم الخدمة `standard` أو `priority`. إذا واجهت 429، تراجع وحاول مرة أخرى، أو انقل حركة المرور الحساسة للتأخير إلى مستوى الأولوية. الأرقام الحالية موجودة في لوحة معلومات حسابك ووثائق API.

كيف تؤثر عتبة 512 ألفًا على فاتورتي؟ يتم فوترة المكالمات التي تحتوي على 512 ألف رمز إدخال أو أقل بالسعر القياسي. بعد 512 ألف رمز إدخال، يطبق معدل السياق الطويل الأعلى. قم بتقليص موجهك إلى الرموز التي يحتاجها النموذج بالفعل، خاصة في حلقات الوكيل حيث تتفاقم التكلفة عبر المكالمات.

هل يمكنني استضافة الأوزان بنفسي بدلاً من استدعاء API؟ API المستضاف هو المسار الذي يغطيه هذا الدليل، وهو أسرع طريقة للبدء. تعتمد الاستضافة الذاتية على ما تنشره MiniMax لـ M3 في أي وقت، لذا تحقق من صفحة النموذج لمعرفة الوضع الحالي للأوزان والتراخيص.

الخلاصة

لديك الآن كل ما تحتاجه لاستدعاء MiniMax M3: مفتاح API مخزن كمتغير بيئة، طلبات curl و Python و Node تعمل، مفتاح تبديل التفكير، عتبة فوترة 512 ألف رمز، ومصافحة استدعاء الأدوات. أسرع طريقة لتأكيد ذلك هي تشغيل مكالمة حقيقية واحدة يدويًا. أسقط نقطة النهاية في Apidog، وخزن الرمز المميز (bearer token) الخاص بك كمتغير بيئة، وأرسل موجه إعادة الهيكلة، واقرأ الاستجابة. بمجرد أن ترى الشكل الخام، يستغرق دمجها في التعليمات البرمجية الخاصة بك دقائق.

زر