> ## 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.

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

> Luma Video Generation 集成指南 - XHuoAPI

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

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

ومع ذلك، لم تقدم Luma رسميًا واجهة برمجة التطبيقات، حيث تقدم XHuoAPI مجموعة من واجهات برمجة التطبيقات الخاصة بـ Luma، والتي تحاكي الاتصال بـ Suno الرسمي، مما يسهل ويسرع عملية توليد الفيديوهات المطلوبة.

## التقديم والاستخدام

لاستخدام واجهة برمجة تطبيقات Luma Videos، يمكنك أولاً زيارة صفحة [Luma Videos Generation API](https://api.xhuoapi.ai/documents/5bd3597d-1ff8-44ad-a580-b66b48393e7f) والنقر على زر "Acquire" للحصول على الشهادات المطلوبة:

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

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

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

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

لإنشاء أي فيديو، يمكنك إدخال نص عشوائي، على سبيل المثال، إذا كنت ترغب في إنشاء فيديو عن رواد الفضاء الذين ينتقلون بين الفضاء والبراكين، يمكنك إدخال `Astronauts shuttle from space to volcano`، كما هو موضح في الصورة:

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

الكود الناتج كما يلي:

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

المعلمات الرئيسية المطلوبة:

* `prompt`: كلمة المرور لتوليد الفيديو.
* `aspect_ratio`: نسبة عرض الفيديو، الافتراضي 16:9.
* `end_image_url`: اختياري، لتحديد الإطار النهائي.
* `enhancement`: اختياري، مفتاح تعزيز الوضوح.
* `loop`: هل يتم توليد فيديو متكرر، الافتراضي false.
* `timeout`: اختياري، عدد الثواني للمهلة.
* `callback_url`: عنوان الاستدعاء غير المتزامن.

يمكنك النقر على زر "Try" لاختبار واجهة برمجة التطبيقات مباشرة، انتظر 1-2 دقيقة، والنتيجة كما يلي:

```json theme={null}
{
  "success": true,
  "task_id": "e4018a99-1522-4f24-9330-62c2a9b50b59",
  "video_id": "155838f8-7f1e-44d8-b387-192f3b4b509d",
  "prompt": "Astronauts shuttle from space to volcano",
  "video_url": "https://storage.cdn-luma.com/dream_machine/af94e7ca-da35-4b5f-a636-2d7254184d0d/watermarked_video0585de3737db946e5a0ac895384ecd180.mp4",
  "video_height": 752,
  "video_width": 1360,
  "state": "completed",
  "thumbnail_url": "https://platform.cdn.xhuoapi.ai/luma/e4018a99-1522-4f24-9330-62c2a9b50b59.jpg",
  "thumbnail_width": 1360,
  "thumbnail_height": 752
}
```

يمكنك أن ترى أننا حصلنا على معلومات الفيديو ذات الصلة، بما في ذلك معرف الفيديو، رابط الفيديو، غلاف الفيديو، وما إلى ذلك.

تفسير الحقول كما يلي:

* success: هل تم التوليد بنجاح، إذا كان ناجحًا فسيكون `true`، وإلا سيكون `false`
* task\_id: المعرف الفريد لمهمة توليد الفيديو هنا
* video\_id: المعرف الفريد للفيديو الناتج عن مهمة توليد الفيديو هنا
* prompt: الكلمات الرئيسية لمهمة توليد الفيديو هنا
* video\_url: رابط الفيديو الناتج عن مهمة توليد الفيديو هنا
* video\_height: ارتفاع صورة غلاف الفيديو الناتج
* video\_width: عرض صورة غلاف الفيديو الناتج
* state: حالة مهمة توليد الفيديو هنا، إذا كانت المهمة مكتملة فستكون `completed`.
* thumbnail\_url: رابط صورة غلاف الفيديو الناتج
* thumbnail\_width: عرض صورة غلاف الفيديو الناتج
* thumbnail\_height: ارتفاع صورة غلاف الفيديو الناتج

## توليد الإطارات المخصصة

إذا كنت ترغب في توليد الفيديو من خلال تخصيص الإطارات الأولى والأخيرة، يمكنك إدخال روابط الصور للإطارات:

في هذه الحالة، يمكن تمرير الصورة التالية كإطار أول للفيديو في حقل `start_image_url`:

![الإطار الأول](https://cdn.xhuoapi.ai/r9vsv9.png)

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

* action: سلوك مهمة توليد الفيديو، عادةً ما يكون التوليد العادي `generate` أو التوليد الموسع `extend`، الافتراضي هو `generate`.
* start\_image\_url: تحديد الإطار الأول للفيديو الناتج.
* end\_image\_url: تحديد الإطار الأخير للفيديو الناتج.
* prompt: محتوى الكلمات الرئيسية لتوليد الفيديو.

مثال على كيفية التعبئة كما يلي:

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

بعد الانتهاء من التعبئة، تم توليد الكود كما يلي:

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

الكود المقابل:

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/luma/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "start_image_url": "https://cdn.xhuoapi.ai/r9vsv9.png",
    "action": "generate",
    "prompt": "Astronauts shuttle from space to volcano"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

النتيجة الناتجة كما يلي:

```json theme={null}
{
  "success": true,
  "task_id": "12a18694-fd4b-47e7-9c50-34f30862cff6",
  "video_id": "0105c090-03a5-425a-8026-523341cd575b",
  "prompt": "Astronauts shuttle from space to volcano",
  "video_url": "https://platform.cdn.xhuoapi.ai/luma/12a18694-fd4b-47e7-9c50-34f30862cff6.mp4",
  "video_height": 656,
  "video_width": 1552,
  "state": "completed",
  "thumbnail_url": "https://platform.cdn.xhuoapi.ai/luma/12a18694-fd4b-47e7-9c50-34f30862cff6.jpg",
  "thumbnail_width": 1552,
  "thumbnail_height": 656
}
```

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

![الإطار الأخير](https://cdn.xhuoapi.ai/0iad3k.png)

مثال على كيفية التعبئة كما يلي:

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

وأخيرًا، نحصل على النتيجة كما يلي:

```json theme={null}
{
  "success": true,
  "task_id": "d1cb723a-e554-4775-94a4-bb6ae8c7ea67",
  "video_id": "6bebd0d2-f793-472e-9326-38528a9273bb",
  "prompt": "رواد الفضاء ينتقلون من الفضاء إلى البركان",
  "video_url": "https://platform.cdn.xhuoapi.ai/luma/d1cb723a-e554-4775-94a4-bb6ae8c7ea67.mp4",
  "video_height": 656,
  "video_width": 1552,
  "state": "مكتمل",
  "thumbnail_url": "https://platform.cdn.xhuoapi.ai/luma/d1cb723a-e554-4775-94a4-bb6ae8c7ea67.jpg",
  "thumbnail_width": 1552,
  "thumbnail_height": 656
}
```

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

## ميزات توسيع الفيديو

إذا كنت ترغب في الاستمرار في إنشاء الفيديو الناتج، يمكنك تعيين المعامل `action` إلى `extend`، وإدخال ID الفيديو أو رابط الفيديو الذي تحتاج إلى الاستمرار في إنشائه، يمكن الحصول على ID الفيديو ورابط الفيديو بناءً على الاستخدام الأساسي كما هو موضح في الصورة أدناه:

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

في هذه الحالة، يمكنك رؤية ID الفيديو هو:

```
"video_id": "0105c090-03a5-425a-8026-523341cd575b",
"video_url": "https://platform.cdn.xhuoapi.ai/luma/12a18694-fd4b-47e7-9c50-34f30862cff6.mp4"
```

> ملاحظة: هنا، `video_id` و `video_url` في الفيديو هي ID ورابط الفيديو الناتج، إذا كنت لا تعرف كيفية إنشاء الفيديو، يمكنك الرجوع إلى الاستخدام الأساسي المذكور أعلاه لإنشاء الفيديو.

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

* action: في هذه الحالة، سلوك توسيع الفيديو، يجب أن يكون `extend`.
* prompt: الكلمات الرئيسية التي تحتاج إلى توسيع الفيديو.
* video\_url: الرابط الذي يحتاج إلى توسيع الفيديو الناتج.
* video\_id: ID الفريد الذي يحتاج إلى توسيع الفيديو الناتج.
* end\_image\_url: يمكن تحديد رابط صورة الإطار الأخير لتوسيع الفيديو، وهو معامل اختياري.

نموذج التعبئة كما يلي:

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

بعد ملء المعلومات، تم إنشاء الكود تلقائيًا كما يلي:

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

الكود المقابل بلغة بايثون:

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/luma/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "extend",
    "video_id": "0105c090-03a5-425a-8026-523341cd575b",
    "prompt": "رواد الفضاء ينتقلون من الفضاء إلى البركان"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

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

```json theme={null}
{
  "success": true,
  "task_id": "c6e529d1-a06d-4c12-91b2-c855135131c3",
  "video_id": "36908c49-c2bb-4a11-bd5a-b8512b004818",
  "prompt": "رواد الفضاء ينتقلون من الفضاء إلى البركان",
  "video_url": "https://platform.cdn.xhuoapi.ai/luma/c6e529d1-a06d-4c12-91b2-c855135131c3.mp4",
  "video_height": 656,
  "video_width": 1552,
  "state": "مكتمل",
  "thumbnail_url": "https://platform.cdn.xhuoapi.ai/luma/c6e529d1-a06d-4c12-91b2-c855135131c3.jpg",
  "thumbnail_width": 1552,
  "thumbnail_height": 656
}
```

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

بالطبع، يمكننا أيضًا تحديد رابط الفيديو للتوسيع، ملء المعلومات كما يلي:

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

بعد التشغيل، حصلنا على النتيجة التالية:

```json theme={null}
{
  "success": true,
  "task_id": "1dcb5902-a7be-4b77-ba5d-dd8ec82b26ca",
  "video_id": "f0187dc2-339f-4a08-a435-c3a3341f620a",
  "prompt": "رواد الفضاء ينتقلون من الفضاء إلى البركان",
  "video_url": "https://platform.cdn.xhuoapi.ai/luma/1dcb5902-a7be-4b77-ba5d-dd8ec82b26ca.mp4",
  "video_height": 656,
  "video_width": 1552,
  "state": "مكتمل",
  "thumbnail_url": "https://platform.cdn.xhuoapi.ai/luma/1dcb5902-a7be-4b77-ba5d-dd8ec82b26ca.jpg",
  "thumbnail_width": 1552,
  "thumbnail_height": 656
}
```

يمكنك أن ترى من النتيجة أنه يمكن أيضًا تحقيق وظيفة توسيع الفيديو بناءً على رابط الفيديو.

أخيرًا، يمكننا أيضًا تحديد صورة الإطار الأخير في الفيديو الموسع للتوسيع، أدناه معلومات صورة الإطار الأخير:

![صورة الإطار الأخير](https://cdn.xhuoapi.ai/0iad3k.png)

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

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

عند النقر على التشغيل، حصلنا على المعلومات التالية:

```json theme={null}
{
  "success": true,
  "task_id": "b816b2b4-c345-4673-9e19-83e91f91b643",
  "video_id": "c5400053-63e6-4206-8082-31cf9dd1e7ed",
  "prompt": "رواد الفضاء ينتقلون من الفضاء إلى البركان",
  "video_url": "https://platform.cdn.xhuoapi.ai/luma/b816b2b4-c345-4673-9e19-83e91f91b643.mp4",
  "video_height": 656,
  "video_width": 1552,
  "state": "مكتمل",
  "thumbnail_url": "https://platform.cdn.xhuoapi.ai/luma/b816b2b4-c345-4673-9e19-83e91f91b643.jpg",
  "thumbnail_width": 1552,
  "thumbnail_height": 656
}
```

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

## ردود غير متزامنة

نظرًا لأن وقت إنشاء الفيديو بواسطة Luma طويل نسبيًا، حوالي 1-2 دقيقة، إذا لم يكن هناك استجابة من API لفترة طويلة، ستظل طلبات HTTP متصلة، مما يؤدي إلى استهلاك موارد النظام الإضافية، لذا فإن هذه API توفر أيضًا دعم الردود غير المتزامنة.
整体流程是：客户端发起请求的时候，额外指定一个 `callback_url` 字段，客户端发起 API 请求之后，API 会立马返回一个结果，包含一个 `task_id` 的字段信息，代表当前的任务 ID。当任务完成之后，生成音乐的结果会通过 POST JSON 的形式发送到客户端指定的 `callback_url`，其中也包括了 `task_id` 字段，这样任务结果就可以通过 ID 关联起来了。

下面我们通过示例来了解下具体怎样操作。

首先，Webhook 回调是一个可以接收 HTTP 请求的服务，开发者应该替换为自己搭建的 HTTP 服务器的 URL。此处为了方便演示，使用一个公开的 Webhook 样例网站 [https://webhook.site/，打开该网站即可得到一个](https://webhook.site/，打开该网站即可得到一个) Webhook URL，如图所示：

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

将此 URL 复制下来，就可以作为 Webhook 来使用，此处的样例为 [https://webhook.site/0c87ca0e-cd74-4577-8d68-f2b80fbf8a13。](https://webhook.site/0c87ca0e-cd74-4577-8d68-f2b80fbf8a13。)

接下来，我们可以设置字段 `callback_url` 为上述 Webhook URL，同时填入 `prompt`，如图所示：

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

点击运行，可以发现会立即得到一个结果，如下：

```json theme={null}
{
  "task_id": "732f8282-7cf8-401c-95f2-42c33aa079a6"
}
```

稍等片刻，我们可以在 [https://webhook.site/0c87ca0e-cd74-4577-8d68-f2b80fbf8a13](https://webhook.site/0c87ca0e-cd74-4577-8d68-f2b80fbf8a13) 上观察到生成歌曲的结果，如图所示：

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

内容如下：

```json theme={null}
{
    "success": true,
    "task_id": "732f8282-7cf8-401c-95f2-42c33aa079a6",
    "video_id": "4d8013c3-5de0-41aa-966e-0b1a51d1c633",
    "prompt": "Astronauts shuttle from space to volcano",
    "video_url": "https://platform.cdn.xhuoapi.ai/luma/732f8282-7cf8-401c-95f2-42c33aa079a6.mp4",
    "video_height": 752,
    "video_width": 1360,
    "state": "completed",
    "thumbnail_url": "https://platform.cdn.xhuoapi.ai/luma/732f8282-7cf8-401c-95f2-42c33aa079a6.jpg",
    "thumbnail_width": 1360,
    "thumbnail_height": 752
}
```

可以看到结果中有一个 `task_id` 字段，其他的字段都和上文类似，通过该字段即可实现任务的关联。