DEV Community

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

Posted on • Originally published at apidog.com

كيفية استخدام Grok API لتحويل الصور إلى فيديو: دليل خطوة بخطوة

موجز لأهم النقاط

يستخدم نموذج grok-imagine-video من xAI واجهة برمجة تطبيقات Grok لتحويل صورة ثابتة إلى فيديو متحرك. ترسل (POST) عنوان URL لصورتك، مع طلب (prompt) اختياري وإعدادات أخرى إلى https://api.x.ai/v1/videos/generations. ستستقبل على الفور request_id. بعد ذلك، تستعلم (poll) من GET /v1/videos/{request_id} حتى يصبح status "done". تستغرق العملية عادة من 1 إلى 15 ثانية. الأسعار تبدأ من 0.05 دولار أمريكي للثانية بدقة 480p.

جرّب Apidog اليوم

مقدمة

في 28 يناير 2026، وفرت xAI نموذج grok-imagine-video للعامة عبر API. خلال الشهر الأول فقط، أنشأ النموذج 1.2 مليار فيديو وتصدر قائمة تحويل النص إلى فيديو من Artificial Analysis. ميزة تحويل الصورة إلى فيديو تتيح لك إرسال صورة مع طلب وصفي، ويقوم API بتحريك الصورة وإرجاع مقطع MP4 جاهز للتحميل.

هذه العملية غير المتزامنة تتطلب إرسال مهمة ثم الاستعلام عنها حتى الاكتمال. لا يكتمل التكامل بمجرد تلقي 200 OK من POST؛ بل يجب التأكد من أن حلقة الاستعلام تتعامل مع حالات "processing" و"done" و"failed" بشكل صحيح في بيئة الشبكة الفعلية.

سيناريوهات اختبار Apidog تعالج ذلك مباشرة: أبنِ تسلسلًا يرسل POST إلى /v1/videos/generations، يستخرج request_id، ويكرر الاستعلام حتى status == "done"، ثم يتحقق من وجود عنوان URL للفيديو.

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

واجهة Grok API جزء من منتج xAI لتوليد الفيديو، وتعمل ضمن نموذج grok-imagine-video. تقبل صورة كإطار بداية للفيديو الناتج، وتدرس محتوى الصورة والطلب النصي لتوليد حركة طبيعية للمشهد.

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

POST https://api.x.ai/v1/videos/generations
Enter fullscreen mode Exit fullscreen mode

المصادقة عبر Bearer Token:

Authorization: Bearer YOUR_XAI_API_KEY
Enter fullscreen mode Exit fullscreen mode

يمكنك الحصول على المفتاح من وحدة تحكم xAI. نفس الواجهة تدعم أيضًا تحويل النص إلى فيديو، تمديد الفيديو، وتعديلات الفيديو.

كيف تعمل عملية تحويل الصورة إلى فيديو

معلمة image في الطلب تشير إلى الإطار الأول للفيديو الناتج. يبدأ النموذج من هذه الصورة، ويتنبأ بالحركة بناءً على الطلب النصي.

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

متى تختار تحويل الصورة إلى فيديو؟

  • لديك صور منتجات أو مناظر أو صور شخصية وتريد تحريكها.
  • تريد الحفاظ على هوية بصرية متسقة في الإطار الأول.
  • تحتاج أن تبدو الحركة من مشهد حقيقي أو محدد.

متى تختار تحويل النص إلى فيديو؟

  • لا تملك صورة مرجعية وتبحث عن أفكار بصرية جديدة.
  • تريد للنموذج أن يحدد تكوين المشهد بالكامل.
  • سرعة التكرار أهم من دقة الإطار الأول.

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

قبل تنفيذ أول طلب:

  1. حساب xAI على console.x.ai
  2. مفتاح API من وحدة تحكم xAI. احفظه في متغير بيئة.
  3. Python 3.8+ أو Node.js 18+ (الأمثلة هنا تستخدم كلاهما).
  4. عنوان URL لصورة عامة، أو صورة مشفرة base64 كـ Data URI.

صورة توضيحية للمتطلبات الأساسية

تعيين المفتاح في البيئة:

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

تثبيت xAI Python SDK (اختياري):

pip install xai-sdk
Enter fullscreen mode Exit fullscreen mode

للطلبات الخام: استخدم فقط مكتبة requests (Python) أو fetch (Node.js).

إجراء أول طلب لتحويل الصورة إلى فيديو

باستخدام 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": "Gentle waves move across the surface, morning mist rises slowly",
    "image": {
      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/1/1a/24701-nature-natural-beauty.jpg/1280px-24701-nature-natural-beauty.jpg"
    },
    "duration": 6,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'
Enter fullscreen mode Exit fullscreen mode

الاستجابة:

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

الفيديو يُولّد بشكل غير متزامن. استعلم عن النتيجة كما يلي.

باستخدام بايثون (طلبات خام) 

import os
import requests

api_key = os.environ["XAI_API_KEY"]

payload = {
    "model": "grok-imagine-video",
    "prompt": "Gentle waves move across the surface, morning mist rises slowly",
    "image": {
        "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/1/1a/24701-nature-natural-beauty.jpg/1280px-24701-nature-natural-beauty.jpg"
    },
    "duration": 6,
    "resolution": "720p",
    "aspect_ratio": "16:9"
}

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

response = requests.post(
    "https://api.x.ai/v1/videos/generations",
    json=payload,
    headers=headers
)

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

باستخدام صورة base64

إذا كانت الصورة محلية أو غير متاحة للعامة:

import base64

with open("my_image.jpg", "rb") as f:
    encoded = base64.b64encode(f.read()).decode("utf-8")

payload["image"] = {
    "url": f"data:image/jpeg;base64,{encoded}"
}
Enter fullscreen mode Exit fullscreen mode

الاستعلام عن النتيجة

توليد الفيديو غير متزامن. بعد استقبال request_id، استعلم من نقطة النهاية التالية:

GET https://api.x.ai/v1/videos/{request_id}
Enter fullscreen mode Exit fullscreen mode

قيم الحالة المحتملة:

الحالة المعنى
"processing" جاري عرض الفيديو
"done" الفيديو جاهز والرابط متوفر
"failed" حدث خطأ

مثال على رد مكتمل:

{
  "status": "done",
  "video": {
    "url": "https://vidgen.x.ai/....mp4",
    "duration": 6
  },
  "progress": 100
}
Enter fullscreen mode Exit fullscreen mode

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

import time

def poll_video(request_id: str, api_key: str, interval: int = 5) -> dict:
    url = f"https://api.x.ai/v1/videos/{request_id}"
    headers = {"Authorization": f"Bearer {api_key}"}

    while True:
        response = requests.get(url, headers=headers)
        data = response.json()
        status = data.get("status")

        print(f"Status: {status} | Progress: {data.get('progress', 0)}%")

        if status == "done":
            return data["video"]
        elif status == "failed":
            raise RuntimeError(f"Video generation failed for {request_id}")

        time.sleep(interval)

# الاستخدام
video = poll_video(request_id, api_key)
print(f"Video URL: {video['url']}")
print(f"Duration: {video['duration']}s")
Enter fullscreen mode Exit fullscreen mode

يفضل أن تكون فترة الاستعلام 5 ثوانٍ أو أكثر بسبب حد المعدل (60 طلب/دقيقة).

استخدام حزمة xAI Python SDK

مكتبة xai-sdk تغلف النمط غير المتزامن تلقائياً:

from xai_sdk import Client
import os

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

video = client.video.generate(
    model="grok-imagine-video",
    prompt="Gentle waves move across the surface, morning mist rises slowly",
    image={"url": "https://example.com/landscape.jpg"},
    duration=6,
    resolution="720p",
    aspect_ratio="16:9"
)

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

تتعامل الحزمة مع الاستعلامات والأخطاء تلقائيًا. استخدم الطلبات الخام إذا أردت التحكم الكامل في الاستعلام وإعادة المحاولة والتسجيل.

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

المدة

معلمة duration تقبل أرقام صحيحة بين 1 و15 ثانية (الافتراضي 6):

"duration": 10
Enter fullscreen mode Exit fullscreen mode

كلما طال الفيديو، زادت التكلفة.

الدقة

القيمة الوصف
"480p" افتراضي، تكلفة منخفضة
"720p" جودة أعلى، تكلفة أعلى 
"resolution": "720p"
Enter fullscreen mode Exit fullscreen mode

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

القيمة الاستخدام
"16:9" افتراضي، شاشة عريضة
"9:16" عمودي للموبايل أو القصص
"1:1" مربع
"4:3" كلاسيكي أو عروض تقديمية
"3:4" تصوير بورتريه
"3:2" قص تصوير فوتوغرافي
"2:3" بورتريه طولي

إذا قدمت معلمة image، يتم تعيين الأبعاد افتراضيًا لأبعاد الصورة المصدر. اضبطها يدويًا للتجاوز أو القص.

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

  • image: الإطار الأول للفيديو.
  • reference_images: مصفوفة صور (حتى 7) توجه النمط أو الإضاءة أو المعالجة الأسلوبية، لكنها ليست جزءًا من الإخراج.

مثال:

{
  "model": "grok-imagine-video",
  "prompt": "A product rotating slowly on a clean white surface",
  "image": {
    "url": "https://example.com/product-shot.jpg"
  },
  "reference_images": [
    {"url": "https://example.com/brand-style-reference-1.jpg"},
    {"url": "https://example.com/lighting-reference.jpg"}
  ],
  "duration": 6,
  "resolution": "720p"
}
Enter fullscreen mode Exit fullscreen mode

يمكنك استخدام الصور المرجعية بدون صورة إطار أول، فيتحول الطلب إلى نص إلى فيديو بنمط مستوحى من المرجع.

توسيع وتعديل مقاطع الفيديو

واجهة API تدعم عمليتين إضافيتين:

توسيع مقطع فيديو

POST /v1/videos/extensions يولد ثوانٍ إضافية من فيديو سابق:

curl -X POST https://api.x.ai/v1/videos/extensions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "video_id": "your_original_request_id",
    "prompt": "The mist continues to lift as sunlight breaks through",
    "duration": 5
  }'
Enter fullscreen mode Exit fullscreen mode

يتم الاستعلام بنفس النمط غير المتزامن.

تعديل مقطع فيديو

POST /v1/videos/edits لتعديلات موجهة بالطلب على فيديو سابق:

curl -X POST https://api.x.ai/v1/videos/edits \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "video_id": "your_original_request_id",
    "prompt": "Change the sky to a dramatic sunset with deep orange tones"
  }'
Enter fullscreen mode Exit fullscreen mode

التوسيعات والتعديلات كلاهما غير متزامنين ويتطلبان الاستعلام حتى الاكتمال.

تفصيل الأسعار: تكلفة فيديو مدته 10 ثوانٍ

تسعير Grok للفيديو يشمل:

المكون التكلفة
صورة الإدخال 0.002 دولار لكل صورة
إخراج 480p 0.05 دولار/ثانية
إخراج 720p 0.07 دولار/ثانية

مثال فيديو 10 ثوانٍ بدقة 720p:

  • صورة الإدخال: 0.002 دولار
  • الإخراج: 10 × 0.07 = 0.70 دولار
  • الإجمالي: 0.702 دولار

مثال فيديو 6 ثوانٍ بدقة 480p:

  • صورة الإدخال: 0.002 دولار
  • الإخراج: 6 × 0.05 = 0.30 دولار
  • الإجمالي: 0.302 دولار

تُفرض رسوم صورة الإدخال في كل طلب حتى لو أعدت استخدام نفس الصورة. تحويل النص إلى فيديو يلغي رسوم الإدخال فقط.

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

لضمان تكامل موثوق، يجب اختبار السيناريو الكامل، وليس فقط طلب واحد:

  1. تحقق أن طلب التوليد يرجع request_id.
  2. تحقق أن الاستعلام يتعامل مع "processing" بشكل صحيح.
  3. تحقق أن الرد النهائي فيه status == "done" وvideo.url غير فارغ.

خطوات بناء السيناريو في Apidog:

1. أنشئ سيناريو اختبار جديد

  • في Apidog، افتح الوحدة الخاصة بالاختبارات وأنشئ سيناريو جديد باسم "Grok image-to-video async flow".

2. أضف خطوة طلب التوليد

  • POST إلى https://api.x.ai/v1/videos/generations
  • رأس: Authorization: Bearer {{xai_api_key}}
  • JSON في النص: 
{
  "model": "grok-imagine-video",
  "prompt": "Gentle mist rises from the water as light filters through the trees",
  "image": {
    "url": "https://example.com/your-test-image.jpg"
  },
  "duration": 6,
  "resolution": "480p"
}
Enter fullscreen mode Exit fullscreen mode

3. استخراج request_id

  • أضف معالج "Extract Variable":
    • اسم المتغير: video_request_id
    • المصدر: نص الاستجابة
    • JSONPath: $.request_id

4. بناء حلقة الاستعلام

  • أضف معالج "For" مع طلب GET إلى https://api.x.ai/v1/videos/{{video_request_id}}
  • استخرج video_status من $.status
  • أضف معالج "Wait" (5000 مللي ثانية) بعد كل استعلام
  • شرط الخروج: {{video_status}} == "done"

5. التأكد من عنوان URL للفيديو

  • بعد الحلقة، أضف خطوة GET أخرى لنفس النهاية، ثم معالج "Assertion":
    • الحقل: $.video.url
    • الشرط: ليس فارغًا

تشغيل السيناريو

  • انقر "تشغيل" في Apidog. ستنفذ الخطوات تلقائيًا مع تقرير مفصل. يمكن ربط السيناريو بخط CI/CD: 
apidog run --scenario grok-video-async-flow --env production
Enter fullscreen mode Exit fullscreen mode

الأخطاء الشائعة والحلول

401 غير مصرح به

راجع صيغة رأس Authorization وتأكد من صحة المفتاح.

422 كيان غير قابل للمعالجة

حقل ناقص أو مشوه في الطلب. تحقق من وجود جميع الحقول، وصحة عنوان URL للصورة.

عنوان URL للصورة غير متاح

يجب أن يكون متاحًا للعامة. استخدم CDN أو base64 إذا كان خاصًا.

الحالة "processing" لا تنتهي

قد يكون الطلب توقف. إذا استمر لأكثر من 10 دقائق، أعد المحاولة.

أخطاء حد المعدل (429)

تأكد من وجود 1 ثانية على الأقل بين كل استعلام.

رفض تحميل Base64

تأكد من صحة بادئة نوع MIME مثل data:image/jpeg;base64,.

عدم تطابق نسبة العرض إلى الارتفاع

إذا اختلفت كثيرًا عن أبعاد الصورة الأصلية قد يحدث قص/تسطير.

الخاتمة

واجهة Grok لتحويل الصورة إلى فيديو تتيح لك الانتقال من صورة ثابتة إلى فيديو متحرك عبر API مباشرة. أطلق نموذج grok-imagine-video مليارات الفيديوهات في أول شهر من طرحه. لضمان تكامل موثوق، نفذ اختبارات تغطي حلقة الاستعلام، استخراج المتغيرات، وتأكيد عنوان URL النهائي باستخدام سيناريوهات Apidog.

ابدأ ببناء تكاملك مع Apidog مجانًا. لا يتطلب بطاقة ائتمان.

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

ما اسم النموذج؟

grok-imagine-video مرّرها في حقل model في POST.

ما الفرق بين image وreference_images؟

image: الإطار الأول للفيديو.

reference_images: صور توجه النمط فقط.

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

6 ثواني بدقة 480p: عادة 1-3 دقائق.

15 ثانية 720p: حتى 8 دقائق. الاستعلام كل 5 ثوانٍ يكفي.

هل يمكن استخدام صورة محلية؟

نعم. شفرها base64 بصيغة data:image/jpeg;base64,....

ماذا لو لم أحدد aspect_ratio؟

إذا أرسلت صورة، يتم اعتماد أبعادها. بدونه الافتراضي 16:9.

تكلفة فيديو 10 ثواني 720p؟

0.002 دولار للصورة + 0.70 دولار للإخراج = 0.702 دولار.

ما هي حدود المعدل؟

60 طلب/دقيقة و1 طلب/ثانية (POST وGET معًا).

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

نعم، عبر POST /v1/videos/extensions لتمديد الفيديو على دفعات متتالية.

Top comments (0)