واجهة API لـ Kling 3.0 Motion Control

المرجع الكامل لواجهة API لتوليد الفيديو باستخدام Kling 3.0 Motion Control من Kuaishou.

إصدارات النموذج

تدعم واجهة API هذه إصدارًا واحدًا من النموذج:

النموذج	المعرّف	الوصف
Kling 3.0 Motion Control	`kling-3.0-motion-control`	توليد الفيديو باستخدام وصف نصي وصورة مرجعية واحدة وفيديو مرجعي واحد

Kling 3.0 Motion Control

نقطة النهاية

POST /api/v1/video/task

معلمات الطلب

المعلمات المطلوبة

المعلمة	النوع	الوصف
`model_name`	string	يجب أن تكون القيمة `"kling-3.0-motion-control"`
`prompt`	string	وصف نصي لتوليد الفيديو، بحد أقصى 5000 حرف
`images`	string[]	عنوان URL لصورة مرجعية واحدة بالضبط. الصيغ المدعومة هي `.jpg` و`.jpeg` و`.png`؛ ويجب ألا يتجاوز حجم الملف 50 ميغابايت. يجب ألا يقل كل من العرض والارتفاع عن 300 بكسل، وأن تتراوح نسبة أبعاد الصورة بين 1:2.5 و2.5:1
`videos`	string[]	عنوان URL لفيديو مرجعي واحد بالضبط. الصيغ المدعومة هي `.mp4` و`.mov`؛ ويجب ألا يتجاوز حجم الملف 100 ميغابايت. يجب أن يتراوح كل من العرض والارتفاع بين 340 و3850 بكسل، شاملًا الحدين. يجب ألا تقل المدة عن 3 ثوانٍ؛ ويعتمد الحد الأقصى على `character_orientation`
`character_orientation`	string	معلمة مطلوبة بلا قيمة افتراضية. `"image"`: يتبع اتجاه الشخصية في الصورة المرجعية؛ ويجب أن تتراوح مدة الفيديو المرجعي بين 3 و10 ثوانٍ. `"video"`: يتبع اتجاه الشخصية في الفيديو المرجعي؛ ويجب أن تتراوح مدة الفيديو المرجعي بين 3 و30 ثانية. يشمل كلا النطاقين الحدين الأدنى والأقصى
`resolution`	string	دقة الفيديو الناتج: `"720p"` أو `"1080p"`. معلمة مطلوبة بلا قيمة افتراضية

المعلمات الاختيارية

المعلمة	النوع	الوصف
`keep_original_sound`	boolean	ما إذا كان سيتم الاحتفاظ بالصوت الأصلي للفيديو المرجعي. تقبل `true` أو `false`؛ والقيمة الافتراضية هي `true`

تتبع مدة الفيديو الناتج مدة الفيديو المصدر. المعلمة duration غير مدعومة. تُحدَّد نسبة أبعاد الفيديو الناتج وفقًا للوسائط المُدخلة، والمعلمة aspect_ratio غير مدعومة. لم يحدد مزوّد النموذج أيًّا من المدخلات يحدد نسبة أبعاد الفيديو الناتج، ولا قاعدة الاختيار الدقيقة.

تُحتسب التكلفة بناءً على مدة الفيديو المصدر بعد تقريبها إلى أقرب ثانية كاملة، ودقة الفيديو الناتج المحددة. على سبيل المثال، تُحتسب مدة 5.4 ثانية على أنها 5 ثوانٍ، ومدة 5.5 ثانية على أنها 6 ثوانٍ.

مثال على الطلب

استبدل عناوين URL للوسائط في المثال بعناوين ملفاتك الخاصة التي تستوفي المتطلبات أعلاه.

javascript
const response = await fetch('https://api.flaq.ai/api/v1/video/task', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model_name: 'kling-3.0-motion-control',
    prompt: 'Animate the character in the reference image using the dance movements from the reference video',
    images: ['https://example.com/character.jpg'],
    videos: ['https://example.com/dance-reference.mp4'],
    character_orientation: 'video',
    resolution: '720p',
    keep_original_sound: true
  })
});

const { data } = await response.json();
const taskId = data.task_id;

تنسيق الاستجابة

الاستجابة الأولية

تُرجع task_id للاستعلام الدوري:

json
{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": "{task_id}",
    "response_url": "https://api.flaq.ai/api/v1/video/{task_id}",
    "task_status": "submitted"
  }
}

استخدم GET /api/v1/video/{task_id} للاستعلام الدوري عن الحالة واسترجاع الفيديو الناتج.

قيم الحالة

submitted: تم قبول المهمة وهي بانتظار المعالجة
processing: جارٍ توليد الفيديو
succeed: اكتمل توليد الفيديو
failed: فشل توليد الفيديو

أفضل الممارسات

الوسائط المرجعية: أرسل صورة واحدة وفيديو واحدًا بالضبط، مع التحقق من صيغهما وأحجام ملفاتهما وأبعادهما قبل الإرسال
الاتجاه: أعد التحقق من مدة الفيديو المرجعي عند تغيير character_orientation، وخاصة عند اختيار "image"
الصوت الأصلي: اضبط keep_original_sound على false لتعطيل الاحتفاظ بالصوت الأصلي للفيديو المرجعي؛ ويؤدي إغفال المعلمة إلى الاحتفاظ بالصوت