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

# توضيح تكامل واجهة برمجة تطبيقات توليد فيديوهات Grok

> Grok API guide - Ace Data Cloud

ستتناول هذه الوثيقة توضيح تكامل واجهة برمجة تطبيقات توليد فيديوهات Grok، والتي يمكنها من خلال إدخال نصوص، صور، وصور مرجعية اختيارية توليد فيديوهات Grok Imagine (xAI).

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

لاستخدام واجهة برمجة تطبيقات توليد فيديوهات Grok، يجب أولاً الذهاب إلى [وحدة التحكم في بيانات Ace](https://platform.acedata.cloud/console/applications) للحصول على رمز API الخاص بك، للاحتفاظ به.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

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

**يمكن استخدام رمز API واحد لاستدعاء جميع خدمات المنصة، دون الحاجة لتقديم طلب منفصل لكل خدمة.** سيتم منحك رصيد مجاني عند الطلب الأول، لتجربته مجانًا؛ وعند نفاد الرصيد يمكنك إعادة شحن الرصيد العام في [وحدة التحكم](https://platform.acedata.cloud/console/coin).

> 📘 الوثائق الكاملة: [واجهة برمجة تطبيقات توليد فيديوهات Grok →](https://platform.acedata.cloud/documents/grok-videos)

## توضيح النموذج

تختار هذه الواجهة نقطة النهاية العلوية من خلال لاحقة اسم النموذج: `:reverse` تستخدم نقطة النهاية السريعة/القياسية (أرخص)، و`:official` تستخدم نقطة النهاية الرسمية (جودة أعلى، يتم احتساب الرسوم حسب ثواني الإخراج). تدعم أربعة نماذج:

* `grok-imagine-video-1.5-fast:reverse` (افتراضي): يدعم الفيديو الناتج عن النص (يتم تمرير `prompt` فقط) والفيديو الناتج عن الصورة (يتم تمرير `image_url`)، مدة 6–30 ثانية، يتم احتساب الرسوم حسب المدة، الأرخص.
* `grok-imagine-video:reverse`: يدعم الفيديو الناتج عن النص والصورة، مدة 1–15 ثانية، يتم احتساب الرسوم حسب ثواني الإخراج.
* `grok-imagine-video:official`: نقطة النهاية الرسمية، تدعم الفيديو الناتج عن النص والصورة، مدة 1–15 ثانية، يتم احتساب الرسوم حسب ثواني الإخراج، جودة أعلى.
* `grok-imagine-video-1.5:official`: نقطة النهاية الرسمية، **تدعم فقط الفيديو الناتج عن الصورة**، **يجب** تمرير `image_url`، مدة 1–15 ثانية، تدعم أعلى دقة `1080p`، يتم احتساب الرسوم حسب ثواني الإخراج.

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

أولاً، تعرف على طريقة الاستخدام الأساسية، إدخال نص `prompt`، نموذج `model` وغيرها من المعلمات، يمكنك من خلالها توليد الفيديو المقابل.

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

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

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

* `prompt`: نص يصف محتوى الفيديو الذي ترغب في توليده. **مطلوب** عند توليد فيديو ناتج عن النص؛ اختياري عند تمرير `image_url`.
* `model`: نموذج توليد الفيديو، يمكن أن يكون `grok-imagine-video-1.5-fast:reverse` (افتراضي)، `grok-imagine-video:reverse`، `grok-imagine-video:official` أو `grok-imagine-video-1.5:official`.
* `image_url`: رابط الصورة المدخلة لفيديو الناتج عن الصورة. **مطلوب** عندما يكون `model` هو `grok-imagine-video-1.5:official`.
* `reference_image_urls`: مصفوفة روابط الصور المرجعية الاختيارية، تستخدم لتوجيه أسلوب أو محتوى الفيديو.
* `aspect_ratio`: نسبة العرض إلى الارتفاع للفيديو الناتج، يمكن أن تكون `1:1` / `16:9` / `9:16` / `4:3` / `3:4` / `3:2` / `2:3`.
* `resolution`: دقة الإخراج، يمكن أن تكون `480p` (افتراضي)، `720p` أو `1080p`.
* `duration`: مدة الفيديو الناتج (ثواني). `grok-imagine-video-1.5-fast:reverse` تتراوح قيمتها بين 6–30، بينما النماذج الأخرى تتراوح بين 1–15، الافتراضي هو 6. يُوصى باستخدام 6 ثوانٍ أو 10 ثوانٍ، حيث أن هذين الطولين القياسيين أكثر استقرارًا.
* `callback_url`: عنوان رد الاتصال غير المتزامن، بعد تعيينه ستعيد الواجهة على الفور `task_id`، وعند الانتهاء من المهمة سيتم إرسال النتائج إلى هذا العنوان.
* `async`: اختياري، إذا تم تعيينه إلى `true` ستعيد الواجهة على الفور `task_id`، دون الحاجة لتوفير `callback_url`، ثم يمكنك الاستعلام عن النتائج من خلال واجهة استعلام المهام المقابلة.

انقر على زر "Try" لإجراء اختبار، وستكون النتائج مشابهة لما يلي:

```json theme={null}
{
  "success": true,
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea",
  "trace_id": "fb751e1e-4705-49ea-9fd4-5024b7865ea2",
  "data": [
    {
      "id": "grok-imagine-video-1.5-fast:reverse:41eb9a5f-3b2d-4d1e-9f5a-6c2f1a0b9e77",
      "video_url": "https://cdn.acedata.cloud/c8cbf53aa0.mp4",
      "state": "succeeded"
    }
  ]
}
```

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

* `success`: هل كانت طلب توليد الفيديو ناجحة.
* `task_id`: معرف مهمة توليد الفيديو هذه.
* `trace_id`: معرف تتبع الطلب، يستخدم لتحديد المشكلات.
* `data`: قائمة نتائج الفيديو الناتج.
  * `id`: المعرف الفريد للفيديو الناتج.
  * `video_url`: عنوان رابط الفيديو الناتج.
  * `state`: حالة مهمة توليد الفيديو، يمكن أن تكون `pending` / `succeeded` / `failed`.

نحتاج فقط إلى الحصول على الفيديو الناتج من عنوان رابط `video_url` في `data`.

الكود المقابل لـ CURL كما يلي:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/grok/videos' \
-H 'authorization: Bearer ${bearer_token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
  "model": "grok-imagine-video-1.5-fast:reverse",
  "resolution": "480p",
  "duration": 6
}'
```

الكود المقابل لـ Python كما يلي:

```python theme={null}
import requests

url = "https://api.acedata.cloud/grok/videos"

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

payload = {
    "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
    "model": "grok-imagine-video-1.5-fast:reverse",
    "resolution": "480p",
    "duration": 6
}

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

## فيديو الناتج عن الصورة

إذا كنت ترغب في توليد فيديو بناءً على صورة مدخلة، يمكنك تمرير `image_url`. عند استخدام `grok-imagine-video-1.5:official` يجب توفير هذا الحقل:

```json theme={null}
{
  "prompt": "The character slowly turns around and smiles at the camera",
  "model": "grok-imagine-video-1.5:official",
  "image_url": "https://cdn.acedata.cloud/5hmkdg.jpg",
  "resolution": "720p",
  "duration": 6
}
```

## توجيه الصور المرجعية

إذا كنت ترغب في استخدام صورة واحدة أو أكثر لتوجيه أسلوب أو محتوى الفيديو الناتج، يمكنك تمرير مصفوفة روابط الصور في `reference_image_urls`:

```json theme={null}
{
  "prompt": "A character dancing in the same art style",
  "model": "grok-imagine-video-1.5-fast:reverse",
  "reference_image_urls": [
    "https://cdn.acedata.cloud/vunnjf.png"
  ]
}
```

## رد الاتصال غير المتزامن

生成 الفيديو يحتاج إلى وقت معالجة معين. إذا كنت لا ترغب في الانتظار مع اتصال طويل، يمكنك تمرير `callback_url`، في هذه الحالة ستقوم API بإرجاع `task_id` على الفور، وعند الانتهاء من المهمة سيتم إرسال النتيجة النهائية عبر POST إلى هذا العنوان:

```json theme={null}
{
  "prompt": "لقطة سينمائية لقط صغير يطارد فراشة في حديقة مضاءة بأشعة الشمس",
  "model": "grok-imagine-video-1.5-fast:reverse",
  "duration": 6,
  "callback_url": "https://your-domain.com/callback/grok"
}
```

النتيجة التي تم إرجاعها على الفور هي كما يلي:

```json theme={null}
{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}
```

## استعلام عن نتائج المهمة

إذا تم استخدام ردود الفعل غير المتزامنة أو إذا كنت ترغب في استعلام حالة المهمة بشكل نشط، يمكنك من خلال [Grok Tasks API](https://platform.acedata.cloud/documents/grok-tasks) (`POST https://api.acedata.cloud/grok/tasks`) استعلام الحالة والنتيجة الأخيرة للمهمة بناءً على `task_id`.

## شرح الفوترة

طريقة الفوترة لهذه الخدمة تحددها `model`:

* `grok-imagine-video-1.5-fast:reverse`: يتم الفوترة حسب مدة الفيديو، غير مرتبطة بالدقة - `6–10` ثوانٍ، `11–20` ثانية، `21–30` ثانية تتوافق مع أسعار مختلفة.
* `grok-imagine-video:reverse`: يتم الفوترة حسب "عدد الثواني الناتجة"، السعر الإجمالي = السعر الفردي × `duration`.
* `grok-imagine-video:official` و `grok-imagine-video-1.5:official`: نقاط نهاية رسمية، يتم الفوترة حسب "عدد الثواني الناتجة"، كلما زادت الدقة زاد السعر الفردي؛ النماذج الرسمية ستفرض رسومًا حتى في حالة فشل مراجعة المحتوى.

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

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

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

* `400`: هناك خطأ في معلمات الطلب، مثل عدم وجود `prompt` في فيديو النص، أو عدم وجود `image_url` في `grok-imagine-video-1.5:official`، أو تجاوز `duration` النطاق (لـ `grok-imagine-video-1.5-fast:reverse` هو 6–30، وبقية النماذج هي 1–15).
* `401`: فشل في التوثيق، الرمز غير صالح أو لا يتطابق مع API.
* `403`: رصيد غير كافٍ، أو تم رفض المحتوى بسبب مراجعة المحتوى.
* `429`: الطلبات متكررة جدًا، يرجى المحاولة لاحقًا.
* `500`: فشل في توليد الفيديو أو حدوث خطأ في الخدمة.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.