الانتقال إلى المحتوى الرئيسي
توليد الفيديو غير متزامن. أرسل مهمة، احفظ queue_id، ثم استعلم عبر /video/retrieve حتى تكون الاستجابة video/mp4.

نقاط النهاية

الخطوة 1: إرسال طلب التوليد إلى الطابور

الطلب:
الاستجابة (200):
لنماذج Grok Imagine Private، تتضمن استجابة الطابور حقلًا إضافيًا download_url:
download_url هو رابط موقّع مسبقًا تستخدمه لتنزيل الفيديو المكتمل بدلًا من قراءته من استجابة retrieve. يُعاد مرة واحدة فقط في استجابة الطابور، فاحفظه إلى جانب queue_id. وهذا ينطبق على متغيّرات Grok Imagine Private الأربعة:
  • grok-imagine-text-to-video-private
  • grok-imagine-image-to-video-private
  • grok-imagine-reference-to-video-private
  • grok-imagine-video-to-video-private
بخلاف متغيّرات grok-imagine-*-video العامة، لا تُحاسَب نماذج Grok Imagine Private على رفضات اعتدال المحتوى، فلا تدفع إلا عن عمليات التوليد الناجحة. احفظ model وqueue_id وdownload_url (إن وُجد) لجميع الاستدعاءات اللاحقة.

روابط التنزيل الخاصة

بالنسبة للنماذج الخاصة، download_url هو الطريقة التي تجلب بها الملف المنتهي بمجرد اكتمال المهمة. الرابط قصير العمر وأحادي الغرض: وُجد لتسليم ملف MP4 إليك، لا ليكون رابطًا طويل المدى أو مشتركًا على نطاق واسع. إذا انقطع التنزيل، يمكنك إعادة المحاولة لنفس طلب GET عدة مرات من البيئة نفسها حتى يكتمل الملف. هذه المحاولات للتعافي من انقطاعات الشبكة—وليست للاستعلام عبر الرابط نفسه إلى ما لا نهاية، أو مشاركته مع عملاء كثر، أو تضمينه مثل عنوان وسائط دائم. مثل هذه الأنماط تظهر غالبًا كرموز 429 أو 410، وقد تكون مفاجئة إن توقعت أن يتصرف الرابط كاستضافة ملفات عادية. من أجل الموثوقية، يجب أن تنطلق طلبات GET من شبكة عميل واحدة. هناك بعض المرونة إذا تغيّر عنوان IP مرة (مثلًا إذا قطعت اتصال VPN وحاولت مجددًا)، لكن التباين الواسع في عناوين IP المصدر لن ينجح عادة. يبقى الرابط صالحًا حتى 24 ساعة، أو حتى تتم إزالة الكائن.
إذا احتجت إلى رابط ثابت أو تشغيل عام أو وصول متكرر مع مرور الوقت، احفظ الملف في التخزين الخاص بك أولًا وقدّمه من هناك.
الخصوصية: إبطال الرابط عبر DELETE عندما تنتهي من جلب الملف—أو إذا قررت عدم الاحتفاظ به—يمكنك استدعاء DELETE على نفس download_url. لا يلزم مفتاح Venice API لهذا الطلب. هذا اختياري لكنه موصى به عندما تكون الخصوصية مهمة، لأن بعض الوكلاء وصناديق الوسائط خارج Venice قد تحتفظ بسجلات للروابط الكاملة، وحذف الرابط هو أبسط طريقة لتضييق النافذة التي يوجد فيها الرابط الموقّع مسبقًا.
التدفق: استعلم عبر /video/retrieve حتى COMPLETED ← اطلب GET على download_url (مع إعادة محاولات خفيفة إذا انقطع النقل) ← احفظ الملف حيث تريد ← استدعِ DELETE على download_url إن أردت إبطال الرابط ← اختياريًا استدعِ /video/complete إذا كنت ما زلت تستخدم تنظيفًا قائمًا على الطابور.

الخطوة 2: الاستعلام عن الاكتمال

الطلب:
تعتمد الاستجابة على الحالة: استجابة قيد المعالجة (200، application/json):
الأوقات بالميلي ثانية. استخدم average_execution_time لتقدير الانتظار المتبقي. استجابة الاكتمال (200، video/mp4): جسم الاستجابة هو بيانات فيديو ثنائية خام. احفظها في ملف. استجابة الاكتمال (200، application/json بـ "COMPLETED"): بالنسبة للنماذج التي أعادت download_url وقت الإرسال للطابور، يُعيد retrieve دائمًا JSON. اجلب الفيديو بـ GET download_url (بلا رأس المصادقة). راجع روابط التنزيل الخاصة لمعرفة كيفية عمل هذه الروابط وإعادة المحاولات وDELETE الاختياري.

الخطوة 3: التنظيف (اختياري)

إما حذف تلقائي عند الاسترجاع:
أو استدعِ /video/complete بعد الحفظ:
الاستجابة (200):

مثال كامل


معاملات الطلب

طلب Queue

التحقق من صحة الطابور خاص بكل نموذج. تحقق من /models?type=video لمعرفة حقول الطلب المدعومة لكل نموذج قبل استدعاء /video/queue.

طلب Quote

طلب Retrieve

طلب Complete


من صورة إلى فيديو

لنماذج الصورة إلى فيديو، مرّر صورة المصدر عبر image_url. التعليمة تصف الحركة المرغوبة، وليس محتوى الصورة.
أو باستخدام base64:

عرض السعر

احصل على التكلفة الدقيقة قبل التوليد. أرسل فقط مدخلات التسعير (model وduration واختياريًا resolution وaspect_ratio وaudio): الطلب:
الاستجابة:
عرض السعر بالدولار الأمريكي.

الأخطاء


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

  1. استعلم عبر /video/retrieve على فترات (مثلًا كل 5 ثوانٍ)
  2. إذا كان Content-Type هو application/json وstatus هو "PROCESSING"، انتظر واستعلم مجددًا. استخدم average_execution_time وexecution_duration (بالميلي ثانية) لتقدير الوقت المتبقي
  3. إذا كان Content-Type هو video/mp4، احفظ جسم الاستجابة كملف الإخراج
  4. إذا كان Content-Type هو application/json وstatus هو "COMPLETED"، استدعِ GET على download_url من استجابة الطابور لجلب الفيديو (راجع روابط التنزيل الخاصة)
  5. إذا استخدمت download_url، فكّر في DELETE على ذلك الرابط عند الانتهاء لتضييق المدة التي يوجد فيها الرابط؛ ثم اختياريًا عيّن delete_media_on_completion: true على retrieve أو استدعِ /video/complete للتنظيف القائم على الطابور
  6. عالج 404 كوسائط غير صالحة أو منتهية أو محذوفة؛ وعالج 500/503 بإعادات محاولة وتأخير تصاعدي

النماذج المتاحة

راجع نماذج الفيديو للقائمة الحالية من النماذج والتسعير.