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

​

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

📘 الوثائق الكاملة: واجهة برمجة تطبيقات توليد فيديوهات Grok →

​

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

• 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، يتم احتساب الرسوم حسب ثواني الإخراج.

​

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

• 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": 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.

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
}'

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)

​

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

{
  "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
}

​

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

{
  "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"
  ]
}

​

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

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

{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}

​

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

​

شرح الفوترة

• 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: نقاط نهاية رسمية، يتم الفوترة حسب “عدد الثواني الناتجة”، كلما زادت الدقة زاد السعر الفردي؛ النماذج الرسمية ستفرض رسومًا حتى في حالة فشل مراجعة المحتوى.

​

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

• 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: فشل في توليد الفيديو أو حدوث خطأ في الخدمة.