توليد الفيديو | وثائق Venice API

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

نقاط النهاية

نقطة النهاية	الغرض	مطلوب
`POST /video/quote`	الحصول على السعر بالدولار قبل التوليد	لا
`POST /video/queue`	إرسال طلب التوليد	نعم
`POST /video/retrieve`	الاستعلام عن الحالة أو تنزيل الفيديو	نعم
`POST /video/complete`	حذف الفيديو من التخزين	لا

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

الطلب:

POST https://api.venice.ai/api/v1/video/queue
Authorization: Bearer $VENICE_API_KEY
Content-Type: application/json

{
  "model": "wan-2.5-preview-text-to-video",
  "prompt": "A gondola gliding through Venice canals at sunset",
  "duration": "5s",
  "resolution": "720p",
  "aspect_ratio": "16:9"
}

الاستجابة (200):

{
  "model": "wan-2.5-preview-text-to-video",
  "queue_id": "123e4567-e89b-12d3-a456-426614174000"
}

لنماذج Grok Imagine Private، تتضمن استجابة الطابور حقلًا إضافيًا download_url:

{
  "model": "grok-imagine-text-to-video-private",
  "queue_id": "123e4567-e89b-12d3-a456-426614174000",
  "download_url": "https://private-share.venice.ai/v1/share/read/..."
}

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 قد تحتفظ بسجلات للروابط الكاملة، وحذف الرابط هو أبسط طريقة لتضييق النافذة التي يوجد فيها الرابط الموقّع مسبقًا.

curl -X DELETE "$DOWNLOAD_URL"

التدفق: استعلم عبر /video/retrieve حتى COMPLETED ← اطلب GET على download_url (مع إعادة محاولات خفيفة إذا انقطع النقل) ← احفظ الملف حيث تريد ← استدعِ DELETE على download_url إن أردت إبطال الرابط ← اختياريًا استدعِ /video/complete إذا كنت ما زلت تستخدم تنظيفًا قائمًا على الطابور.

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

الطلب:

POST https://api.venice.ai/api/v1/video/retrieve
Authorization: Bearer $VENICE_API_KEY
Content-Type: application/json

{
  "model": "wan-2.5-preview-text-to-video",
  "queue_id": "123e4567-e89b-12d3-a456-426614174000"
}

تعتمد الاستجابة على الحالة:

Content-Type	المعنى	الإجراء
`application/json`	لا يزال قيد المعالجة	انتظر 5 ثوانٍ، ثم استعلم مرة أخرى
`video/mp4`	مكتمل	جسم الاستجابة هو ملف الفيديو
`application/json` بـ `"COMPLETED"`	مكتمل، الفيديو ليس مضمّنًا	استدعِ `GET` على `download_url` من استجابة الطابور

استجابة قيد المعالجة (200، application/json):

{
  "status": "PROCESSING",
  "average_execution_time": 145000,
  "execution_duration": 53200
}

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

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

إما حذف تلقائي عند الاسترجاع:

{
  "model": "wan-2.5-preview-text-to-video",
  "queue_id": "123e4567-e89b-12d3-a456-426614174000",
  "delete_media_on_completion": true
}

أو استدعِ /video/complete بعد الحفظ:

POST https://api.venice.ai/api/v1/video/complete
Authorization: Bearer $VENICE_API_KEY
Content-Type: application/json

{
  "model": "wan-2.5-preview-text-to-video",
  "queue_id": "123e4567-e89b-12d3-a456-426614174000"
}

الاستجابة (200):

{
  "success": true
}

مثال كامل

import os
import time
import requests

API_KEY = os.environ.get("VENICE_API_KEY")
BASE_URL = "https://api.venice.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# Queue
resp = requests.post(f"{BASE_URL}/video/queue", headers=HEADERS, json={
    "model": "wan-2.5-preview-text-to-video",
    "prompt": "A gondola gliding through Venice canals at sunset",
    "duration": "5s",
    "resolution": "720p",
    "aspect_ratio": "16:9"
})
data = resp.json()
model, queue_id = data["model"], data["queue_id"]
download_url = data.get("download_url")

# Poll
while True:
    resp = requests.post(f"{BASE_URL}/video/retrieve", headers=HEADERS,
                         json={"model": model, "queue_id": queue_id})
    if "video/mp4" in resp.headers.get("Content-Type", ""):
        with open("output.mp4", "wb") as f:
            f.write(resp.content)
        break
    if resp.json().get("status") == "COMPLETED" and download_url:
        with open("output.mp4", "wb") as f:
            f.write(requests.get(download_url).content)
        break
    time.sleep(5)

# Cleanup
requests.post(f"{BASE_URL}/video/complete", headers=HEADERS,
              json={"model": model, "queue_id": queue_id})

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

طلب Queue

المعامل	النوع	مطلوب	الافتراضي	الوصف
`model`	string	نعم	-	معرّف النموذج. استخدم `wan-2.5-preview-text-to-video` للنص إلى فيديو، و`wan-2.5-preview-image-to-video` للصورة إلى فيديو
`prompt`	string	نعم	-	ما تريد توليده. حد أقصى 2500 حرف
`negative_prompt`	string	لا	`"low resolution, error, worst quality, low quality, defects"`	ما يجب تجنّبه
`duration`	string	نعم	-	`"5s"` أو `"10s"`
`resolution`	string	لا	`"720p"`	`"480p"` أو `"720p"` أو `"1080p"`
`aspect_ratio`	string	شرطي	-	يعتمد على النموذج. مطلوب للنماذج التي تكشف خيارات نسبة العرض إلى الارتفاع؛ احذفه للنماذج التي لا تدعم اختيار النسبة
`audio`	boolean	شرطي	`true` (حين يكون مدعومًا)	صالح فقط للنماذج ذات `supportsAudioConfig: true`؛ احذفه للنماذج التي لا تدعم إعداد الصوت
`image_url`	string	فقط للصورة إلى فيديو	-	رابط أو رابط بيانات base64 لصورة المصدر
`audio_url`	string	شرطي	-	رابط أو رابط بيانات base64 لصوت مرجعي للنماذج التي تدعم إدخال الصوت

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

طلب Quote

المعامل	النوع	مطلوب	الافتراضي	الوصف
`model`	string	نعم	-	معرّف النموذج للتسعير
`duration`	string	نعم	-	`"5s"` أو `"10s"`
`resolution`	string	لا	`"720p"`	`"480p"` أو `"720p"` أو `"1080p"`
`aspect_ratio`	string	شرطي	-	ضمّنه عندما يدعم النموذج المختار اختيار النسبة أو يتطلبه
`audio`	boolean	شرطي	`true` (حين يكون مدعومًا)	صالح فقط للنماذج ذات `supportsAudioConfig: true`

طلب Retrieve

المعامل	النوع	مطلوب	الافتراضي	الوصف
`model`	string	نعم	-	من استجابة الطابور
`queue_id`	string	نعم	-	من استجابة الطابور
`delete_media_on_completion`	boolean	لا	`false`	حذف الفيديو بعد الاسترجاع الناجح

طلب Complete

المعامل	النوع	مطلوب	الوصف
`model`	string	نعم	من استجابة الطابور
`queue_id`	string	نعم	من استجابة الطابور

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

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

{
  "model": "wan-2.5-preview-image-to-video",
  "prompt": "Camera slowly zooms in as leaves rustle in the wind",
  "image_url": "https://example.com/image.jpg",
  "duration": "5s"
}

أو باستخدام base64:

{
  "model": "wan-2.5-preview-image-to-video",
  "prompt": "Camera slowly zooms in as leaves rustle in the wind",
  "image_url": "data:image/jpeg;base64,/9j/4AAQ...",
  "duration": "5s"
}

عرض السعر

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

{
  "model": "wan-2.5-preview-text-to-video",
  "duration": "10s",
  "resolution": "1080p"
}

الاستجابة:

{
  "quote": 0.085
}

عرض السعر بالدولار الأمريكي.

الأخطاء

الحالة	تُعاد من	المعنى	الإجراء
400	`queue`، `quote`، `retrieve`، `complete`	معاملات غير صالحة	تحقّق من جسم الطلب مقابل المخطط
401	`queue`، `retrieve`، `complete`	فشل المصادقة	تحقّق من مفتاح API
402	`queue`	رصيد غير كافٍ	أضف رصيدًا
404	`retrieve`، `download_url`	الوسائط غير موجودة (غير صالحة أو منتهية أو محذوفة)	تحقّق من `model`/`queue_id` أو أعد الإرسال للطابور
410	`download_url`	رابط موقّع مسبقًا منتهي أو مستهلك كليًا أو مُبطل (مثلًا بعد `DELETE`)	ابدأ توليدًا جديدًا إن احتجت ملفًا آخر؛ كل رابط قصير العمر بشكل متعمّد
429	`download_url`	تجاوز حد المعدل—غالبًا من إعادة محاولات كثيرة أو جلب متكرّر للرابط نفسه	أكمل التنزيل (بضع إعادات لا بأس بها إذا انقطع الاتصال)، احفظ نسخة محلية، واستخدم `DELETE` إن أردت إخلاء الرابط؛ واحتفظ بالوصول المستمر على تخزينك الخاص
413	`queue`	حمولة كبيرة جدًا	قلّل حجم الصورة/الصوت
422	`queue`، `retrieve`	انتهاك للمحتوى	عدّل التعليمة
500	`queue`، `retrieve`، `complete`	فشل الاستدلال/المعالجة	أعد المحاولة بتأخير تصاعدي؛ تواصل مع الدعم إذا استمر
503	`retrieve`	النموذج عند حد طاقته	أعد المحاولة بتأخير تصاعدي

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

استعلم عبر /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 بإعادات محاولة وتأخير تصاعدي

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

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

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

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

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

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

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

​مثال كامل

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

​طلب Queue

​طلب Quote

​طلب Retrieve

​طلب Complete

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

​عرض السعر

​الأخطاء

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

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

نقاط النهاية

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

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

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

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

مثال كامل

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

طلب Queue

طلب Quote

طلب Retrieve

طلب Complete

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

عرض السعر

الأخطاء

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

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