# Seedance 2.5 Flash API المرجع الكامل لواجهة API الخاصة بنماذج Seedance 2.5 Flash لتوليد الفيديو من ByteDance. ## إصدارات النموذج تدعم واجهة API ثلاثة إصدارات من النموذج: | النموذج | المعرّف | الوصف | |-------|----|-------------| | **Seedance 2.5 Flash Text to Video** | `seedance-v2.5-flash-text-to-video` | توليد فيديو عالي الجودة من النص | | **Seedance 2.5 Flash Image to Video** | `seedance-v2.5-flash-image-to-video` | توليد فيديو من الإطار الأول أو من الإطارين الأول والأخير | | **Seedance 2.5 Flash Reference to Video** | `seedance-v2.5-flash-reference-to-video` | توليد فيديو بالاستعانة بصور ومقاطع فيديو ومقاطع صوتية مرجعية | ## مقارنة سريعة | الخاصية | من نص إلى فيديو | من صورة إلى فيديو | من مراجع إلى فيديو | |---------|---------------|----------------|--------------------| | نطاق المدة | من 4 إلى 30 ثانية | من 4 إلى 30 ثانية | من 4 إلى 30 ثانية | | خيارات الدقة | 480p، 720p | 480p، 720p | 480p، 720p | | نسبة العرض إلى الارتفاع | اختيارية (الافتراضية: 16:9) | غير مدعومة | اختيارية (الافتراضية: 16:9) | | الوسائط المطلوبة | لا توجد | صورة الإطار الأول | لا توجد | | الوسائط الاختيارية | لا توجد | صورة الإطار الأخير | صور ومقاطع فيديو ومقاطع صوتية | ### نسب العرض إلى الارتفاع المدعومة يدعم نموذجا التوليد من نص والتوليد من مراجع النسب التالية: `21:9`, `16:9`, `9:16`, `1:1`, `4:3`, `3:4` لا يدعم نموذج التوليد من صورة المعامل `aspect_ratio`. ### خيارات الدقة | الدقة | الوصف | |------------|-------------| | `480p` | دقة قياسية | | `720p` | دقة عالية | ## Seedance 2.5 Flash Text to Video ### نقطة النهاية ``` POST /api/v1/video/task ``` ### معاملات الطلب #### المعاملات المطلوبة | المعامل | النوع | الوصف | |-----------|------|-------------| | `model_name` | string | يجب أن تكون القيمة `"seedance-v2.5-flash-text-to-video"` | | `prompt` | string | وصف نصي لتوليد الفيديو بحد أقصى 5000 حرف | | `resolution` | string | دقة الفيديو الناتج: `"480p"` أو `"720p"`. لا توجد قيمة افتراضية | | `duration` | integer | مدة الفيديو بعدد صحيح من الثواني من 4 إلى 30، بزيادة ثانية واحدة في كل خطوة. لا توجد قيمة افتراضية | #### المعاملات الاختيارية | المعامل | النوع | الوصف | |-----------|------|-------------| | `aspect_ratio` | string | نسبة عرض الفيديو إلى ارتفاعه: `"21:9"` أو `"16:9"` أو `"9:16"` أو `"1:1"` أو `"4:3"` أو `"3:4"`. القيمة الافتراضية هي `"16:9"` | | `sound` | boolean | يحدد ما إذا كان سيُولّد صوت. القيمة الافتراضية هي `true`، وتُنتج القيمة `false` فيديو صامتًا | ### مثال على الطلب ```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-flash-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 Flash Image to Video ### معاملات الطلب #### المعاملات المطلوبة | المعامل | النوع | الوصف | |-----------|------|-------------| | `model_name` | string | يجب أن تكون القيمة `"seedance-v2.5-flash-image-to-video"` | | `prompt` | string | وصف نصي لتوليد الفيديو بحد أقصى 5000 حرف | | `resolution` | string | دقة الفيديو الناتج: `"480p"` أو `"720p"`. لا توجد قيمة افتراضية | | `duration` | integer | مدة الفيديو بعدد صحيح من الثواني من 4 إلى 30، بزيادة ثانية واحدة في كل خطوة. لا توجد قيمة افتراضية | | `image_url` | string | عنوان URL لصورة الإطار الأول. راجع حدود الوسائط أدناه. يتبع الفيديو الناتج نسبة عرض هذه الصورة إلى ارتفاعها | #### المعاملات الاختيارية | المعامل | النوع | الوصف | |-----------|------|-------------| | `image_end_url` | string | عنوان URL اختياري لصورة الإطار الأخير. راجع حدود الوسائط أدناه. يُنصح باستخدام نسبة العرض إلى الارتفاع نفسها المستخدمة في الإطار الأول | | `sound` | boolean | يحدد ما إذا كان سيُولّد صوت. القيمة الافتراضية هي `true`، وتُنتج القيمة `false` فيديو صامتًا | > لا تُدرج `aspect_ratio` في طلبات التوليد من صورة، فهذا النموذج لا يدعم هذا المعامل. ### مثال على الطلب ```javascript { model_name: 'seedance-v2.5-flash-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 Flash Reference to Video ### معاملات الطلب #### المعاملات المطلوبة | المعامل | النوع | الوصف | |-----------|------|-------------| | `model_name` | string | يجب أن تكون القيمة `"seedance-v2.5-flash-reference-to-video"` | | `prompt` | string | وصف نصي لتوليد الفيديو بحد أقصى 5000 حرف. اكتب وصفًا عاديًا من دون عناصر نائبة، أو استخدم ميزة الإشارة @ (AT) مع `<<>>` و`<<>>` و`<<>>` للإشارة صراحةً إلى عناصر مصفوفات الوسائط المقابلة | | `resolution` | string | دقة الفيديو الناتج: `"480p"` أو `"720p"`. لا توجد قيمة افتراضية | | `duration` | integer | مدة الفيديو بعدد صحيح من الثواني من 4 إلى 30، بزيادة ثانية واحدة في كل خطوة. لا توجد قيمة افتراضية | #### الوسائط المرجعية جميع الوسائط المرجعية اختيارية. يمكن إرسال صور فقط أو فيديو فقط أو صوت فقط، كما يمكن إرسال طلب من دون وسائط مرجعية. يُنصح باستخدام نموذج التوليد من نص عند عدم استخدام مراجع. | المعامل | النوع | الوصف | |-----------|------|-------------| | `images` | string[] | من 0 إلى 10 عناوين URL لصور مرجعية، وتُحدَّد الإشارات إليها بحسب ترتيبها في المصفوفة. راجع حدود الوسائط أدناه | | `videos` | string[] | من 0 إلى 5 عناوين URL لمقاطع فيديو مرجعية بصيغة MP4 أو MOV. يجب أن تتراوح مدة كل مقطع بين ثانيتين و30 ثانية، وألا يتجاوز مجموع مدد المقاطع 30 ثانية. راجع حدود الوسائط أدناه. عند احتساب التكلفة، يُقرَّب مجموع مدد مقاطع الفيديو المرجعية إلى أقرب ثانية (ويُقرَّب نصف الثانية إلى الأعلى)، ثم يُضاف إلى مدة الفيديو الناتج | | `audios` | string[] | من 0 إلى 5 عناوين URL لمقاطع صوتية مرجعية بصيغة WAV أو MP3. يجب أن تتراوح مدة كل مقطع بين ثانيتين و30 ثانية، وألا يتجاوز حجمه 15 ميغابايت، وألا يتجاوز مجموع مدد المقاطع 30 ثانية | #### العناصر النائبة للإشارة @ (AT) تربط ميزة الإشارة @ (AT) الوسائط المرجعية بالوصف النصي من خلال عناصر نائبة مرقّمة بصيغة `<<<...>>>`. يبدأ الترقيم من `1` لكل نوع من الوسائط على حدة ويتبع ترتيب عناصر المصفوفة المقابلة: | العنصر النائب | القيمة المشار إليها | |-------------|------------------| | `<<>>` | `images[0]` | | `<<>>` | `images[1]` | | `<<>>` | `videos[0]` | | `<<>>` | `audios[0]` | مثلًا، إذا كانت الصورة الأولى مرجعًا للشخصية والثانية مرجعًا للمشهد، فاستخدم `<<>>` للشخصية و`<<>>` للمشهد في `prompt`. يجب أن يشير كل عنصر نائب إلى عنصر موجود في المصفوفة المقابلة. #### المعاملات الاختيارية | المعامل | النوع | الوصف | |-----------|------|-------------| | `aspect_ratio` | string | نسبة عرض الفيديو إلى ارتفاعه: `"21:9"` أو `"16:9"` أو `"9:16"` أو `"1:1"` أو `"4:3"` أو `"3:4"`. القيمة الافتراضية هي `"16:9"` | | `sound` | boolean | يحدد ما إذا كان سيُولّد صوت. القيمة الافتراضية هي `true`، وتُنتج القيمة `false` فيديو صامتًا | ### مثال على الطلب ```javascript { model_name: 'seedance-v2.5-flash-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-flash-reference-to-video', prompt: 'Place the explorer from <<>> in the environment from <<>>, following the camera movement in <<>> and speaking with the reference voice from <<>>', 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 ميغابايت، وأن يتراوح كل من عرضها وارتفاعها بين 300 و6000 بكسل، وأن تتراوح نسبة العرض إلى الارتفاع بين 0.4 و2.5 | | الفيديو | MP4, MOV | بحد أقصى 200 ميغابايت لكل مقطع. يجب أن يتراوح كل من العرض والارتفاع بين 300 و6000 بكسل، ونسبة العرض إلى الارتفاع بين 0.4 و2.5، ومعدل الإطارات بين 24 و60 إطارًا في الثانية، والعدد الإجمالي للبكسلات بين 407696 و8295044 | | الصوت | WAV, MP3 | بحد أقصى 15 ميغابايت لكل مقطع | تخضع المقاطع الصوتية المرجعية ومقاطع الفيديو المرجعية لحدّين منفصلين، بحيث لا يتجاوز مجموع المدد لكل نوع 30 ثانية. وتُحسب الأعداد بصورة مستقلة أيضًا: حتى 10 صور و5 مقاطع فيديو و5 مقاطع صوتية. تتطلب جميع النماذج تحديد `resolution` و`duration`، ولا توجد لهما قيم افتراضية. يستخدم نموذجا التوليد من نص والتوليد من مراجع النسبة `16:9` عند إغفال `aspect_ratio`. القيمة الافتراضية لخيار الصوت هي `true`، ويمكن ضبطه على `false` لتوليد فيديو صامت. ## تنسيق الاستجابة ### الاستجابة الأولية تُرجع جميع النماذج `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. **المعاملات المطلوبة**: أرسل دائمًا `prompt` و`resolution` و`duration`. المعامل `aspect_ratio` اختياري عند التوليد من نص أو من مراجع، وقيمته الافتراضية `16:9` 2. **نسبة الأبعاد عند التوليد من صورة**: لا ترسل `aspect_ratio` في طلبات التوليد من صورة 3. **مقاطع الفيديو المرجعية**: مقاطع الفيديو اختيارية. التزم بالحدود الموضّحة لمدة كل مقطع وللمدة الإجمالية للمقاطع 4. **الصور المرجعية**: الصور اختيارية بصرف النظر عن استخدام الفيديو والصوت. أرسل حتى 10 عناوين URL لصور مدعومة 5. **المقاطع الصوتية المرجعية**: يجب أن تتراوح مدة كل مقطع بين ثانيتين و30 ثانية وألا يتجاوز حجمه 15 ميغابايت، على ألا تتجاوز المدة الإجمالية 30 ثانية 6. **ترتيب المراجع**: رتّب عناصر `images` و`videos` و`audios` بالترتيب المقصود، والتزم بهذا الترتيب عند الإشارة إليها في الوصف النصي 7. **الصوت**: أغفل `sound` لاستخدام القيمة الافتراضية `true` أو اضبطه على `false` لتعطيل توليد الصوت