# واجهة برمجة تطبيقات Gemini Omni 1.2 Flash

المرجع الكامل لواجهة برمجة التطبيقات الخاصة بنماذج Google Gemini Omni 1.2 Flash لتوليد الفيديو.

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

تدعم هذه الواجهة أربعة إصدارات من النموذج:

| النموذج | المعرّف | الوصف |
|-------|-----|-------------|
| **Gemini Omni 1.2 Flash Text to Video** | `gemini-omni-1.2-flash-text-to-video` | توليد مقاطع فيديو من أوصاف نصية |
| **Gemini Omni 1.2 Flash Image to Video** | `gemini-omni-1.2-flash-image-to-video` | تحريك صورة بداية إلزامية مع إمكانية تحديد إطار نهائي لتوجيه النتيجة |
| **Gemini Omni 1.2 Flash Video Edit** | `gemini-omni-1.2-flash-video-edit` | تعديل فيديو موجود بحسب التعليمات النصية |
| **Gemini Omni 1.2 Flash Reference to Video** | `gemini-omni-1.2-flash-reference-to-video` | توليد مقاطع فيديو بالاعتماد على صور مرجعية أو مقاطع فيديو مرجعية أو كليهما |

## مقارنة سريعة

| الخاصية | توليد فيديو من نص | توليد فيديو من صورة | تعديل الفيديو | توليد فيديو من مراجع |
|---------|---------------|----------------|------------|--------------------|
| المدخل الأساسي | وصف نصي | صورة بداية ووصف نصي | فيديو أصلي وتعليمات نصية | وصف نصي وصورة مرجعية واحدة على الأقل أو فيديو مرجعي واحد على الأقل |
| المدة | من 3 إلى 15 ثانية | من 3 إلى 15 ثانية، ومن 3 إلى 10 ثوانٍ عند تحديد إطار نهائي | يجب ألا تزيد مدة الفيديو الأصلي على 10 ثوانٍ | من 3 إلى 15 ثانية |
| خيارات الدقة | 360p, 720p, 1080p, 4k | 360p, 720p, 1080p, 4k | 360p, 720p, 1080p, 4k | 360p, 720p, 1080p, 4k |
| نسب العرض إلى الارتفاع | 16:9, 9:16 | 16:9, 9:16 | غير مدعومة | 16:9, 9:16 |
| المدخلات الاختيارية | لا يوجد | صورة النهاية | لا يوجد | حتى 10 صور و3 مقاطع فيديو، ويلزم مرجع واحد على الأقل |

## نقطة النهاية المشتركة

تستخدم جميع إصدارات Gemini Omni 1.2 Flash نقطة النهاية المخصصة لمهام الفيديو:

```
POST /api/v1/video/task
```

## Gemini Omni 1.2 Flash Text to Video

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

| المعامل | النوع | الوصف |
|-----------|------|-------------|
| `model_name` | string | يجب أن تكون القيمة `"gemini-omni-1.2-flash-text-to-video"` |
| `prompt` | string | وصف نصي للفيديو المطلوب توليده |
| `aspect_ratio` | string | نسبة العرض إلى الارتفاع في الفيديو الناتج: `"16:9"` أو `"9:16"` |
| `resolution` | string | دقة الفيديو الناتج: `"360p"` أو `"720p"` أو `"1080p"` أو `"4k"` |
| `duration` | integer | مدة الفيديو الناتج بالثواني، من 3 إلى 15 |

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

```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: 'gemini-omni-1.2-flash-text-to-video',
    prompt: 'A cinematic tracking shot follows a sailboat crossing a glowing ocean at sunset',
    aspect_ratio: '16:9',
    resolution: '1080p',
    duration: 12
  })
});

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

## Gemini Omni 1.2 Flash Image to Video

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

| المعامل | النوع | الوصف |
|-----------|------|-------------|
| `model_name` | string | يجب أن تكون القيمة `"gemini-omni-1.2-flash-image-to-video"` |
| `prompt` | string | وصف نصي للحركة المطلوبة وكيفية تطور المشهد |
| `image_url` | string | عنوان URL لصورة الإطار الأول المطلوبة |
| `aspect_ratio` | string | نسبة العرض إلى الارتفاع في الفيديو الناتج: `"16:9"` أو `"9:16"` |
| `resolution` | string | دقة الفيديو الناتج: `"360p"` أو `"720p"` أو `"1080p"` أو `"4k"` |
| `duration` | integer | مدة الفيديو الناتج بالثواني، من 3 إلى 15 دون إطار نهائي، ومن 3 إلى 10 عند تحديد `image_end_url` |

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

| المعامل | النوع | الوصف |
|-----------|------|-------------|
| `image_end_url` | string | عنوان URL اختياري لصورة الإطار النهائي. عند تحديده، يجب أن تتراوح قيمة `duration` بين 3 و10 ثوانٍ |

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

```javascript
{
  model_name: 'gemini-omni-1.2-flash-image-to-video',
  prompt: 'The girl walks toward the camera while the city lights shimmer behind her',
  image_url: 'https://example.com/start-frame.jpg',
  image_end_url: 'https://example.com/end-frame.jpg',
  aspect_ratio: '9:16',
  resolution: '1080p',
  duration: 8
}
```

## Gemini Omni 1.2 Flash Video Edit

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

| المعامل | النوع | الوصف |
|-----------|------|-------------|
| `model_name` | string | يجب أن تكون القيمة `"gemini-omni-1.2-flash-video-edit"` |
| `prompt` | string | تعليمات نصية تصف التعديل المطلوب |
| `video_url` | string | عنوان URL للفيديو الأصلي. يجب ألا تزيد مدته على 10 ثوانٍ |
| `resolution` | string | دقة الفيديو الناتج: `"360p"` أو `"720p"` أو `"1080p"` أو `"4k"` |

**ملاحظة:** لا يدعم نموذج Video Edit المعاملين `aspect_ratio` و`duration`. لا تُدرج أيًا منهما في الطلب.

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

```javascript
{
  model_name: 'gemini-omni-1.2-flash-video-edit',
  prompt: 'A small ball rolls into the scene and captures the attention of the cat',
  video_url: 'https://example.com/source-video.mp4',
  resolution: '1080p'
}
```

## Gemini Omni 1.2 Flash Reference to Video

يمكن استخدام الصور ومقاطع الفيديو المرجعية كلٌّ على حدة أو معًا. يجب تقديم صورة مرجعية واحدة أو فيديو مرجعي واحد على الأقل في `images` أو `videos`.

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

| المعامل | النوع | الوصف |
|-----------|------|-------------|
| `model_name` | string | يجب أن تكون القيمة `"gemini-omni-1.2-flash-reference-to-video"` |
| `prompt` | string | وصف نصي للفيديو المطلوب توليده |
| `aspect_ratio` | string | نسبة العرض إلى الارتفاع في الفيديو الناتج: `"16:9"` أو `"9:16"` |
| `resolution` | string | دقة الفيديو الناتج: `"360p"` أو `"720p"` أو `"1080p"` أو `"4k"` |
| `duration` | integer | مدة الفيديو الناتج بالثواني، من 3 إلى 15 |

### المدخلات المرجعية الاختيارية

| المعامل | النوع | الوصف |
|-----------|------|-------------|
| `images` | string[] | حتى 10 عناوين URL للصور المرجعية. هذا المعامل اختياري عند تقديم مقاطع فيديو مرجعية |
| `videos` | string[] | حتى 3 عناوين URL لمقاطع فيديو مرجعية. يجب ألا تزيد مدة أي مقطع على 3 ثوانٍ. هذا المعامل اختياري عند تقديم صور مرجعية |

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

```javascript
{
  model_name: 'gemini-omni-1.2-flash-reference-to-video',
  prompt: 'Use the references to create a cinematic shot of a small boat approaching from the distance',
  aspect_ratio: '16:9',
  resolution: '1080p',
  duration: 12,
  images: ['https://example.com/boat-reference.jpg'],
  videos: ['https://example.com/motion-reference.mp4']
}
```

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

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

تُرجع جميع النماذج `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/{taskId}` دوريًا للتحقق من الحالة:

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": "{task_id}",
    "response_url": "https://api.flaq.ai/api/v1/video/{task_id}",
    "task_status": "succeed",
    "task_status_msg": null,
    "task_result": {
      "credit": 0.2,
      "videos": [
        {
          "url": "https://example.com/generated-video.mp4"
        }
      ]
    }
  }
}
```

### قيم الحالة

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

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

1. **صياغة الوصف النصي**: صِف بوضوح عناصر المشهد والأفعال وحركة الكاميرا والإضاءة وتطور المشهد.
2. **الإعدادات المطلوبة**: حدّد دائمًا دقة مدعومة. ولجميع الإصدارات باستثناء Video Edit، حدّد أيضًا نسبة عرض إلى ارتفاع ومدة مدعومتين.
3. **الصور المدخلة**: استخدم عناوين URL ثابتة ومتاحة للعامة لصور البداية والنهاية والصور المرجعية. عند تقديم صورة للإطار النهائي، اضبط `duration` على قيمة بين 3 و10 ثوانٍ.
4. **الفيديو المراد تعديله**: تحقّق قبل الإرسال من أن مدة الفيديو الأصلي لا تتجاوز 10 ثوانٍ.
5. **حدود المراجع**: قدّم صورة مرجعية واحدة أو فيديو مرجعيًا واحدًا على الأقل. الحد الأقصى هو 10 صور و3 مقاطع فيديو، ويجب ألا تتجاوز مدة أي مقطع مرجعي 3 ثوانٍ.