# Seedance 2.0 Mini API

مرجع API الكامل لنماذج إنشاء الفيديو Seedance 2.0 Mini من ByteDance.

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

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

| النموذج | ID | الوصف |
|-------|-----|-------------|
| **Seedance 2.0 Mini Text to Video** | `seedance-v2.0-mini-text-to-video` | إنشاء فيديو من النص بتكلفة اقتصادية |
| **Seedance 2.0 Mini Image to Video** | `seedance-v2.0-mini-image-to-video` | تحريك الصور بتكلفة اقتصادية مع التحكم في الحركة |
| **Seedance 2.0 Mini Reference to Video** | `seedance-v2.0-mini-reference-to-video` | إنشاء فيديو بتكلفة اقتصادية بتوجيه من صور وفيديوهات وملفات صوتية مرجعية |

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

| الميزة | القيمة |
|---------|-------|
| نطاق المدة | 4-15 ثانية |
| خيارات الدقة | 480p, 720p |
| خيارات نسبة العرض إلى الارتفاع | 21:9, 16:9, 9:16, 1:1, 4:3, 3:4 |
| دعم الصوت | نعم (مفعّل افتراضيًا) |
| الوسائط المرجعية | صور وفيديوهات وملفات صوتية لإنشاء الفيديو من المراجع |
| التحكم في البذرة | لا يدعمه أي نموذج من Seedance 2.0 Mini |

### نسب العرض إلى الارتفاع المدعومة

`21:9`, `16:9`, `9:16`, `1:1`, `4:3`, `3:4`

### خيارات الدقة

| الدقة | الوصف |
|------------|-------------|
| `480p` | دقة قياسية ومعالجة أسرع |
| `720p` | دقة عالية |

## Seedance 2.0 Mini Text to Video

### نقطة النهاية

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

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

#### مطلوبة

| المعلمة | النوع | الوصف |
|-----------|------|-------------|
| `model_name` | string | يجب أن تكون `"seedance-v2.0-mini-text-to-video"` |
| `prompt` | string | الموجّه النصي لإنشاء الفيديو |
| `duration` | integer | مدة الفيديو بالثواني الصحيحة (4-15)، بزيادة قدرها 1 |
| `resolution` | string | دقة الإخراج: `"480p"` أو `"720p"` |
| `aspect_ratio` | string | نسبة عرض الفيديو إلى ارتفاعه: `"21:9"` أو `"16:9"` أو `"9:16"` أو `"1:1"` أو `"4:3"` أو `"3:4"` |

#### اختيارية

| المعلمة | النوع | الوصف |
|-----------|------|-------------|
| `sound` | boolean | ما إذا كان سيتم إنشاء أصوات محيطة (الافتراضي: `true`) |

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

```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: 'seedance-v2.0-mini-text-to-video',
    prompt: 'A golden retriever running through a sunlit meadow',
    duration: 6,
    resolution: '720p',
    aspect_ratio: '16:9',
    sound: true
  })
});

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

## Seedance 2.0 Mini Image to Video

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

#### مطلوبة

| المعلمة | النوع | الوصف |
|-----------|------|-------------|
| `model_name` | string | يجب أن تكون `"seedance-v2.0-mini-image-to-video"` |
| `prompt` | string | الموجّه النصي لإنشاء الفيديو |
| `duration` | integer | مدة الفيديو بالثواني الصحيحة (4-15)، بزيادة قدرها 1 |
| `resolution` | string | دقة الإخراج: `"480p"` أو `"720p"` |
| `aspect_ratio` | string | نسبة عرض الفيديو إلى ارتفاعه: `"21:9"` أو `"16:9"` أو `"9:16"` أو `"1:1"` أو `"4:3"` أو `"3:4"` |
| `image_url` | string | الإطار الأول للفيديو |

#### اختيارية

| المعلمة | النوع | الوصف |
|-----------|------|-------------|
| `image_end_url` | string | عنوان URL اختياري لصورة الإطار الأخير |
| `sound` | boolean | ما إذا كان سيتم إنشاء أصوات محيطة (الافتراضي: `true`) |

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

```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: 'seedance-v2.0-mini-image-to-video',
    image_url: 'https://example.com/image.jpg',
    image_end_url: 'https://example.com/end-frame.jpg',
    prompt: 'Camera slowly pulls back to reveal the full landscape',
    duration: 6,
    resolution: '720p',
    aspect_ratio: '16:9',
    sound: true
  })
});

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

## Seedance 2.0 Mini Reference to Video

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

#### مطلوبة

| المعلمة | النوع | الوصف |
|-----------|------|-------------|
| `model_name` | string | يجب أن تكون `"seedance-v2.0-mini-reference-to-video"` |
| `prompt` | string | الموجّه النصي لإنشاء الفيديو. اكتب موجّهًا عاديًا دون عناصر نائبة، أو استخدم ميزة الإشارة @ (AT) مع `<<<image_N>>>` و`<<<video_N>>>` و`<<<audio_N>>>` للإشارة صراحةً إلى عناصر من مصفوفات الوسائط المقابلة |
| `duration` | integer | مدة الفيديو بالثواني الصحيحة (4-15)، بزيادة قدرها 1 |
| `resolution` | string | دقة الإخراج: `"480p"` أو `"720p"` |
| `aspect_ratio` | string | نسبة عرض الفيديو إلى ارتفاعه: `"21:9"` أو `"16:9"` أو `"9:16"` أو `"1:1"` أو `"4:3"` أو `"3:4"` |

#### الوسائط المرجعية

يجب أن يتضمن كل طلب صورة واحدة أو فيديو واحدًا على الأقل. أرسل من 1 إلى 9 صور عند استخدام مراجع الصور. يمكن حذف مصفوفة `images` أو تركها فارغة فقط عندما تحتوي مصفوفة `videos` على فيديو مرجعي واحد على الأقل. الطلبات التي تحتوي على صوت فقط غير مدعومة.

| المعلمة | النوع | الوصف |
|-----------|------|-------------|
| `images` | string[] | من 1 إلى 9 عناوين URL لصور مرجعية، أو مصفوفة فارغة عندما تكون `videos` غير فارغة |
| `videos` | string[] | حتى 3 عناوين URL لفيديوهات مرجعية؛ يجب أن تكون مدة كل فيديو 2-15 ثانية، وألا يتجاوز مجموع المدد 15 ثانية |
| `audios` | string[] | حتى 3 عناوين URL لملفات صوتية مرجعية؛ يجب أن تكون مدة كل مقطع 2-15 ثانية، وألا يتجاوز مجموع المدد 15 ثانية؛ WAV أو MP3، بحد أقصى 15 MB لكل مقطع؛ يتطلب صورة واحدة أو فيديو واحدًا على الأقل |

#### العناصر النائبة للإشارة @ (AT)

تربط ميزة الإشارة @ (AT) الوسائط المرجعية بالموجّه عبر عناصر نائبة مرقّمة بالشكل `<<<...>>>`. يبدأ الترقيم من `1` بشكل مستقل لكل نوع من الوسائط ويتبع ترتيب المصفوفة المقابلة:

| العنصر النائب | القيمة المشار إليها |
|-------------|------------------|
| `<<<image_1>>>` | `images[0]` |
| `<<<image_2>>>` | `images[1]` |
| `<<<video_1>>>` | `videos[0]` |
| `<<<audio_1>>>` | `audios[0]` |

يجب أن يشير كل عنصر نائب إلى عنصر موجود في المصفوفة المقابلة.

#### اختيارية

| المعلمة | النوع | الوصف |
|-----------|------|-------------|
| `sound` | boolean | ما إذا كان سيتم إنشاء صوت متزامن. القيمة الافتراضية `true` |

### تسعير الفيديوهات المرجعية

يتبع Seedance V2.0 Mini Reference-to-Video بنية الفوترة نفسها بالثانية حسب الدقة المستخدمة في إصدارات Seedance 2.0 المرجعية الأخرى. عندما تحتوي مصفوفة `videos` على فيديو مرجعي واحد على الأقل، تُضرب تكلفة الإنشاء الإجمالية في 2. يُطبّق هذا المضاعف مرة واحدة، بغض النظر عن عدد الفيديوهات المرجعية المرفوعة أو مدتها.

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

```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: 'seedance-v2.0-mini-reference-to-video',
    prompt: 'Place the explorer from <<<image_1>>> in the environment from <<<image_2>>>, following the camera movement in <<<video_1>>> and speaking with the reference voice from <<<audio_1>>>',
    duration: 8,
    resolution: '720p',
    aspect_ratio: '16:9',
    sound: true,
    images: [
      'https://example.com/explorer-reference.jpg',
      'https://example.com/environment-reference.jpg'
    ],
    videos: ['https://example.com/camera-movement-reference.mp4'],
    audios: ['https://example.com/voice-reference.mp3']
  })
});

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

## حدود الوسائط

تنطبق هذه الحدود على صور الإطار الأول وصور الإطار الأخير والوسائط المرجعية لنماذج هذه الصفحة.

| الوسائط | التنسيقات | الحدود |
|-------|---------|--------|
| الصور | JPEG, PNG, WEBP, BMP, TIFF, GIF, HEIC, HEIF | يجب أن يكون حجم كل صورة أقل من 30 MB؛ وأن يتراوح كل من العرض والارتفاع بين 300 و6000 px؛ وأن تكون نسبة العرض إلى الارتفاع بين 0.4 و2.5 |
| الفيديوهات | MP4, MOV | بحد أقصى 200 MB لكل فيديو؛ يجب أن يتراوح كل من العرض والارتفاع بين 300 و6000 px؛ ونسبة العرض إلى الارتفاع بين 0.4 و2.5؛ ومعدل الإطارات بين 24 و60 FPS |
| الصوت | WAV, MP3 | بحد أقصى 15 MB لكل ملف |
| جسم الطلب | — | بحد أقصى 64 MB |

للصوت المرجعي والفيديو المرجعي حدّان منفصلان لمجموع المدد، قدر كل منهما 15 ثانية. كما أن الأعداد مستقلة: حتى 9 صور و3 فيديوهات و3 مقاطع صوتية. إضافة فيديوهات لا تقلّل عدد الصور المسموح به.

تستخدم جميع النماذج `720p` افتراضيًا، لكن يجب مع ذلك توفير `resolution`. القيمة الافتراضية لمفتاح الصوت هي `true`؛ ولا يؤثر هذا المفتاح ولا الصوت المرجعي في السعر. يتطلب إنشاء الفيديو من المراجع صورة واحدة أو فيديو واحدًا على الأقل؛ ولا تُدعم الطلبات الصوتية فقط. رفع فيديوهات مرجعية يضاعف تكلفة الإنشاء بغض النظر عن عددها أو مدتها.

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

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

تُرجع جميع النماذج `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`: فشل إنشاء الفيديو

## وقت المعالجة

يتراوح وقت المعالجة المعتاد بين دقيقتين و6 دقائق، حسب المدة والدقة.

استعلم كل 5-10 ثوانٍ للتحقق من الحالة.

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

1. **صف الحركة بوضوح**: ضمّن أوصافًا محددة للحركة في الموجّهات
2. **اختيار الدقة**: استخدم `480p` لمعالجة أسرع و`720p` لجودة أعلى
3. **تعزيز الصوت**: أبقِ `sound` مفعّلًا لتجربة فيديو أكثر واقعية
4. **الصورة إلى فيديو**: قدّم إطارًا أول واضحًا عبر `image_url`؛ واستخدم `image_end_url` عند الحاجة إلى التحكم في إطاري البداية والنهاية
5. **الوسائط المرجعية**: استخدم الصور والفيديوهات والصوت المرجعي المدعوم، وتأكد من تضمين صورة واحدة أو فيديو واحد على الأقل
6. **تسعير الفيديوهات المرجعية**: تُحتسب أي طلبات لإنشاء فيديو من المراجع تحتوي على فيديو مرجعي واحد على الأقل بضعف التكلفة، بغض النظر عن عدد الفيديوهات المرفوعة أو مدتها
7. **معلمة البذرة**: لا ترسل `seed`؛ فنماذج Seedance 2.0 Mini لا تدعمها