DEV Community

Cover image for كيفية استخدام واجهة برمجة تطبيقات Grok لتحويل النص إلى فيديو: دليل شامل
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

كيفية استخدام واجهة برمجة تطبيقات Grok لتحويل النص إلى فيديو: دليل شامل

الخلاصة

تولّد واجهة برمجة تطبيقات Grok لتحويل النص إلى فيديو مقاطع فيديو من موجه نصي. يمكنك استدعاء POST /v1/videos/generations، وستحصل على request_id فورًا، ثم تقوم باستطلاع GET /v1/videos/{request_id} حتى تصبح الحالة "done". النموذج هو grok-imagine-video، ويبدأ التسعير من 0.05 دولار لكل ثانية بدقة 480p. يتعامل xAI Python SDK مع الاستطلاع تلقائيًا.

جرّب Apidog اليوم

المقدمة

ولّدت xAI أكثر من 1.2 مليار مقطع فيديو في يناير 2026 وحده بعد إطلاق واجهة برمجة تطبيقات Grok لتحويل النص إلى فيديو. هذه الأرقام تؤكد أن البنية التحتية تعمل بكفاءة على نطاق واسع.

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

💡
واجهة برمجة التطبيقات غير متزامنة (async). هذا يعني أن الواجهة الأمامية لا تنتظر حتى يصبح الفيديو جاهزًا قبل عرض شيء للمستخدم. إذا كنت تبني UI لتوليد الفيديو، ستحتاج لطريقة تطوير مقابل تدفق الاستطلاع دون إنفاق اعتمادات على كل تجربة. استخدم Smart Mock من Apidog لمحاكاة نقطة نهاية التوليد والاستطلاع. يمكن بناء واجهة مستخدم مشغل الفيديو أثناء تطوير الباكند. حمّل Apidog مجانًا أو تابع قسم الاختبار أدناه.

ما هي واجهة برمجة تطبيقات Grok لتحويل النص إلى فيديو؟

Grok Video API جزء من مجموعة xAI لتوليد الوسائط على https://api.x.ai. ترسل موجهًا نصيًا ويولّد النموذج grok-imagine-video فيديو قصير من الصفر. لا حاجة لصورة مصدر.

يمكنك أيضًا استخدام نقطة نهاية توليد الصور (POST /v1/images/generations، النموذج grok-imagine-image) وتوسيع أو تعديل الفيديوهات.

نقطة نهاية تحويل النص إلى فيديو تختلف عن تحويل الصورة إلى فيديو: هنا تقدّم الكلمات فقط، والنموذج يولّد المشهد والحركة من وصفك. إذا كنت تريد تحريك صورة، راجع دليل تحويل الصورة إلى فيديو.

كيف يعمل توليد الفيديو من النص (شرح نمط عدم التزامن)

توليد الفيديو يستغرق وقتًا أكبر من طلبات API العادية. لهذا السبب، تستخدم Grok Video API نمط عدم التزامن:

  1. ترسل طلب POST مع الموجه.
  2. تحصل فورًا على request_id.
  3. يبدأ توليد الفيديو على الخادم.
  4. تستطلع نقطة نهاية GET بشكل متكرر مستخدمًا نفس request_id.
  5. عندما تتغيّر الحالة إلى "done"، تحصل على رابط الفيديو.

هذا يتطلب أن يدير كودك الحالة الوسيطة (الانتظار/التحميل) بشكل واضح ويظهر للمستخدم مؤشر تقدّم حتى يصبح الفيديو متاحًا.

المتطلبات الأساسية

قبل كتابة الكود، جهّز:

حساب xAI: أنشئ حسابًا على console.x.ai. أضف الفوترة ليعمل مفتاح API.

مفتاح API: من "API Keys" في لوحة التحكم، أنشئ مفتاحًا جديدًا واحتفظ به بشكل آمن. ستستخدمه كـ Bearer Token في كل طلب.

لقطة شاشة للوحة تحكم xAI تعرض قسم مفاتيح API.

لتخزين المفتاح:

export XAI_API_KEY="your_api_key_here"
Enter fullscreen mode Exit fullscreen mode

اختياري: ثبّت xAI Python SDK لأبسط تكامل:

pip install xai-sdk
Enter fullscreen mode Exit fullscreen mode

أول طلب لك لتحويل النص إلى فيديو

نقطة النهاية:

POST https://api.x.ai/v1/videos/generations

الحقول المطلوبة: model وprompt.

استخدام curl 

curl -X POST https://api.x.ai/v1/videos/generations \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "كلب جولدن ريتريفر يركض عبر أوراق الخريف بحركة بطيئة، إضاءة سينمائية"
  }'
Enter fullscreen mode Exit fullscreen mode

الاستجابة:

{
  "request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"
}
Enter fullscreen mode Exit fullscreen mode

استخدام بايثون مع مكتبة requests 

import requests
import os

API_KEY = os.environ["XAI_API_KEY"]
BASE_URL = "https://api.x.ai"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

payload = {
    "model": "grok-imagine-video",
    "prompt": "A golden retriever running through autumn leaves in slow motion, cinematic lighting"
}

response = requests.post(
    f"{BASE_URL}/v1/videos/generations",
    headers=headers,
    json=payload
)

data = response.json()
request_id = data["request_id"]
print(f"Generation started. Request ID: {request_id}")
Enter fullscreen mode Exit fullscreen mode

الاستطلاع للحصول على نتيجة الفيديو

عند الحصول على request_id، استطلع:

GET /v1/videos/{request_id}

حتى يصبح status: "done".

القيم الممكنة لـstatus:

  • "processing"
  • "done"
  • "failed"

مثال حلقة استطلاع بايثون:

import requests
import time
import os

API_KEY = os.environ["XAI_API_KEY"]
BASE_URL = "https://api.x.ai"

headers = {
    "Authorization": f"Bearer {API_KEY}"
}

def poll_video(request_id: str, interval: int = 5, max_attempts: int = 60) -> dict:
    url = f"{BASE_URL}/v1/videos/{request_id}"

    for attempt in range(max_attempts):
        response = requests.get(url, headers=headers)
        data = response.json()

        status = data.get("status")
        progress = data.get("progress", 0)
        print(f"Attempt {attempt + 1}: status={status}, progress={progress}%")

        if status == "done":
            return data
        elif status == "failed":
            raise RuntimeError(f"Video generation failed: {data}")

        time.sleep(interval)

    raise TimeoutError(f"Video not ready after {max_attempts} attempts")


def generate_video(prompt: str) -> str:
    response = requests.post(
        f"{BASE_URL}/v1/videos/generations",
        headers={**headers, "Content-Type": "application/json"},
        json={"model": "grok-imagine-video", "prompt": prompt}
    )
    request_id = response.json()["request_id"]
    print(f"Request ID: {request_id}")

    result = poll_video(request_id)
    video_url = result["video"]["url"]
    print(f"Video ready: {video_url}")
    return video_url


video_url = generate_video(
    "A timelapse of a city skyline at sunset transitioning to night, aerial view"
)
Enter fullscreen mode Exit fullscreen mode

استجابة الاستطلاع عند الاكتمال:

{
  "status": "done",
  "video": {
    "url": "https://vidgen.x.ai/....mp4",
    "duration": 8,
    "respect_moderation": true
  },
  "progress": 100,
  "usage": {
    "cost_in_usd_ticks": 500000000
  }
}
Enter fullscreen mode Exit fullscreen mode

استخدام xAI Python SDK

لتبسيط الاستطلاع، استخدم xAI SDK:

from xai_sdk import Client
import os

client = Client(api_key=os.environ["XAI_API_KEY"])

result = client.video.generate(
    model="grok-imagine-video",
    prompt="كلب جولدن ريتريفر يركض عبر أوراق الخريف بحركة بطيئة",
    duration=8,
    resolution="720p",
    aspect_ratio="16:9"
)

print(f"Video URL: {result.video.url}")
print(f"Duration: {result.video.duration}s")
Enter fullscreen mode Exit fullscreen mode

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

كتابة موجهات فعالة لتوليد الفيديو

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

مثال موجه فعّال:

رائد فضاء وحيد يطفو بجانب محطة الفضاء الدولية،
يجر خلفه حبل الربط. تتبع الكاميرا ببطء بجانبه، مع إظهار الأرض بالأسفل.
سينمائي، بجودة IMAX، ضوء شروق الشمس الدافئ ينعكس على الواقي.
Enter fullscreen mode Exit fullscreen mode

التحكم في الدقة، المدة، ونسبة العرض إلى الارتفاع

عند إرسال الطلب، يمكنك التحكم في عدة معلمات:

المدة:

"duration": 10
Enter fullscreen mode Exit fullscreen mode

من 1 إلى 15 ثانية (الافتراضي 6).

الدقة:

"resolution": "720p"
Enter fullscreen mode Exit fullscreen mode

"480p" و"720p" متاحان.

نسبة العرض إلى الارتفاع:

"aspect_ratio": "9:16"
Enter fullscreen mode Exit fullscreen mode
النسبة الأفضل لـ
16:9 سطح المكتب، يوتيوب (افتراضي)
9:16 تيك توك، ريلز، الجوال
1:1 إنستغرام، بطاقات اجتماعية
4:3 الفيديو الكلاسيكي، العروض التقديمية
3:4 محتوى الجوال العمودي
3:2 نسبة الصورة القياسية
2:3 التصوير الفوتوغرافي العمودي

مثال كامل:

curl -X POST https://api.x.ai/v1/videos/generations \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "بلدة ساحلية عند الفجر، أمواج تتكسر بلطف على شاطئ صخري",
    "duration": 10,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'
Enter fullscreen mode Exit fullscreen mode

استخدام الصور المرجعية لتوجيه نمط الفيديو

يمكنك تمرير حتى 7 صور مرجعية عبر reference_images لتوجيه النمط دون تغيير موضوع الفيديو:

{
  "model": "grok-imagine-video",
  "prompt": "بلدة ساحلية عند الفجر، أمواج تتكسر بلطف على شاطئ صخري",
  "reference_images": [
    {"url": "https://example.com/my-style-reference.jpg"},
    {"url": "https://example.com/color-palette-reference.jpg"}
  ]
}
Enter fullscreen mode Exit fullscreen mode

اختر صورًا متناسقة في الأسلوب للحصول على نتائج أفضل.

الفرق: الصور المرجعية تؤثر فقط على المظهر، أما نقطة نهاية تحويل الصورة إلى فيديو فتعتمد الصورة كمشهد رئيسي.

توسيع وتحرير مقاطع الفيديو المولّدة

xAI توفر نقطتي نهاية إضافيتين:

توسيع الفيديو:

POST /v1/videos/extensions

أضف لقطات جديدة إلى فيديو مولّد عبر request_id وموجه جديد.

تعديل الفيديو:

POST /v1/videos/edits

عدّل فيديو موجود عبر تعليمات نصية (مثلاً تغيير النمط أو المشهد).

كلتا النقطتين تعيدان request_id ويجب الاستطلاع بنفس طريقة التوليد.

قراءة التكلفة من رد واجهة برمجة التطبيقات

رد الاستطلاع يتضمن:

"usage": {
  "cost_in_usd_ticks": 500000000
}
Enter fullscreen mode Exit fullscreen mode

لتحويلها إلى دولار: اقسم على 10,000,000.

cost_in_usd = result["usage"]["cost_in_usd_ticks"] / 10_000_000
print(f"Cost: ${cost_in_usd:.4f}")
# Output: Cost: $0.0500
Enter fullscreen mode Exit fullscreen mode

مرجع التسعير:
| الدقة | السعر/ثانية | 10 ثوانٍ |
|---------|-------------|---------------|
| 480p | 0.05 دولار | 0.50 دولار |
| 720p | 0.07 دولار | 0.70 دولار |

سجّل قيمة cost_in_usd_ticks لكل رد مكتمل لتتبع التكاليف بسهولة.

كيف تختبر واجهة برمجة تطبيقات Grok Video باستخدام Apidog

الاستطلاع غير المتزامن يتطلّب من واجهتك الأمامية التعامل مع ثلاث حالات: التحميل، النجاح، الخطأ. اختبار ذلك باستدعاءات حقيقية مكلف وبطيء. هنا يأتي دور Smart Mock من Apidog.

لقطة شاشة لـ Apidog تعرض ميزة Smart Mock

حالة الاستخدام 1: Smart Mock لتطوير الواجهة الأمامية

استخدم Smart Mock من Apidog لتعريف مخطط نقطتي النهاية وتوليد ردود Mock واقعية.

  • محاكاة نقطة نهاية التوليد: أنشئ POST /v1/videos/generations وحدد الاستجابة مع حقل request_id. 
  {
    "request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"
  }
Enter fullscreen mode Exit fullscreen mode
  • محاكاة نقطة نهاية الاستطلاع: أنشئ GET /v1/videos/{request_id} وحدد الاستجابة مع الحقول الكاملة. 
  {
    "status": "done",
    "video": {
      "url": "https://vidgen.x.ai/mock-video-12345.mp4",
      "duration": 8,
      "respect_moderation": true
    },
    "progress": 100,
    "usage": {
      "cost_in_usd_ticks": 400000000
    }
  }
Enter fullscreen mode Exit fullscreen mode

يمكنك اختبار كل الحالات (تحميل/نجاح/فشل) دون استهلاك اعتمادات حقيقية.

حالة الاستخدام 2: سيناريوهات الاختبار لحلقة الاستطلاع

  • الخطوة 1: أضف طلب POST /v1/videos/generations ثم استخرج request_id كمتغير.
  • الخطوة 2: أضف طلب GET /v1/videos/{{videoRequestId}} داخل حلقة For تتوقف عند status == "done"، مع "انتظار" 5 ثوانٍ بين التكرارات.
  • الخطوة 3: بعد الحلقة، أضف تأكيدًا أن $.video.url ليس فارغًا.

استخدم هذه السيناريوهات في CI لضمان استقرار التكامل.

تحويل النص إلى فيديو مقابل تحويل الصورة إلى فيديو: متى تستخدم كل منهما

كلا الوضعين يستخدمان نموذج grok-imagine-video، لكن لأغراض مختلفة:

  • تحويل النص إلى فيديو:

    • عندما تريد محتوى أصلي من نص
    • لا تملك صورة مصدر
    • تحتاج سيطرة إبداعية كاملة للنموذج

  • تحويل الصورة إلى فيديو:

    • لديك صورة منتج/رسم وتريد تحريكه
    • تريد الحفاظ على تفاصيل محددة
    • تريد رسوم متحركة متناسقة من صورك

الفرق الأساسي: تحويل النص إلى فيديو يبدأ من الصفر، بينما تحويل الصورة إلى فيديو يعتمد على صورة واقعية.

لمزيد من التفاصيل، راجع دليل تحويل الصورة إلى فيديو.

الأخطاء الشائعة وكيفية إصلاحها

  • 401 Unauthorized: تحقق من صحة مفتاح API وصياغة Authorization header.
  • 429 Too Many Requests: أضف تأخير بين الاستدعاءات (5 ثوانٍ بين استطلاعات الفيديو).
  • status: "failed": غالبًا بسبب اعتدال المحتوى. عدّل الموجه ليكون أوضح أو أقل حساسية.
  • رابط الفيديو يعيد 404: روابط الفيديو مؤقتة. نزّل الفيديو فورًا بعد الاستطلاع.
  • فيديو فارغ أو متجمد: أضف أوصاف حركة واضحة في الموجه.
  • استطلاع بطيء: استخدم 480p ومدد قصيرة أثناء التطوير لتسريع التكرار.

الخاتمة

واجهة برمجة تطبيقات Grok لتحويل النص إلى فيديو تمنحك مسارًا واضحًا من الموجه النصي إلى ملف فيديو MP4. تعامل مع النمط غير المتزامن بشكل صحيح (حلقة الاستطلاع)، وستكون بقية المعلمات (المدة، الدقة، النسبة، الصور المرجعية) قابلة للتعديل حسب الحاجة.

للبناء الإنتاجي، أضف تتبع التكلفة عبر قراءة cost_in_usd_ticks. استخدم Apidog لمحاكاة نقاط النهاية أثناء التطوير حتى لا تضطر للانتظار أو استهلاك اعتمادات حقيقية. شغّل سيناريوهات الاختبار بانتظام لضمان استقرار عمل الاستطلاع.

الأسئلة الشائعة

ما اسم النموذج المستخدم لتوليد الفيديو من النص؟

grok-imagine-video في حقل model عند إرسال طلب POST إلى /v1/videos/generations.

كم يستغرق توليد الفيديو؟

حسب المدة والدقة: مقاطع قصيرة 480p قد تكتمل خلال 30 ثانية، أما 720p أو الفيديوهات الأطول تستغرق دقائق. استطلع كل 5-10 ثوانٍ.

هل يمكن توليد فيديو أطول من 15 ثانية؟

لا، الحد الأقصى هو 15 ثانية في الطلب الواحد. لتوليد فيديو أطول، استخدم POST /v1/videos/extensions.

كيف أقوم بتنزيل الفيديو المولّد؟

حمّل ملف MP4 من result.video.url فور حصولك عليه من رد الاستطلاع.

ماذا يحدث إذا تم رفض الموجه من اعتدال المحتوى؟

ستكون الحالة "failed" مع respect_moderation: true. عدّل الموجه وحاول مجددًا.

هل توجد طبقة مجانية؟

لا توجد طبقة مجانية للفيديو. تحقق من console.x.ai لعروض حسابات جديدة.

ما الفرق بين reference_images وصورة المصدر؟

الصور المرجعية تؤثر فقط على النمط البصري. صورة المصدر تستخدم في تحويل الصورة إلى فيديو وتصبح الإطار الرئيسي.

أفضل طريقة لاختبار حلقة الاستطلاع دون إنفاق اعتمادات؟

استعمل Smart Mock من Apidog لمحاكاة نقاط النهاية وتوليد حالات "processing" و"done" لاختبار الكود دون لمس API حقيقية.

Top comments (0)