Skip to main content
يقدم هذا المقال تكامل واستخدام API لتوليد الفيديو MiniMax H3. تدعم هذه الواجهة توليد الفيديو من النص، والتحكم بالإطار الأول والأخير، وتوليد الفيديو بالمرجع متعدد الوسائط، وتستخدم بنية V2 موحّدة متعددة الوسائط content لإنشاء المهام.

عملية التقديم

لاستخدام API لتوليد الفيديو MiniMax H3، انتقل أولاً إلى وحدة تحكم Ace Data Cloud للحصول على API Token الخاص بك، واحتفظ به للاستخدام لاحقاً. إذا لم تكن قد سجلت الدخول أو أنشأت حساباً بعد، فسيتم تحويلك تلقائياً إلى صفحة تسجيل الدخول لدعوتك إلى التسجيل وتسجيل الدخول، وبعد الإكمال ستعود تلقائياً إلى الصفحة الحالية. يمكن لـ API Token واحد استدعاء جميع خدمات المنصة، ولا حاجة للتقديم بشكل منفصل لكل خدمة. سيُمنح رصيد مجاني عند أول تقديم، ويمكن التجربة مجاناً؛ وعندما لا يكون الرصيد كافياً، يمكن شحن الرصيد العام من وحدة التحكم.
📘 الوثائق الكاملة: API لتوليد الفيديو MiniMax H3 →
يُوصى بحفظ Token كمتغير بيئة، ولا تكتبه في الشيفرة المصدرية أو ترسله إلى مستودع الإصدارات:

نظرة عامة على الواجهة

  • Base URL: https://api.acedata.cloud
  • Endpoint: POST /minimax/videos
  • طريقة المصادقة: تضمين authorization: Bearer {token} في HTTP Header
  • رؤوس الطلب:
    • accept: application/json
    • content-type: application/json
  • النموذج (model): MiniMax-H3
  • بنية الإدخال: تمرير النصوص والصور ومقاطع الفيديو والصوت بشكل موحّد عبر content
  • وضع الإخراج: افتراضياً، ينتظر بشكل متزامن حتى يكتمل التوليد ويعيد task كاملاً؛ وعند تمرير async: true أو callback_url يعيد فوراً task_id وtrace_id
  • استعلام النتيجة: الحصول على الحالة والفيديو الناتج عبر API لاستعلام مهام MiniMax H3
  • رد الاتصال غير المتزامن: اختياري، استقبل نتيجة المهمة النهائية عبر callback_url
لا تحتاج إلى تمرير action لاختيار وضع التوليد، إذ ستحدد الواجهة الاستخدام تلقائياً بناءً على نوع المادة وrole في content.

ما السيناريوهات المناسبة

عملية الاستدعاء

عند عدم تمرير async افتراضياً، سينتظر /minimax/videos حتى يكتمل التوليد ويعيد task كاملاً مباشرةً. عند الحاجة إلى تحرير الاتصال فوراً، مرّر async: true أو callback_url:
  1. احفظ task_id وtrace_id في الاستجابة الفورية.
  2. عند عدم إعداد رد اتصال، استدعِ /minimax/tasks مرة كل 10 ثوانٍ تقريباً للاستعلام.
  3. عندما تصبح task.status هي succeeded، احصل على الفيديو من task.content.url.
  4. عندما تكون الحالة failed أو cancelled، أوقف الاستعلام الدوري واقرأ task.error.

معاملات الطلب العليا

تعتمد قواعد ratio على سير العمل:
  • توليد الفيديو من النص: مطلوب، ولا يمكن أن يكون adaptive.
  • فيديو الإطار الأول أو الإطار الأخير أو الإطار الأول والأخير: تحدد صورة الإدخال نسبة الأبعاد، ويُوصى بحذفه أو تمرير adaptive.
  • توليد الفيديو بالمرجع متعدد الوسائط: يمكن حذفه، والقيمة الافتراضية هي adaptive؛ ويمكن أيضاً تحديد نسبة ثابتة بوضوح.
لا تقبل الواجهة الحقول القديمة أو حقول التوافق، مثل prompt وimage_urls وaudio_urls وmessages وfirst_frame_image. عند تلقي أخطاء لهذه المعاملات، احذف الحقول القديمة وانتقل إلى content؛ مثلاً غيّر "prompt": "一只猫挥手" إلى "content": [{"type": "text", "text": "一只猫挥手"}]。لا ترسل التنسيقين الجديد والقديم في الوقت نفسه.

معاملات عناصر محتوى content

يجب أن يحتوي كل عنصر محتوى على type، وتُحدد الحقول الأخرى حسب النوع: تدعم عناوين الوسائط ثلاثة أشكال:
  • عنوان HTTPS متاح للعامة، ويوصى به للملفات الكبيرة.
  • mm_file://{file_id}، للإشارة إلى الملفات التي تم رفعها أو النتائج الموجودة بالفعل.
  • Base64 data URI لنوع الوسائط المقابل. يزيد Base64 الحجم بنحو الثلث، لذا تأكد من أن جسم الطلب بالكامل لا يتجاوز 64 MB.

مواصفات المواد وحدود الكمية

يمكن أن يصل إجمالي ملفات الصور والفيديو والصوت في سيناريو المراجع متعددة الوسائط إلى 12 ملفًا كحد أقصى. سيناريو الإطارين الأول والأخير وسيناريو المواد المرجعية متنافيان: بمجرد استخدام reference_image أو reference_video أو reference_audio، لا يمكن استخدام first_frame أو last_frame بعد ذلك، والعكس صحيح.

عرض قدرات على مستوى الإنتاج

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

فيلم قصير لعلامة تجارية فاخرة: توحيد الشخصية والمنتج وأصول العلامة التجارية

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

دراما قصيرة عمودية واقعية: اتساق الوجه والأداء العاطفي

هدف الإنتاج: إعلان تشويقي لدراما رومانسية مظلمة واقعية مدته 15 ثانية، بنسبة 9:16. ثبّت مظهر الشخصيات بالاعتماد على صور مرجعية للبطل والبطلة، وقيّد الفضاء باستخدام صورة مرجعية لقلعة قديمة؛ استخدم اللقطات المتوسطة القريبة واللقطات المقربة للوجه لإظهار مواجهة النظرات، والخوف، وضبط النفس، والإحساس بالخطر. هذه الحالة مناسبة لمراقبة استقرار ملامح الوجه البشري الواقعي، والتعبيرات الدقيقة، وعلاقات النظرات، والأداء المتواصل. فتح أو تنزيل الدراما القصيرة الواقعية مباشرة يجب أن تحدد المطالبة بوضوح علاقة الشخصيات والمشاعر وحجم اللقطة، بدلاً من مجرد وصف «حوار بين رجل وامرأة»:

إعلان نظارات عصرية: الحفاظ على تفاصيل الوجه وبنية المنتج

هدف الإنتاج: إعلان نظارات عصرية راقٍ بنسبة 9:16. تتولى الصورة الكاملة للجسم تحديد هيئة العارضة ومشيتها، وتتولى الصورة المرجعية للوجه تحديد ملامح الوجه والمكياج، وتتولى صورة المنتج تحديد المنحنيات المحيطة وانعكاسات العدسات وذراعي النظارة ومحيط عين القطة. تختبر هذه الحالة في الوقت نفسه اللقطات القريبة للوجه، واتساق عدة أشخاص، وعلاقة الارتداء، والبنية الهندسية للمنتج. فتح أو تنزيل إعلان النظارات العصرية مباشرة في إعلانات المنتجات، ينبغي أن تفصل المطالبة بوضوح بين أدوار مرجع الشخصيات ومرجع المنتج: تقيّد مواد الشخصيات الوجه والمكياج وهيئة الجسم والطابع؛ وتقيّد مواد المنتج المحيط والخامة والانعكاسات وموضع الارتداء. هذا أكثر استقراراً من كتابة «أنشئ إعلاناً للنظارات» بشكل عام.

تحويل النص إلى فيديو

عندما يكون هناك عنصر نصي واحد فقط، يكون ذلك تحويل النص إلى فيديو. وهو مناسب لتوليد المشاهد مباشرة من الإبداع أو السيناريو أو وصف اللقطات. يمكن تنظيم المطالبة وفق ترتيب «الموضوع + الحركة + المشهد + الكاميرا + الإضاءة + الصوت».
يعيد الوضع المتزامن الافتراضي المهمة الكاملة بعد اكتمال التوليد:
إذا أُضيف "async": true إلى الطلب، تعيد الواجهة فوراً:

تحويل صورة الإطار الأول إلى فيديو

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

فيديو الإطار الأخير وفيديو الإطارين الأول والأخير

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

توليد الفيديو بالرجوع إلى مراجع متعددة الوسائط

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

إشعار الاستدعاء

سيؤدي تمرير callback_url إلى تفعيل الوضع غير المتزامن تلقائيًا: تعيد واجهة الإنشاء فورًا task_id وtrace_id، وترسل النتيجة النهائية عبر POST إلى هذا العنوان بعد اكتمال المهمة، ويكون هيكلها متوافقًا مع استجابة استعلام المهمة. تكون الحالات النهائية في الاستدعاء هي succeeded أو failed أو cancelled. حتى عند استخدام الاستدعاء، يُوصى أيضًا بحفظ task_id لتسهيل الاستعلام النشط أو تعويض الإشعارات الفائتة.

الأخطاء الشائعة

يشير task.status: succeeded في الاستجابة المتزامنة إلى أن الفيديو قد تم إنشاؤه؛ أما التأكيد غير المتزامن فلا يعني سوى أن المهمة دخلت قائمة الانتظار. لا يتم احتساب الرسوم إلا عند نجاح المهمة نهائيًا، واستعلام المهمة نفسه مجاني ولا يؤدي إلى خصم متكرر.

H3 Max

يدعم MiniMax-H3-Max دقة 480P أو 768P، ومددًا صحيحة من 5 إلى 15 ثانية. لا تُفرض رسوم إضافية على إدخال الصوت، وأول صورتين مجانيتان، بينما تُحتسب رسوم لكل صورة إضافية؛ ويُحتسب الفيديو المرجعي وفقًا لمدة الإدخال الفعلية. لا يدعم هذا النموذج دقة 2K.