> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# واجهة برمجة تطبيقات Hailuo لتوليد الفيديوهات - تعليمات الدمج

> Hailuo Video Generation 集成指南 - XHuoAPI

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

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

لاستخدام واجهة برمجة التطبيقات، يجب أولاً زيارة صفحة [واجهة برمجة تطبيقات Hailuo لتوليد الفيديوهات](https://api.xhuoapi.ai/documents/ee06377b-9185-438f-ac84-3376bcb1275e) للتقدم للحصول على الخدمة المناسبة، بعد دخول الصفحة، انقر على زر "Acquire" كما هو موضح في الصورة:

![](https://cdn.xhuoapi.ai/q6ytrc.png)

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

عند التقديم لأول مرة، سيكون هناك حد مجاني متاح، يمكنك استخدام واجهة برمجة التطبيقات مجانًا.

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

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

<p>
  <img src="https://cdn.xhuoapi.ai/7jyu0n.png" width="500" className="m-auto" />
</p>

يمكننا أن نرى هنا أننا قمنا بتعيين رؤوس الطلب، بما في ذلك:

* `accept`: نوع الاستجابة التي ترغب في تلقيها، هنا يتم ملؤها بـ `application/json`، أي بتنسيق JSON.
* `authorization`: مفتاح استدعاء واجهة برمجة التطبيقات، يمكن اختياره مباشرة بعد التقديم.

بالإضافة إلى ذلك، تم تعيين جسم الطلب، بما في ذلك:

* `model`: نموذج توليد الفيديو، والذي يتضمن نموذج توليد الفيديو من الصور `minimax-i2v` ونموذج توليد الفيديو من النصوص `minimax-t2v`.
* `action`: سلوك مهمة توليد الفيديو هذه.
* `first_image_url`: عند اختيار نموذج توليد الفيديو من الصور `minimax-i2v`، يجب تحميل رابط صورة الإطار الأول المرجعية، ولا يدعم الترميز Base64.
* `prompt`: كلمة التلميح.
* `callback_url`: URL الذي يحتاج إلى استدعاء النتائج.

بعد الاختيار، يمكننا أن نرى أن الجانب الأيمن قد تم توليد الكود المقابل، كما هو موضح في الصورة:

<p>
  <img src="https://cdn.xhuoapi.ai/8psuxw.png" width="500" className="m-auto" />
</p>

انقر على زر "Try" لإجراء اختبار، كما هو موضح في الصورة أعلاه، هنا حصلنا على النتيجة التالية:

```json theme={null}
{
  "success": true,
  "task_id": "baf1034c-684c-46be-ae6d-89ebb89b690d",
  "trace_id": "3221eb74-1a25-447a-ba69-7d9b310e306c",
  "data": [
    {
      "id": "0pv8yhe4fdrge0cmckpv23pd2g",
      "model": "minimax-t2v",
      "prompt": "Internal heat",
      "video_url": "https://file.aigpai.com/czjl/qoueLWBokF3ud6tdVD6VJTZuXTnK5HaMO2qAOS46Ef8VSBFUA/tmp9e3u11c1.output.mp4",
      "state": "succeeded"
    }
  ]
}
```

تتضمن النتيجة عدة حقول، كما يلي:

* `success`: حالة مهمة توليد الفيديو في ذلك الوقت.
* `task_id`: معرف مهمة توليد الفيديو في ذلك الوقت.
* `trace_id`: معرف تتبع توليد الفيديو في ذلك الوقت.
* `data`: قائمة نتائج مهمة توليد الفيديو في ذلك الوقت.
  * `id`: معرف الفيديو لمهمة توليد الفيديو في ذلك الوقت.
  * `prompt`: كلمة التلميح لمهمة توليد الفيديو في ذلك الوقت.
  * `model`: رابط الغلاف لمهمة توليد الفيديو في ذلك الوقت.
  * `video_url`: رابط الفيديو لمهمة توليد الفيديو في ذلك الوقت.
  * `state`: حالة مهمة توليد الفيديو في ذلك الوقت.

يمكننا أن نرى أننا حصلنا على معلومات الفيديو المرضية، كل ما علينا هو الحصول على رابط الفيديو الناتج من `data`.

بالإضافة إلى ذلك، إذا كنت ترغب في توليد الكود المقابل، يمكنك نسخه مباشرة، على سبيل المثال، كود CURL كما يلي:

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/hailuo/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "prompt": "Internal heat"
}'
```

## الاستدعاء غير المتزامن

نظرًا لأن واجهة برمجة تطبيقات Hailuo لتوليد الفيديوهات تستغرق وقتًا طويلاً نسبيًا، حوالي 1-2 دقيقة، إذا لم يكن هناك استجابة لفترة طويلة، ستظل طلبات HTTP متصلة، مما يؤدي إلى استهلاك موارد النظام الإضافية، لذا توفر هذه الواجهة أيضًا دعمًا للاستدعاء غير المتزامن.

تتمثل العملية العامة في: عندما يقوم العميل بإرسال الطلب، يحدد حقل `callback_url` إضافي، بعد أن يقوم العميل بإرسال طلب واجهة برمجة التطبيقات، ستقوم الواجهة بإرجاع نتيجة على الفور، تتضمن حقل `task_id`، الذي يمثل معرف المهمة الحالية. عند الانتهاء من المهمة، سيتم إرسال نتيجة توليد الفيديو إلى `callback_url` المحدد من قبل العميل عبر POST JSON، والتي تتضمن أيضًا حقل `task_id`، بحيث يمكن ربط نتيجة المهمة من خلال المعرف.

دعونا نفهم كيفية القيام بذلك من خلال مثال.

أولاً، يعد استدعاء Webhook خدمة يمكنها استقبال طلبات HTTP، يجب على المطور استبدالها بعنوان URL الخاص بخادم HTTP الذي قام بإنشائه. هنا، لتسهيل العرض، نستخدم موقع Webhook عام [https://webhook.site/،](https://webhook.site/،) عند فتح هذا الموقع، ستحصل على عنوان URL لـ Webhook، كما هو موضح في الصورة:

![](https://cdn.xhuoapi.ai/cjjfly.png)

انسخ هذا العنوان URL، يمكنك استخدامه كـ Webhook، والعينة هنا هي `https://webhook.site/580b81f5-596e-4321-b03f-606770b0bb83`.

بعد ذلك، يمكننا تعيين حقل `callback_url` إلى عنوان URL الخاص بـ Webhook المذكور أعلاه، مع ملء المعلمات المناسبة، كما هو موضح في الصورة:

<p>
  <img src="https://cdn.xhuoapi.ai/odabh3.png" width="500" className="m-auto" />
</p>

انقر على تشغيل، وستلاحظ أنك ستحصل على نتيجة على الفور، كما يلي:

```
{
  "task_id": "05aff65c-5e84-442b-8e29-3a5d27130840"
}
```

بعد قليل، يمكنك ملاحظة نتيجة توليد الفيديو على `https://webhook.site/580b81f5-596e-4321-b03f-606770b0bb83`، كما هو موضح في الصورة:

![](https://cdn.xhuoapi.ai/7jngb4.png)

المحتوى كما يلي:

```json theme={null}
{
    "success": true,
    "task_id": "05aff65c-5e84-442b-8e29-3a5d27130840",
    "trace_id": "b9856b8a-725d-45c9-befe-e789d9fd9ffb",
    "data": [
        {
            "id": "t80jhsf96srg80cmcm6b0rk8gm",
            "model": "minimax-t2v",
            "prompt": "Internal heat",
            "video_url": "https://file.aigpai.com/czjl/YPaUz2DcwpJqItTXAG9XHAoEoj3dbF0XPU69LT5nefCMzBFUA/tmp8s_59jez.output.mp4",
            "state": "succeeded"
        }
    ]
}
```

يمكننا أن نرى أن النتيجة تحتوي على حقل `task_id`، وجميع الحقول الأخرى مشابهة لما سبق، من خلال هذا الحقل يمكن تحقيق الربط بين المهام.

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

عند استدعاء واجهة برمجة التطبيقات (API)، إذا واجهت خطأ، ستقوم واجهة برمجة التطبيقات بإرجاع رمز الخطأ والمعلومات المناسبة. على سبيل المثال:

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

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

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## الاستنتاج

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