# واجهة 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`: فشل توليد الفيديو

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

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