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

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

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

وصف النماذج

يمكن اختيار النماذج العامة الأربعة التالية عبر model، وتكون القدرات وطرق الفوترة المحددة كما يلي:
  • 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” لإجراء اختبار، وستكون النتائج مشابهة لما يلي:
تتضمن النتيجة عدة حقول، كما هو موضح أدناه:
  • success: هل كانت طلب توليد الفيديو ناجحة.
  • task_id: معرف مهمة توليد الفيديو هذه.
  • trace_id: معرف تتبع الطلب، يستخدم لتحديد المشكلات.
  • data: قائمة نتائج الفيديو الناتج.
    • id: المعرف الفريد للفيديو الناتج.
    • video_url: عنوان رابط الفيديو الناتج.
    • state: حالة مهمة توليد الفيديو، يمكن أن تكون pending / succeeded / failed.
نحتاج فقط إلى الحصول على الفيديو الناتج من عنوان رابط video_url في data. الكود المقابل لـ CURL كما يلي:
الكود المقابل لـ Python كما يلي:

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

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

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

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

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

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

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

إذا تم استخدام ردود الفعل غير المتزامنة أو إذا كنت ترغب في استعلام حالة المهمة بشكل نشط، يمكنك من خلال Grok Tasks API (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: فشل في توليد الفيديو أو حدوث خطأ في الخدمة.