# Seedance 2.5 API

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

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

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

| النموذج | ID | الوصف |
|-------|----|-------------|
| **Seedance 2.5 Text to Video** | `seedance-v2.5-text-to-video` | إنشاء فيديو عالي الجودة من النص |
| **Seedance 2.5 Image to Video** | `seedance-v2.5-image-to-video` | إنشاء فيديو باستخدام الإطار الأول أو الإطارين الأول والأخير |
| **Seedance 2.5 Reference to Video** | `seedance-v2.5-reference-to-video` | إنشاء فيديو بتوجيه من صور وفيديوهات وصوت مرجعي |

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

| الميزة | نص إلى فيديو | صورة إلى فيديو | مراجع إلى فيديو |
|---------|---------------|----------------|--------------------|
| نطاق المدة | 4-30 ثانية | 4-30 ثانية | 4-30 ثانية |
| خيارات الدقة | 480p, 720p, 1080p | 480p, 720p, 1080p | 480p, 720p, 1080p |
| نسبة الأبعاد | مطلوبة | غير مدعومة | مطلوبة |
| الوسائط المطلوبة | لا توجد | صورة الإطار الأول | لا توجد |
| الوسائط الاختيارية | لا توجد | صورة الإطار الأخير | صور وفيديوهات وصوت |

### نسب الأبعاد المدعومة

يدعم نص إلى فيديو ومراجع إلى فيديو النسب التالية:

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

لا يدعم صورة إلى فيديو المعامل `aspect_ratio`.

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

| الدقة | الوصف |
|------------|-------------|
| `480p` | دقة قياسية |
| `720p` | دقة عالية |
| `1080p` | دقة عالية كاملة |

## Seedance 2.5 Text to Video

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

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

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

#### مطلوبة

| المعامل | النوع | الوصف |
|-----------|------|-------------|
| `model_name` | string | يجب أن يكون `"seedance-v2.5-text-to-video"` |
| `prompt` | string | وصف إنشاء الفيديو |
| `resolution` | string | دقة الإخراج: `"480p"` أو `"720p"` أو `"1080p"` |
| `duration` | integer | مدة الفيديو بالثواني الصحيحة (4-30)، بزيادة قدرها ثانية واحدة |
| `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.5-text-to-video',
    prompt: 'A golden retriever running through a sunlit meadow',
    resolution: '720p',
    duration: 8,
    aspect_ratio: '16:9',
    sound: true
  })
});

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

## Seedance 2.5 Image to Video

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

#### مطلوبة

| المعامل | النوع | الوصف |
|-----------|------|-------------|
| `model_name` | string | يجب أن يكون `"seedance-v2.5-image-to-video"` |
| `prompt` | string | وصف إنشاء الفيديو |
| `resolution` | string | دقة الإخراج: `"480p"` أو `"720p"` أو `"1080p"` |
| `duration` | integer | مدة الفيديو بالثواني الصحيحة (4-30)، بزيادة قدرها ثانية واحدة |
| `image_url` | string | عنوان URL لصورة الإطار الأول |

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

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

> لا تُضمّن `aspect_ratio` في طلبات صورة إلى فيديو. هذا النموذج لا يدعم هذا المعامل.

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

```javascript
{
  model_name: 'seedance-v2.5-image-to-video',
  image_url: 'https://example.com/first-frame.jpg',
  image_end_url: 'https://example.com/last-frame.jpg',
  prompt: 'Camera slowly pulls back to reveal the full landscape',
  resolution: '720p',
  duration: 8,
  sound: true
}
```

## Seedance 2.5 Reference to Video

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

#### مطلوبة

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

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

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

| المعامل | النوع | الوصف |
|-----------|------|-------------|
| `images` | string[] | 0-30 عنوان URL لصور مرجعية؛ راجع حدود الوسائط أدناه |
| `videos` | string[] | 0-10 عناوين URL لفيديوهات مرجعية بصيغة MP4 أو MOV؛ يجب أن تكون مدة كل فيديو 2-30 ثانية، وألا يتجاوز مجموع المدد 30 ثانية |
| `audios` | string[] | 0-10 عناوين URL لصوت مرجعي بصيغة WAV أو MP3؛ يجب أن تكون مدة كل مقطع 2-30 ثانية وحجمه لا يزيد على 15 MB، وألا يتجاوز مجموع المدد 30 ثانية |

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

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

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

مثلًا، إذا كانت الصورة الأولى مرجعًا لشخصية والثانية مرجعًا لمشهد، فاستخدم `<<<image_1>>>` للشخصية و`<<<image_2>>>` للمشهد داخل `prompt`. يجب أن يشير كل عنصر نائب إلى عنصر موجود في المصفوفة المقابلة.

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

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

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

```javascript
{
  model_name: 'seedance-v2.5-reference-to-video',
  prompt: 'Use image one for the subject, video one for the movement, and audio one for the atmosphere',
  resolution: '720p',
  duration: 8,
  aspect_ratio: '16:9',
  sound: true,
  images: ['https://example.com/subject-reference.jpg'],
  videos: ['https://example.com/motion-reference.mp4'],
  audios: ['https://example.com/atmosphere-reference.mp3']
}
```

### مثال لطلب مراجع إلى فيديو باستخدام @ (AT)

```javascript
{
  model_name: 'seedance-v2.5-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>>>',
  resolution: '720p',
  duration: 10,
  aspect_ratio: '16:9',
  sound: true,
  images: [
    'https://example.com/explorer-reference.jpg',
    'https://example.com/environment-reference.png'
  ],
  videos: ['https://example.com/camera-movement-reference.mp4'],
  audios: ['https://example.com/voice-reference.mp3']
}
```

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

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

| الوسائط | الصيغ | الحدود |
|-------|---------|--------|
| الصور | 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 |

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

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

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

يختلف وقت المعالجة حسب المدة والدقة وحالة قائمة الانتظار الحالية.

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

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

1. **المعاملات المطلوبة**: أرسل `resolution` و`duration` دائمًا، وأرسل `aspect_ratio` لنص إلى فيديو ومراجع إلى فيديو
2. **نسبة أبعاد صورة إلى فيديو**: لا ترسل `aspect_ratio` في طلبات صورة إلى فيديو
3. **الفيديوهات المرجعية**: الفيديوهات اختيارية؛ يجب أن تظل مدة كل فيديو ومجموع مدد الفيديوهات ضمن الحدود الموثقة
4. **الصور المرجعية**: الصور اختيارية ومستقلة عن الفيديوهات والصوت؛ أرسل حتى 30 عنوان URL لصور مدعومة
5. **الصوت المرجعي**: اجعل مدة كل مقطع 2-30 ثانية وحجمه لا يتجاوز 15 MB، مع مجموع مدد لا يتجاوز 30 ثانية
6. **ترتيب المراجع**: رتّب `images` و`videos` و`audios` كما تريد، وأشر إليها باتساق في الوصف
7. **الصوت**: احذف `sound` لاستخدام القيمة الافتراضية `true`، أو اضبطه على `false` لتعطيل إنشاء الصوت