> ## Documentation Index > Fetch the complete documentation index at: https://docs.venice.ai/llms.txt > Use this file to discover all available pages before exploring further. # توليد الفيديو > ولِّد مقاطع فيديو من تعليمات نصية أو من صور بداية على Venice API ذات الطابور غير المتزامن — أرسل مهمة، استعلم عن الحالة، ونزّل الفيديو المكتمل. توليد الفيديو غير متزامن. أرسل مهمة، احفظ `queue_id`، ثم استعلم عبر `/video/retrieve` حتى تكون الاستجابة `video/mp4`. ## نقاط النهاية | نقطة النهاية | الغرض | مطلوب | | ---------------------- | ------------------------------------- | ----- | | `POST /video/quote` | الحصول على السعر بالدولار قبل التوليد | لا | | `POST /video/queue` | إرسال طلب التوليد | نعم | | `POST /video/retrieve` | الاستعلام عن الحالة أو تنزيل الفيديو | نعم | | `POST /video/complete` | حذف الفيديو من التخزين | لا | ## الخطوة 1: إرسال طلب التوليد إلى الطابور **الطلب:** ```bash theme={"system"} 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):** ```json theme={"system"} { "model": "wan-2.5-preview-text-to-video", "queue_id": "123e4567-e89b-12d3-a456-426614174000" } ``` لنماذج Grok Imagine Private، تتضمن استجابة الطابور حقلًا إضافيًا `download_url`: ```json theme={"system"} { "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 قد تحتفظ بسجلات للروابط الكاملة، وحذف الرابط هو أبسط طريقة لتضييق النافذة التي يوجد فيها الرابط الموقّع مسبقًا. ```bash theme={"system"} curl -X DELETE "$DOWNLOAD_URL" ``` **التدفق:** استعلم عبر `/video/retrieve` حتى `COMPLETED` ← اطلب `GET` على `download_url` (مع إعادة محاولات خفيفة إذا انقطع النقل) ← احفظ الملف حيث تريد ← استدعِ `DELETE` على `download_url` إن أردت إبطال الرابط ← اختياريًا استدعِ `/video/complete` إذا كنت ما زلت تستخدم تنظيفًا قائمًا على الطابور. ## الخطوة 2: الاستعلام عن الاكتمال **الطلب:** ```bash theme={"system"} 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):** ```json theme={"system"} { "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` (بلا رأس المصادقة). راجع [روابط التنزيل الخاصة](#private-download-links) لمعرفة كيفية عمل هذه الروابط وإعادة المحاولات و`DELETE` الاختياري. ## الخطوة 3: التنظيف (اختياري) إما حذف تلقائي عند الاسترجاع: ```json theme={"system"} { "model": "wan-2.5-preview-text-to-video", "queue_id": "123e4567-e89b-12d3-a456-426614174000", "delete_media_on_completion": true } ``` أو استدعِ `/video/complete` بعد الحفظ: ```bash theme={"system"} 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):** ```json theme={"system"} { "success": true } ``` *** ## مثال كامل ```python Python theme={"system"} 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}) ``` ```javascript Node.js theme={"system"} 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`. التعليمة تصف الحركة المرغوبة، وليس محتوى الصورة. ```json theme={"system"} { "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: ```json theme={"system"} { "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`): **الطلب:** ```json theme={"system"} { "model": "wan-2.5-preview-text-to-video", "duration": "10s", "resolution": "1080p" } ``` **الاستجابة:** ```json theme={"system"} { "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` | النموذج عند حد طاقته | أعد المحاولة بتأخير تصاعدي | *** ## استراتيجية الاستعلام 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` من استجابة الطابور لجلب الفيديو (راجع [روابط التنزيل الخاصة](#private-download-links)) 5. إذا استخدمت `download_url`، فكّر في `DELETE` على ذلك الرابط عند الانتهاء لتضييق المدة التي يوجد فيها الرابط؛ ثم اختياريًا عيّن `delete_media_on_completion: true` على retrieve أو استدعِ `/video/complete` للتنظيف القائم على الطابور 6. عالج `404` كوسائط غير صالحة أو منتهية أو محذوفة؛ وعالج `500/503` بإعادات محاولة وتأخير تصاعدي *** ## النماذج المتاحة راجع [نماذج الفيديو](/models/video) للقائمة الحالية من النماذج والتسعير.