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

📝 مقدّمة

توليد الفيديو عملية غير متزامنة: أرسل مهمة، واستلم معرّف مهمة، ثم استعلم دوريًا عن النتيجة.

العائلة	النماذج	نقطة إنشاء المهمة
Google Veo	veo-3.1-generate-preview وveo-3.1-fast-generate-preview وveo-3.0-generate-001 وveo-3.0-fast-generate-001	POST /v1/video/generations
Vidu	viduq3-pro وviduq3-turbo وviduq3-fast	POST /v1/video/generations
HappyHorse	happyhorse-1.0-t2v	POST /v1/video/generations
Kling	kling-v3 وkling-v2-6 وkling-v2-5-turbo	‏POST /kling/v1/videos/text2video وPOST /kling/v1/videos/image2video

المصادقة

Authorization: Bearer $WS_API_KEY

الصيغة الموحّدة (/v1/video/generations)

إنشاء مهمة توليد فيديو ✅

تدعم تحويل النص إلى فيديو والصورة إلى فيديو.

curl -X POST "http://baseurl/v1/video/generations" \
  -H "Authorization: Bearer $WS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-preview",
    "prompt": "A drone shot flying over a coastal city at golden hour, cinematic",
    "metadata": {
      "resolution": "720p",
      "ratio": "16:9",
      "duration": 8,
      "generate_audio": true
    }
  }'

لتحويل صورة إلى فيديو، أضف الحقل images:

{
  "model": "viduq3-pro",
  "prompt": "The camera slowly zooms in while leaves fall",
  "images": ["https://example.com/first-frame.jpg"]
}

الاستجابة — معرّف مهمة:

{"task_id": "task_id"}

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

المعامل	النوع	مطلوب	الوصف
model	string	نعم	معرّف نموذج الفيديو، انظر الجدول أعلاه
prompt	string	نعم	وصف نصي للفيديو المطلوب
images	array	لا	صورة/صور مرجعية (رابط أو base64) لتحويل الصورة إلى فيديو
metadata.resolution	string	لا	مثل 480p أو 720p أو 1080p (حسب النموذج)
metadata.ratio	string	لا	نسبة العرض إلى الارتفاع، مثل 16:9 أو 9:16
metadata.duration	integer	لا	مدة الفيديو بالثواني (حسب النموذج)
metadata.generate_audio	boolean	لا	توليد الصوت (للنماذج الداعمة)

الاستعلام عن حالة المهمة ✅

curl http://baseurl/v1/video/generations/task_id \
  -H "Authorization: Bearer $WS_API_KEY"

مثال على الاستجابة:

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_id",
    "action": "generate",
    "status": "SUCCESS",
    "fail_reason": "",
    "submit_time": 1775188030,
    "start_time": 1775188043,
    "finish_time": 1775188329,
    "progress": "100%",
    "data": {
      "id": "task_id",
      "status": "succeed",
      "duration": 8,
      "resolution": "720p",
      "result": {
        "content": {
          "video_url": "video download URL"
        }
      }
    }
  }
}

قيم حالة المهمة:

• ‏queued: في قائمة الانتظار
• ‏in_progress: قيد التنفيذ
• ‏completed: مكتملة
• ‏failed: فاشلة

نزّل الملف فورًا

روابط الفيديو المولّدة مؤقتة. نزّل الفيديو وخزّنه لديك فور اكتمال المهمة.

صيغة Kling

نص إلى فيديو — إنشاء مهمة ✅

curl -X POST "http://baseurl/kling/v1/videos/text2video" \
  -H "Authorization: Bearer $WS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "prompt": "A cat playing piano in the garden",
    "negative_prompt": "blurry, low quality",
    "cfg_scale": 0.7,
    "mode": "pro",
    "aspect_ratio": "16:9",
    "duration": "4",
    "metadata": {
      "sound": "on"
    }
  }'

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

المعامل	النوع	مطلوب	الوصف
model	string	نعم	‏kling-v3 أو kling-v2-6 أو kling-v2-5-turbo
prompt	string	نعم	موجّه إيجابي يصف محتوى الفيديو المطلوب
negative_prompt	string	لا	موجّه سلبي يصف المحتوى المراد تجنّبه
cfg_scale	float	لا	درجة الالتزام بالموجّه، النطاق 0–1؛ القيم الأعلى تلتزم بالموجّه أكثر
mode	string	لا	‏std (قياسي) أو pro (جودة عالية)
aspect_ratio	string	لا	‏16:9 أو 9:16 أو 1:1
duration	string	لا	مدة الفيديو بالثواني، مثل 4 أو 5 أو 10
metadata.sound	string	لا	‏on لتوليد الصوت، off لتعطيله

مثال على الاستجابة:

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "request_id",
  "data": {
    "task_id": "task_id",
    "task_status": "submitted",
    "created_at": 1775188030000,
    "updated_at": 1775188030000
  }
}

نص إلى فيديو — الاستعلام عن المهمة ✅

curl "http://baseurl/kling/v1/videos/text2video/task_id" \
  -H "Authorization: Bearer $WS_API_KEY"

مثال على الاستجابة:

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "request_id",
  "data": {
    "task_id": "task_id",
    "task_status": "succeed",
    "task_status_msg": "",
    "created_at": 1775188030000,
    "updated_at": 1775188329000,
    "task_result": {
      "videos": [
        {
          "id": "video_id",
          "url": "video download URL",
          "duration": "4"
        }
      ]
    }
  }
}

صورة إلى فيديو — إنشاء مهمة ✅

تَستخدم صورةً كأول إطار (مع إطار أخير اختياري).

curl -X POST "http://baseurl/kling/v1/videos/image2video" \
  -H "Authorization: Bearer $WS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "image": "https://example.com/first-frame.jpg",
    "image_tail": "https://example.com/last-frame.jpg",
    "prompt": "A cat playing piano in the garden",
    "cfg_scale": 0.7,
    "mode": "pro",
    "duration": "4"
  }'

معاملات إضافية مقارنةً بالنص إلى فيديو:

المعامل	النوع	مطلوب	الوصف
image	string	نعم	صورة الإطار الأول، رابط أو Base64
image_tail	string	لا	صورة الإطار الأخير، رابط أو Base64

صورة إلى فيديو — الاستعلام عن المهمة ✅

curl "http://baseurl/kling/v1/videos/image2video/task_id" \
  -H "Authorization: Bearer $WS_API_KEY"

قيم حالة مهام Kling:

• ‏submitted: مُرسلة
• ‏processing: قيد التنفيذ
• ‏succeed: مكتملة
• ‏failed: فاشلة