توليد الفيديو

ولِّد مقاطع فيديو من تعليمات نصية أو من صور بداية على 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
}

---

​

مثال كامل

Python

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})

const API_KEY = process.env.VENICE_API_KEY;
const BASE_URL = "https://api.venice.ai/api/v1";
const headers = {"Authorization": `Bearer ${API_KEY}`, "Content-Type": "application/json"};

// Queue
const queueResp = await fetch(`${BASE_URL}/video/queue`, {
    method: "POST", headers,
    body: JSON.stringify({
        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"
    })
});
const {model, queue_id, download_url} = await queueResp.json();

// Poll
while (true) {
    const resp = await fetch(`${BASE_URL}/video/retrieve`, {
        method: "POST", headers,
        body: JSON.stringify({model, queue_id})
    });
    if (resp.headers.get("Content-Type")?.includes("video/mp4")) {
        const fs = await import("fs");
        fs.writeFileSync("output.mp4", Buffer.from(await resp.arrayBuffer()));
        break;
    }
    const status = await resp.json();
    if (status.status === "COMPLETED" && download_url) {
        const fs = await import("fs");
        const video = await fetch(download_url);
        fs.writeFileSync("output.mp4", Buffer.from(await video.arrayBuffer()));
        break;
    }
    await new Promise(r => setTimeout(r, 5000));
}

// Cleanup
await fetch(`${BASE_URL}/video/complete`, {
    method: "POST", headers,
    body: JSON.stringify({model, 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
}

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

معاملات عرض السعر هي مدخلات تسعير فقط. الحقول التي ترسلها إلى /video/quote — بما في ذلك aspect_ratio وaudio وreference_video_total_duration — تُستخدم بحتًا لحساب السعر. لا تُمرَّر إلى /video/queue ولا تؤثر في الفيديو المولَّد. يُقبل إرسال aspect_ratio إلى quote حتى بالنسبة للنماذج (مثل seedance-2-0-image-to-video) التي ترفض aspect_ratio وقت التوليد، لأن نماذج الصورة إلى فيديو تشتق نسبة العرض إلى الارتفاع للإخراج من صورة الإدخال.

​

تسعير المرجع إلى فيديو

بالنسبة لنماذج R2V (مثل Seedance 2.0 R2V)، مرّر reference_video_total_duration — وهي المدة الإجمالية بالثواني لجميع المقاطع المرجعية التي تعتزم تضمينها — كي يعكس عرض السعر فئة سعر “إدخال مع فيديو” وصيغة الرموز (الإدخال + الإخراج) × البكسلات. إن أغفلته، فإن عرض السعر يعيد الحد الأساسي بلا مرجع بدلًا من ذلك.

reference_video_total_duration مُعترف به فقط بواسطة /video/quote. ليس له أي تأثير على /video/queue، وإغفاله لن يتسبب في خطأ توليد.

​

عرض أسعار ثابتة

عروض الأسعار لحظية وقد تتغير الأسعار. إن أردت عرض سعر ثابت في تطبيقك، فاستدعِ /video/quote مرة واحدة لكل مجموعة من المعاملات التي تدعمها واحفظ النتيجة في مخزنك الخاص — ثم أعد طلب عرض السعر وفق جدول زمني (أو عند تحديثات قائمة الأسعار) لتحديث القيمة المخزنة. لا توجد نقطة نهاية لعرض سعر “مقفل” أو “ثابت”.

---

​

الأخطاء

الحالة	تُعاد من	المعنى	الإجراء
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	النموذج عند حد طاقته	أعد المحاولة بتأخير تصاعدي

---

​

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

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

---

​

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

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