queue_id، ثم استعلم عبر /video/retrieve حتى تكون الاستجابة video/mp4.
نقاط النهاية
الخطوة 1: إرسال طلب التوليد إلى الطابور
الطلب:download_url:
download_url هو رابط موقّع مسبقًا تستخدمه لتنزيل الفيديو المكتمل بدلًا من قراءته من استجابة retrieve. يُعاد مرة واحدة فقط في استجابة الطابور، فاحفظه إلى جانب queue_id. وهذا ينطبق على متغيّرات Grok Imagine Private الأربعة:
grok-imagine-text-to-video-privategrok-imagine-image-to-video-privategrok-imagine-reference-to-video-privategrok-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 بعد الحفظ:
مثال كامل
معاملات الطلب
طلب Queue
التحقق من صحة الطابور خاص بكل نموذج. تحقق من
/models?type=video لمعرفة حقول الطلب المدعومة لكل نموذج قبل استدعاء /video/queue.
طلب Quote
طلب Retrieve
طلب Complete
من صورة إلى فيديو
لنماذج الصورة إلى فيديو، مرّر صورة المصدر عبرimage_url. التعليمة تصف الحركة المرغوبة، وليس محتوى الصورة.
عرض السعر
احصل على التكلفة الدقيقة قبل التوليد. أرسل فقط مدخلات التسعير (model وduration واختياريًا resolution وaspect_ratio وaudio):
الطلب:
الأخطاء
استراتيجية الاستعلام
- استعلم عبر
/video/retrieveعلى فترات (مثلًا كل 5 ثوانٍ) - إذا كان
Content-Typeهوapplication/jsonوstatusهو"PROCESSING"، انتظر واستعلم مجددًا. استخدمaverage_execution_timeوexecution_duration(بالميلي ثانية) لتقدير الوقت المتبقي - إذا كان
Content-Typeهوvideo/mp4، احفظ جسم الاستجابة كملف الإخراج - إذا كان
Content-Typeهوapplication/jsonوstatusهو"COMPLETED"، استدعِGETعلىdownload_urlمن استجابة الطابور لجلب الفيديو (راجع روابط التنزيل الخاصة) - إذا استخدمت
download_url، فكّر فيDELETEعلى ذلك الرابط عند الانتهاء لتضييق المدة التي يوجد فيها الرابط؛ ثم اختياريًا عيّنdelete_media_on_completion: trueعلى retrieve أو استدعِ/video/completeللتنظيف القائم على الطابور - عالج
404كوسائط غير صالحة أو منتهية أو محذوفة؛ وعالج500/503بإعادات محاولة وتأخير تصاعدي