API

Wan 3.0 API

فيديو

تنشئ واجهة Wan 3.0 API فيديوهات مدتها 2–30 ثانية بدقة 480p / 720p / 1080p من النص أو الإطارات أو المراجع متعددة الوسائط. يقبل وضع المراجع حتى 10 صورة و5 فيديو و5 ملف صوت. يجب ألا يتجاوز حجم كل صورة 30 ميغابايت.

التفويضات

Bearerstringheaderمطلوب

مفتاح API لتفويض الطلبات

النص

application/json

modelstringمطلوب

wan-3-0

input.promptstringمطلوب

صِف العنصر والحركة والمشهد والإضاءة وحركة الكاميرا والتوقيت. تُحذف المسافات في البداية والنهاية.

input.frames_imagesstring[]اختياري

قائمة من رابط أو رابطين لصور HTTPS عامة: إطار البداية ثم إطار النهاية الاختياري. هذا الوضع لا يجتمع مع reference_images أو reference_videos أو reference_audios.

الحد الأقصى للروابط: 2.

الحجم الأقصى لكل صورة: 30 ميغابايت.

مثال: ["https://example.com/first-frame.png","https://example.com/last-frame.png"]

input.reference_imagesstring[]اختياري

قائمة روابط HTTPS عامة لصور مرجعية. يمكن جمعها مع reference_videos وreference_audios، لكن ليس frames_images. أرسل نصوص روابط، لا ملفات أو base64.

الحد الأقصى للروابط: 10.

الحجم الأقصى لكل صورة: 30 ميغابايت.

مثال: ["https://example.com/your-image.png"]

input.reference_videosstring[]اختياري

قائمة روابط HTTPS عامة لفيديوهات مرجعية. لا تجمعها مع frames_images. تغيّر الفيديوهات استهلاك الرصيد؛ راجع صف التسعير والمعادلة أدناه.

الحد الأقصى للروابط: 5.

مثال: ["https://example.com/your-video.mp4"]

input.reference_audiosstring[]اختياري

قائمة روابط HTTPS عامة لصوت مرجعي. يمكن جمعها مع قوائم reference_* الأخرى، لكن ليس frames_images.

الحد الأقصى للروابط: 5.

مثال: ["https://example.com/your-audio.mp3"]

input.reference_video_durationnumberاختياري

المدة الإجمالية لكل الفيديوهات المرجعية بالثواني. مطلوبة مع reference_videos. تُقرب المدة للأعلى إلى ثانية كاملة ويُحتسب حد أقصى قدره 15 ثانية إضافية. احذفها عند عدم إرسال فيديوهات مرجعية.

input.durationintegerاختياري

مدة الفيديو بعدد صحيح من الثواني بين 2 و30. القيمة الافتراضية 5. يتناسب استهلاك الرصيد مع المدة.

الافتراضي: 5

2–30

input.resolutionstringاختياري

دقة الفيديو الناتج. استخدم إحدى القيم بالأحرف الصغيرة أدناه. تتغير تكلفة الرصيد بحسب الدقة.

الافتراضي: 720p

480p720p1080p

input.aspect_ratiostringاختياري

نسبة العرض إلى الارتفاع. الافتراضي 16:9. قد توجّه الإطارات تكوين المشهد النهائي.

الافتراضي: 16:9

16:99:161:13:44:3

input.soundbooleanاختياري

تحديد ما إذا كان سيُولد صوت مع الفيديو. الافتراضي false. أرسل قيمة JSON منطقية، وليس سلسلة نصية.

الافتراضي: false

أمثلة الطلبات

اختر وضعًا واحدًا: احذف الوسائط للتوليد من النص؛ استخدم frames_images لإطاري البداية والنهاية؛ أو اجمع reference_images وreference_videos وreference_audios للتوليد بالمراجع. لا يمكن جمع frames_images مع أي قائمة وسائط reference_*. جميع الموارد قوائم روابط HTTPS عامة، وليست ملفات أو base64. استبدل روابط example.com. احفظ data.task_id واستعلم عبر POST /api/v1/check حتى completed أو failed.

POST /api/v1/create

curl -X POST https://nanobanana.io/api/v1/create \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "wan-3-0",
  "input": {
    "prompt": "سيارة كلاسيكية حمراء تسير على طريق ساحلي عند الغروب. تتبع الكاميرا جانب السيارة بسلاسة بينما ينعكس الضوء الدافئ على المحيط.",
    "duration": 5,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "sound": false
  }
}'

POST /api/v1/create · HTTP 201

{
  "data": {
    "task_id": "task_example",
    "model": "wan-3-0",
    "status": "processing",
    "credits": 600
  }
}

استعلم عن نقطة النهاية هذه باستخدام معرّف المهمة المُعاد حتى تكتمل المهمة أو تفشل. نوصي بالاستعلام كل 5 ثوانٍ للتحقق من أحدث حالة للمهمة.

POST /api/v1/check

{
  "task_id": "task_example"
}

الاستجابة

حالة المهمة التي يعيدها POST /api/v1/check. المعرّفات والروابط والطوابع الزمنية التالية أمثلة توضيحية.

idstringمطلوب

معرّف المهمة في data.id يطابق task_id المُرسل في طلب الاستعلام.

statusstringمطلوب

تعني completed نجاح الإنشاء وتحتوي data.data على النتائج. تكون data.data بقيمة null في الحالات الأخرى.

failed_reasonstringاختياري

يُعاد فقط عندما تكون status بقيمة failed لشرح سبب الفشل. لا يظهر هذا الحقل في completed أو processing.

مكتملة · completed

روابط التنزيل موجودة في data.data.results.

POST /api/v1/check · HTTP 200

{
  "data": {
    "id": "task_example",
    "created_at": 1791244800,
    "model": "wan-3-0",
    "status": "completed",
    "data": {
      "results": [
        "https://example.com/generated.mp4"
      ],
      "processing_time": 120
    }
  }
}

الحالات الأخرى

تكون data.data بقيمة null في processing أو failed. يوضح هذا المثال failed: تظهر failed_reason في failed فقط. تابع الاستعلام في processing وأوقفه في failed.

POST /api/v1/check · HTTP 200

{
  "data": {
    "id": "task_example",
    "created_at": 1791244800,
    "model": "wan-3-0",
    "status": "failed",
    "data": null,
    "failed_reason": "Generation failed."
  }
}

استهلاك النقاط

الرصيد لكل ثانية قابلة للفوترة بحسب الدقة ووضع الفيديو المرجعي.

الرصيد لكل ثانية قابلة للفوترة بحسب الدقة ووضع الفيديو المرجعي.
التوليد	480P	720P	1080P
بدون فيديوهات مرجعية	60	120	240
مع فيديوهات مرجعية	60	120	240

ينشئ كل طلب فيديو واحدًا. عند حذف المدة أو الدقة تُستخدم القيم الافتراضية أعلاه. قد تزيد الفيديوهات المرجعية استهلاك الرصيد؛ استخدم الصف والمعادلة المناسبين.

بدون فيديو مرجعي: الثواني المُولدة × السعر. مع فيديو مرجعي: (الثواني المُولدة + min(15, ceil(reference_video_duration))) × السعر. لا يتغير سعر الثانية؛ تضيف مدة المرجع ثواني قابلة للفوترة.

يوضح حقل credits في استجابة POST /api/v1/create عدد النقاط المخصومة للمهمة.