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

