Skip to main content
ستقدم هذه الوثيقة شرحًا حول واجهة برمجة تطبيقات Hailuo Videos Generation، والتي يمكن استخدامها لإنشاء مقاطع الفيديو الرسمية من Hailuo من خلال إدخال معلمات مخصصة.

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

لاستخدام واجهة برمجة تطبيقات Hailuo Videos Generation، يجب أولاً الذهاب إلى وحدة التحكم في Ace Data Cloud للحصول على رمز API الخاص بك، والاحتفاظ به للاستخدام لاحقًا. إذا لم تكن قد قمت بتسجيل الدخول أو التسجيل بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، وبعد الانتهاء، سيتم إرجاعك تلقائيًا إلى الصفحة الحالية. يمكن استخدام رمز API واحد لاستدعاء جميع خدمات المنصة، دون الحاجة لتقديم طلب منفصل لكل خدمة. عند التقديم لأول مرة، ستحصل على رصيد مجاني لتجربته؛ وعند نفاد الرصيد، يمكنك إعادة شحن الرصيد العام في وحدة التحكم.
📘 الوثائق الكاملة: Hailuo Videos Generation API →

​
الاستخدام الأساسي

أولاً، يجب أن نفهم طريقة الاستخدام الأساسية، وهي إدخال كلمة التلميح prompt، وسلوك التوليد action، وصورة الإطار الأول المرجعية first_image_url، بالإضافة إلى النموذج model، للحصول على النتيجة المعالجة. أولاً، نحتاج ببساطة إلى تمرير حقل action، الذي تكون قيمته generate، ثم نحتاج أيضًا إلى إدخال النموذج، والذي يتضمن حاليًا نموذج الفيديو الناتج من الصور minimax-i2v ونموذج الفيديو الناتج من النصوص minimax-t2v، المحتوى المحدد كما يلي:

يمكننا أن نرى هنا أننا قمنا بتعيين رؤوس الطلب، بما في ذلك:
  • accept: نوع الاستجابة التي ترغب في تلقيها، هنا يتم ملؤها بـ application/json، أي بتنسيق JSON.
  • authorization: مفتاح استدعاء API، يمكن اختياره مباشرة بعد التقديم.
بالإضافة إلى ذلك، تم تعيين جسم الطلب، بما في ذلك:
  • model: نموذج إنشاء الفيديو، والذي يتضمن نموذج الفيديو الناتج من الصور minimax-i2v ونموذج الفيديو الناتج من النصوص minimax-t2v.
  • action: سلوك مهمة إنشاء الفيديو هذه.
  • first_image_url: عند اختيار نموذج الفيديو الناتج من الصور minimax-i2v، يجب تحميل رابط صورة الإطار الأول المرجعية، ولا يدعم الترميز Base64.
  • prompt: كلمة التلميح.
  • callback_url: URL الذي يحتاج إلى استرجاع النتائج.
  • async: اختياري، إذا تم تعيينه إلى true، ستعيد الواجهة على الفور task_id، دون الحاجة لتقديم callback_url، ثم يمكن استعلام النتائج من خلال واجهة استعلام المهام المقابلة.
بعد الاختيار، يمكننا أن نرى أن الجانب الأيمن قد أنشأ أيضًا الكود المقابل، كما هو موضح في الصورة:

انقر على زر “Try” لإجراء الاختبار، كما هو موضح في الصورة أعلاه، هنا حصلنا على النتيجة التالية:
تتضمن النتيجة العائدة عدة حقول، كما يلي:
  • success: حالة مهمة إنشاء الفيديو في ذلك الوقت.
  • task_id: معرف مهمة إنشاء الفيديو في ذلك الوقت.
  • trace_id: معرف تتبع إنشاء الفيديو في ذلك الوقت.
  • data: قائمة نتائج مهمة إنشاء الفيديو في ذلك الوقت.
    • id: معرف الفيديو لمهمة إنشاء الفيديو في ذلك الوقت.
    • prompt: كلمة التلميح لمهمة إنشاء الفيديو في ذلك الوقت.
    • model: رابط الغلاف لمهمة إنشاء الفيديو في ذلك الوقت.
    • video_url: رابط الفيديو لمهمة إنشاء الفيديو في ذلك الوقت.
    • state: حالة مهمة إنشاء الفيديو في ذلك الوقت.
يمكننا أن نرى أننا حصلنا على معلومات الفيديو المرضية، كل ما علينا هو الحصول على الفيديو الناتج من Hailuo من خلال رابط الفيديو في data. بالإضافة إلى ذلك، إذا كنت ترغب في إنشاء الكود المقابل، يمكنك نسخه مباشرة، مثل كود CURL كما يلي:

​
الاسترجاع غير المتزامن

نظرًا لأن واجهة برمجة تطبيقات Hailuo Videos Generation تستغرق وقتًا طويلاً نسبيًا للتوليد، حوالي 1-2 دقيقة، إذا لم يكن هناك استجابة من API لفترة طويلة، ستظل طلبات HTTP متصلة، مما يؤدي إلى استهلاك موارد النظام الإضافية، لذا توفر هذه الواجهة أيضًا دعم الاسترجاع غير المتزامن. تتمثل العملية العامة في: عندما يقوم العميل بإرسال الطلب، يحدد حقل callback_url إضافي، بعد أن يقوم العميل بإرسال طلب API، ستعيد الواجهة على الفور نتيجة تحتوي على حقل task_id، الذي يمثل معرف المهمة الحالية. عند اكتمال المهمة، سيتم إرسال نتيجة الفيديو الناتج إلى callback_url المحدد من قبل العميل بصيغة POST JSON، والتي تتضمن أيضًا حقل task_id، بحيث يمكن ربط نتيجة المهمة من خلال المعرف. دعونا نفهم كيفية القيام بذلك من خلال مثال. أولاً، يعد استرجاع Webhook خدمة يمكنها استقبال طلبات HTTP، يجب على المطور استبدالها بعنوان URL الخاص بالخادم HTTP الذي قام بإنشائه. هنا، لتسهيل العرض، نستخدم موقع Webhook عام مثل https://webhook.site/، عند فتح هذا الموقع، ستحصل على عنوان URL لـ Webhook، كما هو موضح في الصورة: انسخ هذا العنوان URL، ويمكنك استخدامه كـ Webhook، والعينة هنا هي https://webhook.site/580b81f5-596e-4321-b03f-606770b0bb83. بعد ذلك، يمكننا تعيين حقل callback_url إلى عنوان URL الخاص بـ Webhook المذكور أعلاه، مع ملء المعلمات المناسبة، كما هو موضح في الصورة:

انقر على تشغيل، وستلاحظ أنك ستحصل على نتيجة على الفور، كما يلي:
بعد قليل، يمكنك ملاحظة نتيجة الفيديو الناتج على https://webhook.site/580b81f5-596e-4321-b03f-606770b0bb83، كما هو موضح في الصورة: المحتوى كما يلي:
يمكنك رؤية أن النتيجة تحتوي على حقل task_id، بينما الحقول الأخرى مشابهة لما سبق، من خلال هذا الحقل يمكنك تحقيق ارتباط المهام.

​
معالجة الأخطاء

عند استدعاء واجهة برمجة التطبيقات، إذا واجهت خطأ، ستقوم واجهة برمجة التطبيقات بإرجاع رمز الخطأ والمعلومات ذات الصلة. على سبيل المثال:
  • 400 token_mismatched：طلب غير صحيح، ربما بسبب معلمات مفقودة أو غير صالحة.
  • 400 api_not_implemented：طلب غير صحيح، ربما بسبب معلمات مفقودة أو غير صالحة.
  • 401 invalid_token：غير مصرح، رمز تفويض غير صالح أو مفقود.
  • 429 too_many_requests：عدد كبير جداً من الطلبات، لقد تجاوزت الحد الأقصى لمعدل الطلبات.
  • 500 api_error：خطأ في الخادم الداخلي، حدث خطأ ما على الخادم.

​
مثال على استجابة الخطأ

​
الاستنتاج

من خلال هذه الوثيقة، لقد فهمت كيفية استخدام واجهة برمجة تطبيقات توليد الفيديوهات Hailuo من خلال إدخال كلمات التوجيه وصورة الإطار الأول المرجعية لتوليد الفيديو. نأمل أن تساعدك هذه الوثيقة في التوصيل والاستخدام الأفضل لهذه الواجهة. إذا كان لديك أي استفسارات، لا تتردد في الاتصال بفريق الدعم الفني لدينا.