Seedance 2.5 Flash
قم بتوليد الفيديوهات باستخدام Seedance 2.5 Flash عبر النص، أو الإطارات الأولى والأخيرة، أو مراجع متعددة الوسائط. تغطي هذه الصفحة سير العمل بالكامل من الطلب إلى النتيجة لهذا النموذج.
معرف النموذج في الـ API: seedance-2-5-flash
عملية التوليد غير متزامنة. احفظ الـ taskId الذي يتم إرجاعه عند إنشاء المهمة، ثم استعلم عن حالتها أو استقبل النتيجة عبر خطاف الويب.
الإمكانيات
| الميزة | القيم المدعومة |
|---|---|
| دقة المخرجات | 480p · 720p |
| مدة المخرجات | ٤–30 ثوانٍ |
| نسبة العرض إلى الارتفاع | 16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptive |
| الصور المرجعية | حتى 30 صور |
| الفيديوهات المرجعية | حتى 10 مقاطع فيديو |
| الملفات الصوتية المرجعية | حتى 10 ملفات صوتية |
| كافة المراجع مدمجة | حتى 50 من الملفات المرجعية إجمالاً |
| المدة الإجمالية لكل مجموعة فيديو/صوت | 30 ثانية |
| seed | -1 إلى 2147483647 |
الأسعار والأرصدة
يتم احتساب تكلفة توليد الفيديو بالنقاط بناءً على مدة الفيديو الخاضعة للفوترة بالثواني. في حال عدم وجود فيديو مدخل، تكون المدة الخاضعة للفوترة هي مدة الفيديو الناتج؛ أما في حال وجود فيديو مدخل، فتشمل المدة أيضاً مدة الفيديو المرجعي.
يوضح الجدول أدناه النقاط المحتسبة لكل ثانية، وليس التكلفة الإجمالية للمهمة. تعتمد التعريفة على النموذج المستخدم، ودقة الفيديو الناتج، وما إذا كان قد تم إدخال مقاطع فيديو مرجعية في وضع "المرجع إلى فيديو" (reference-to-video). يرجى الاطلاع على المعادلات والأمثلة الموضحة أسفل الجدول لمعرفة كيفية حساب التكلفة الإجمالية.
| دقة المخرجات | بدون إدخال فيديو | مع إدخال فيديو |
|---|---|---|
480p | 7 رصيد/الثانية | 5 رصيد/الثانية |
720p | 10 رصيد/الثانية | 7 رصيد/الثانية |
- بدون إدخال فيديو: ثواني المخرجات × سعر عدم وجود فيديو.
- مع إدخال فيديو: (ثواني المخرجات + ثواني الفيديو المرجعي المقاسة) × سعر وجود فيديو. يقوم الخادم بقياس المدة الإجمالية للفيديو المرجعي ويقربها لأعلى إلى أقرب ثانية كاملة قبل الاحتساب.
- تطبق مراجع الصور أو الصوت وحدها سعر عدم وجود فيديو. لا يطبق سعر فوترة الفيديو المرجعي إلا في وضع مرجع إلى فيديو عند توفير مراجع فيديو.
أمثلة على احتساب التكلفة
نص إلى فيديو مدته 5 ثوانٍ وبدقة 720p: 5 × 10 = 50 رصيدًا.
مخرج مدته 5 ثوانٍ بدقة 720p مع فيديو مرجعي مدته 5 ثوانٍ: (5 + 5) × 7 = 70 رصيدًا.
تُحجز الأرصدة عند تقديم الطلب وتُخصم عند النجاح. تدخل المهام الفاشلة أو التي انتهت مهلتها في مسار استرداد الأموال. تعني حالة الفوترة refund_failed أن عملية الاسترداد لم تكتمل؛ يرجى مراجعة سجلات الـ API أو الاتصال بالدعم.
كيفية احتساب الرصيد عندما تكون المدة = -1
عند ضبط المدة على -1، لن تكون مدة الفيديو النهائي ثابتة، بل يحددها النموذج تلقائيًا.
في معظم الحالات، يُنصح بتحديد المدة الفعلية التي تحتاجها للفيديو بدلاً من ضبطها على -1. نوصي باستخدام القيمة -1 لتحرير الفيديو فقط، وتجنب استخدامها في حالات توليد الفيديو الأخرى.
| المدخلات المرجعية | طريقة احتساب التكلفة | مثال |
|---|---|---|
| بوجود فيديوهات مرجعية | تُجمع مدد كافة الفيديوهات المرجعية وتُقرّب التكلفة الإجمالية لأقرب ثانية كاملة تالية، ويُرمز لها بالرمز T. وتُحسب التكلفة بالمعادلة: (T + T) × سعر الباقة بوجود فيديو؛ حيث يمثل الرمز T الأول مدة الفيديو المخرَج المتوقعة، بينما يمثل الرمز T الآخر مدة الفيديو المدخَل. | جودة 720p مع فيديو مرجعي مدته 5 ثوانٍ: (5 + 5) × 7 = 70 رصيد. |
| بدون فيديوهات مرجعية (صور أو صوت فقط) | تُعتمد 30 ثانية كمدة متوقعة للفيديو المخرَج. وتُحسب التكلفة بالمعادلة: 30 × سعر الباقة بدون فيديو. | جودة 720p بدون فيديوهات مرجعية: 30 × 10 = 300 رصيد. |
المصادقة
أنشئ مفتاح API في لوحة التحكم. يظهر المفتاح الكامل مرة واحدة فقط. احتفظ به في خادمك وأرسله كرمز حامل (Bearer token) مع كل طلب.
رابط الأساس (Base URL)
https://api.seevio.aiAuthorization: Bearer sk_live_your_api_key
Content-Type: application/jsonقم بتعيين متغير البيئة SEEVIO_API_KEY قبل تشغيل هذه الأمثلة. يتم تشغيل أمثلة JavaScript على خادمك باستخدام Node.js؛ وتستخدم أمثلة Python حزمة requests.
البدء السريع
أرسل هذا الطلب البسيط، واحفظ الـ taskId المسترجع، ثم استخدم مثال الاستعلام عن المهمة أدناه. قيمة الرصيد في استجابة الإنشاء تمثل المبلغ المحجوز.
curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
-H "Authorization: Bearer $SEEVIO_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"model": "seedance-2-5-flash",
"input": {
"prompt": "A cat surfing at sunset, cinematic lighting",
"duration": 5,
"resolution": "720p",
"seed": 42,
"generation_type": "text-to-video",
"aspect_ratio": "16:9",
"generate_audio": true
}
}'مثال على استجابة إنشاء المهمة
بعد قبول الطلب أعلاه، ترجع واجهة برمجة التطبيقات (API) استجابة JSON هذه. يمثل taskId معرف المهمة المستخدم في عمليات الاستعلام اللاحقة عن الحالة؛ بينما يمثل credits عدد النقاط المحجوزة لهذه المهمة. تؤكد هذه الاستجابة إنشاء المهمة بنجاح، ولا تعني أن الفيديو جاهز بعد. يتعين عليك تتبع حالة المهمة بشكل دوري (Poll) أو استخدام Webhook لتلقي نتائج الفيديو.
{
"taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
"credits": 50
}إنشاء مهمة
POST https://api.seevio.ai/v1/videos/generationsأرسل كائن JSON يحتوي على model وinput، بالإضافة إلى callback_url اختياري. حدد دائمًا معرف النموذج (model ID) المعروض في هذه الصفحة؛ وفي حال حذفه، سيتم تحديد seedance-2-0 تلقائيًا.
جسم الطلب (Request body)
| الحقل | النوع | مطلوب | الوصف والقيود |
|---|---|---|---|
model | string | نعم | معرّف النموذج. لاستخدام Seedance 2.5 Flash، عيّن قيمة هذا الحقل إلى seedance-2-5-flash. |
callback_url | string | لا | نقطة نهاية HTTPS عامة لاستلام استجابات POST عند الاكتمال أو الفشل. الشبكات الخاصة والاستضافة المحلية (localhost) غير مسموح بها. مثال: https://example.com/webhooks/seevio |
input | object | نعم | إعدادات التوليد. يجب أن تحتوي على وصف (prompt) غير فارغ. |
معلمات الإدخال
يرجى توفير image_urls و video_urls و audio_urls في شكل مصفوفات من سلاسل عناوين URL (string[]). يجب أن يكون كل عنوان URL متوفرًا بشكل عام للوصول إليه عبر بروتوكول HTTPS، بما في ذلك الوسائط التي تم تجاهلها بواسطة الوضع المحدد.
| الحقل | النوع | مطلوب | افتراضي | الوصف والقيود |
|---|---|---|---|---|
input.prompt | string | نعم | — | يجب إدخال وصف نصي في جميع الأوضاع، وبحد أقصى 10,000 حرف (قبل تصفية الفراغات)، ولا يمكن أن يقتصر الوصف على مسافات فارغة فقط. مثال: A cat surfing at sunset |
input.generation_type | string | لا | text-to-video | القيم المدعومة text-to-video | image-to-video | reference-to-videotext-to-video، أو image-to-video، أو reference-to-video. في حال حذفه، يكون الافتراضي هو text-to-video ويستخدم الوصف النصي فقط. يستخدم وضع image-to-video صور إطارات مرتبة (1-2 صور). ويستخدم وضع reference-to-video الصور، والفيديوهات و/أو الصوت؛ ويدعم مراجع الصوت فقط مع وجود وصف نصي مطلوب. |
input.image_urls | string[] | مشروط | [] | قدم روابط الصور لتوجيه المظهر البصري. في وضع image-to-video، قدم صورة واحدة للإطار الأول أو صورتين بترتيب الإطار الأول ثم الإطار الأخير. في وضع reference-to-video، قدم صورًا بحد أقصى 30 صورة. يجب أن يكون حجم كل صورة أقل من 30 ميجابايت؛ انظر متطلبات الوسائط أدناه لمعرفة الصيغ والأبعاد المقبولة. يسمح بتقديم 50 ملفًا كحد أقصى لجميع أنواع المراجع مدمجة. عند إهماله، يكون الافتراضي هو []؛ ويتم تجاهله في وضع text-to-video. مثال: ["https://example.com/first-frame.jpg"] |
input.video_urls | string[] | مشروط | [] | قدم روابط الفيديوهات المرجعية لتوجيه الحركة أو لتعديل فيديو أو تمديد مدته، وذلك فقط في وضع reference-to-video. يسمح بتقديم 10 ملفات كحد أقصى، على ألا يتجاوز حجم الملف 100 ميجابايت وتتراوح مدته بين 2 و 30 ثانية؛ ويجب ألا تتجاوز المدة الإجمالية لها 30 ثانية. يسمح بتقديم 50 ملفًا كحد أقصى لجميع أنواع المراجع مدمجة. يقيس الخادم مدة الفيديو لاحتساب الفواتير. عند إهماله، يكون الافتراضي هو []؛ ويتم تجاهله في الأوضاع الأخرى. مثال: ["https://example.com/source.mp4"] |
input.audio_urls | string[] | مشروط | [] | قدم روابط الملفات الصوتية المرجعية لتوجيه الصوت، وذلك فقط في وضع reference-to-video. يسمح بتقديم 10 ملفات كحد أقصى بصيغة MP3/WAV، على ألا يتجاوز حجم الملف 15 ميجابايت وتتراوح مدته بين 2 و 30 ثانية؛ ويجب ألا تتجاوز المدة الإجمالية لها 30 ثانية. يسمح بتقديم 50 ملفًا كحد أقصى لجميع أنواع المراجع مدمجة. يمكن أن يكون الصوت هو المرجع الوحيد؛ مع بقاء الوصف النصي مطلوبًا. عند إهماله، يكون الافتراضي هو []؛ ويتم تجاهله في الأوضاع الأخرى. مثال: ["https://example.com/music.mp3"] |
input.duration | integer | لا | 5 | القيم المدعومة -1 | 4–30مدة المخرجات كعدد صحيح من 4 إلى 30 ثوانٍ. يقبل أيضًا القيمة -1 فقط في وضع reference-to-video. استخدمها مع فيديو مصدر للتعديل؛ وتخضع الفوترة للقاعدة الخاصة الموضحة أعلاه. مثال: 5 |
input.aspect_ratio | string | لا | adaptive | القيم المدعومة 16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptiveالنسب المتاحة هي 16:9، أو 4:3، أو 1:1، أو 3:4، أو 9:16، أو 21:9، أو adaptive. عند إهماله، يكون الافتراضي هو adaptive، مما يتيح للنموذج تحديد النسبة الأنسب للفيديو الناتج تلقائيًا. لتعديل الفيديو أو تمديد مدته، استخدم القيمة adaptive. لا يقبل وضع image-to-video سوى adaptive؛ اترك هذا الحقل فارغًا أو اضبطه على adaptive. مثال: adaptive |
input.resolution | string | لا | 720p | القيم المدعومة 480p | 720pخيارات الدقة هي 480p أو 720p. عند إهماله، يكون الافتراضي هو 720p لجميع أوضاع التوليد المدعومة. يتم رفض الدقات الأعلى. مثال: 720p |
input.generate_audio | boolean | لا | true | القيم المدعومة true | falseتطلب القيمة true توليد صوت متزامن؛ بينما تعطل القيمة false توليد الصوت. عند إهماله، يكون الافتراضي هو true. ينطبق هذا على جميع أوضاع التوليد المدعومة. مثال: true |
input.watermark | boolean | لا | false | القيم المدعومة true | falseتطلب القيمة true إضافة علامة مائية تشير إلى الذكاء الاصطناعي (AI) على الفيديو الناتج؛ وتطلب القيمة false الحصول على الفيديو بدون تلك العلامة. عند إهماله، يكون الافتراضي هو false. ينطبق هذا على جميع أوضاع التوليد المدعومة. مثال: false |
input.web_search | boolean | لا | false | القيم المدعومة true | falseتسمح القيمة true بالبحث في الويب إذا كان متاحًا للنموذج؛ بينما تعطل القيمة false هذه الميزة. عند إهماله، يكون الافتراضي هو false. تفعيل هذا الخيار لا يضمن إجراء البحث بالضرورة. مثال: false |
input.return_last_frame | boolean | لا | false | القيم المدعومة true | falseتطلب القيمة true الإطار الأخير للفيديو الناتج؛ بينما لا تطلبه القيمة false. عند إهماله، يكون الافتراضي هو false. ينطبق هذا على جميع أوضاع التوليد المدعومة. عند طلبه وتوفره، يتم إرجاع الرابط في الحقل data.last_frame_url؛ وإلا تكون قيمته null. مثال: true |
input.seed | integer | لا | — | القيم المدعومة -1 إلى 2147483647عدد صحيح من -1 إلى 2147483647. تختار القيمة -1 بذرة عشوائية. مثال: 42 |
input.output_format | string | لا | mp4 | القيم المدعومة mp4 | movخيارات الصيغة هي mp4 أو mov. عند إهماله، يكون الافتراضي هو mp4. يحدد هذا الإعداد تنسيق حاوية الفيديو الناتج لجميع أوضاع التوليد المدعومة. |
يجب أن تكون الحقول المنطقية قيم JSON true أو false، وليست نصوصًا أو أرقامًا.
استجابة الإنشاء
تعيد استجابة HTTP 200 المعرف taskId (نص) والرصيد credits (رقم). هذا تأكيد على إنشاء المهمة وليس اكتمالها. القيمة أدناه تتوافق مع البدء السريع لـ 5 ثوانٍ بدقة 720p.
{
"taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
"credits": 50
}أوضاع التوليد وأمثلة
نص إلى فيديو
التوليد من وصف نصي. لا يتم تمرير عناوين URL للوسائط في هذا الوضع.
curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
-H "Authorization: Bearer $SEEVIO_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"model": "seedance-2-5-flash",
"input": {
"prompt": "A cat surfing at sunset, cinematic lighting",
"duration": 5,
"resolution": "720p",
"seed": 42,
"generation_type": "text-to-video",
"aspect_ratio": "16:9",
"generate_audio": true
}
}'الإطار الأول
قدم صورة واحدة كإطار أول، ثم صف الحركة المطلوبة في الوصف الخاص بك.
curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
-H "Authorization: Bearer $SEEVIO_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"model": "seedance-2-5-flash",
"input": {
"prompt": "A cat surfing at sunset, cinematic lighting",
"duration": 5,
"resolution": "720p",
"seed": 42,
"generation_type": "image-to-video",
"image_urls": [
"https://example.com/first-frame.jpg"
],
"aspect_ratio": "adaptive"
}
}'الإطاران الأول والأخير
قدم عنوانين لصور مرتبة: الإطار الأول، ثم الإطار الأخير. يطلب هذا المثال أيضًا الحصول على الإطار الأخير من الفيديو المولد.
curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
-H "Authorization: Bearer $SEEVIO_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"model": "seedance-2-5-flash",
"input": {
"prompt": "A cat surfing at sunset, cinematic lighting",
"duration": 5,
"resolution": "720p",
"seed": 42,
"generation_type": "image-to-video",
"image_urls": [
"https://example.com/first-frame.jpg",
"https://example.com/last-frame.jpg"
],
"aspect_ratio": "adaptive",
"return_last_frame": true
}
}'مرجع متعدد الوسائط
دمج مراجع الصور، الفيديو والصوت معًا. يظل الوصف النصي مطلوبًا. يؤدي إدخال الفيديو المرجعي إلى تغيير معادلة الفوترة.
curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
-H "Authorization: Bearer $SEEVIO_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"model": "seedance-2-5-flash",
"input": {
"prompt": "Follow the reference camera movement and keep the character consistent. Use the audio for ambience.",
"duration": 5,
"resolution": "720p",
"seed": 42,
"generation_type": "reference-to-video",
"image_urls": [
"https://example.com/character.jpg"
],
"video_urls": [
"https://example.com/camera.mp4"
],
"audio_urls": [
"https://example.com/ambience.mp3"
],
"aspect_ratio": "adaptive"
}
}'مرجع صوتي
استخدام الصوت كنوع المرجع الوحيد، مع وصف نصي مطلوب يوضح الفيديو المنشود.
curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
-H "Authorization: Bearer $SEEVIO_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"model": "seedance-2-5-flash",
"input": {
"prompt": "Create a coastal sunrise scene matching the rhythm of this audio.",
"duration": 5,
"resolution": "720p",
"seed": 42,
"generation_type": "reference-to-video",
"audio_urls": [
"https://example.com/music.mp3"
]
}
}'تعديل الفيديو
صف التعديل المطلوب وقدم الفيديو المصدر. اضبط duration=-1 واستخدم نسبة العرض إلى الارتفاع adaptive. استخدم مقطعًا مصدريًا لا يقل عن 4 ثوانٍ لسير العمل هذا. قاعدة الفوترة لـ duration=-1 موضحة أعلاه.
curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
-H "Authorization: Bearer $SEEVIO_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"model": "seedance-2-5-flash",
"input": {
"prompt": "Edit the source video: change the character’s coat to blue and preserve the camera movement.",
"duration": -1,
"resolution": "720p",
"seed": 42,
"generation_type": "reference-to-video",
"video_urls": [
"https://example.com/source.mp4"
],
"aspect_ratio": "adaptive"
}
}'تمديد الفيديو
صف كيف يجب أن يستمر الفيديو المصدر. استخدم نسبة العرض إلى الارتفاع adaptive واضبط مدة مخرجات عادية ضمن نطاق النموذج.
curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
-H "Authorization: Bearer $SEEVIO_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"model": "seedance-2-5-flash",
"input": {
"prompt": "Continue the camera movement from the source video, revealing a forest clearing.",
"duration": 8,
"resolution": "720p",
"seed": 42,
"generation_type": "reference-to-video",
"video_urls": [
"https://example.com/source.mp4"
],
"aspect_ratio": "adaptive"
}
}'الاستعلام عن مهمة
GET https://api.seevio.ai/v1/tasks/{taskId}استبدل معرف المثال بـ taskId المسترجع من عملية الإنشاء. تعيد الاستعلامات فقط المهام المملوكة لمستخدم مفتاح API؛ وتعيد المعرفات غير المعروفة أو التي لا يمكن الوصول إليها خطأ HTTP 404.
استعلم كل 10–20 ثوانٍ كخطوة أولى، وتراجع مؤقتًا عند تلقي HTTP 429، وتوقف عندما تصبح الحالة completed أو failed. يُفضل استخدام خطاطيف الويب (webhooks) في بيئة الإنتاج. يقوم كل مثال كود أدناه باستعلام واحد.
curl --fail-with-body https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
-H "Authorization: Bearer $SEEVIO_API_KEY"| الحالة | الوصف والقيود |
|---|---|
queued | تم القبول وفي انتظار التقديم. |
generating | عملية التوليد قيد المعالجة حاليًا. |
completed | نجاح نهائي. قم بتنزيل data.results قبل انتهاء الصلاحية. |
failed | فشل نهائي. تحقق من failed_reason و billing_status. |
| الحقل | النوع | الوصف والقيود |
|---|---|---|
id | string | معرف المهمة. هذا هو taskId المسترجع من استجابة الإنشاء. |
created_at | number | وقت إنشاء المهمة بثواني Unix. |
model | string | معرف النموذج العام المستخدم لهذه المهمة. |
billing_status | string | reserved (محجوز)، charged (مخصوم)، refunded (مسترد)، أو refund_failed (فشل الاسترد). |
credits | number | الأرصدة المحجوزة لهذه المهمة. يتم الاحتفاظ بهذه القيمة بعد الاسترداد؛ تحقق من billing_status لمعرفة النتيجة النهائية للفوترة. |
failed_reason | string | null | سبب الفشل للمهام الفاشلة؛ ويكون null في الحالات الأخرى. تحذف استجابات الاستعلام الفاشلة حقل data. |
data | object | يكون متواجدًا في استعلامات المهام غير الفاشلة. يحتوي على تفاصيل المخرجات والمعالجة. |
data.results | string[] | مصفوفة روابط الفيديو. وتكون فارغة حتى الاكتمال أو بعد انتهاء صلاحية الفيديو. |
data.video_expires_at | string | null | وقت انتهاء صلاحية الفيديو كطابع زمني بتنسيق ISO 8601، أو null قبل توفره. احفظ النتيجة قبل هذا الوقت. |
data.last_frame_url | string | null | رابط الإطار الأخير عند طلبه وتوفره، وإلا يكون null. |
data.processing_time | number | null | مدة معالجة المهمة بالثواني عند توفرها، وإلا ستكون القيمة فارغة (null). |
مهمة مكتملة: استجابة الاستعلام مع نتائج الفيديو
عندما ترجع نتيجة الاستعلام status=completed، فهذا يعني أن عملية إنشاء الفيديو قد انتهت بنجاح. يمكنك قراءة روابط الفيديو من data.results وتنزيلها قبل حلول تاريخ data.video_expires_at. تشير القيمة billing_status=charged إلى أنه تم خصم الرصيد المحجوز بالفعل.
{
"id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
"created_at": 1788652800,
"model": "seedance-2-5-flash",
"is_draft": false,
"draft_task_id": null,
"status": "completed",
"billing_status": "charged",
"credits": 50,
"failed_reason": null,
"data": {
"results": [
"https://cdn.seevio.ai/api/videos/example.mp4"
],
"video_expires_at": "2026-09-07T00:00:00Z",
"last_frame_url": null,
"processing_time": 48
}
}مهمة فاشلة: استجابة الاستعلام مع تفاصيل الفشل والفوترة
عندما ترجع نتيجة الاستعلام status=failed، فهذا يعني أن عملية الإنشاء قد انتهت دون نجاح. يمكنك قراءة سبب الفشل من failed_reason وحالة الفوترة من billing_status لمعرفة تفاصيل عملية الاسترداد. في هذا المثال، تعني refunded أنه تمت إعادة الرصيد المحجوز. يحتفظ الحقل credits بالقيمة الأصلية المحجوزة، ولا تتضمن الاستجابة أي بيانات في data.
{
"id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
"created_at": 1788652800,
"model": "seedance-2-5-flash",
"is_draft": false,
"draft_task_id": null,
"status": "failed",
"billing_status": "refunded",
"credits": 50,
"failed_reason": "provider_failed"
}خطاطيف الويب (Webhooks)
اضبط callback_url في طلب الإنشاء لتلقي طلب JSON POST عند اكتمال المهمة أو فشلها. يجب إرجاع استجابة بترميز 2xx في غضون 15 ثانية. تتم إعادة المحاولة للإرسال الفاشل؛ لذا يرجى معالجة الطلبات المتكررة بشكل متطابق (idempotently) باستخدام معرف المهمة.
يجب أن تدعم نقطة نهاية الاستدعاء الذاتي (Callback endpoint) استقبال طلبات من نوع POST مع نص طلب بتنسيق JSON (Content-Type: application/json).
إنشاء مهمة مع تعيين خطاف الويب (callback)
curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
-H "Authorization: Bearer $SEEVIO_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"model": "seedance-2-5-flash",
"input": {
"prompt": "A cat surfing at sunset, cinematic lighting",
"duration": 5,
"resolution": "720p",
"seed": 42,
"generation_type": "text-to-video",
"aspect_ratio": "16:9",
"generate_audio": true
},
"callback_url": "https://example.com/webhooks/seevio"
}'اكتملت المهمة: بيانات الاستدعاء الذاتي الناجح
عند نجاح عملية الإنشاء، ستحتوي استجابة الاستدعاء الذاتي على status=completed. استخدم المعرّف (id) لتحديد المهمة، وdata.results للحصول على روابط الفيديو. يُرجى تنزيل النتائج وحفظها قبل تاريخ صلاحية الفيديو الموضح في data.video_expires_at.
يشير created_at إلى وقت إنشاء الحدث، وtask_created_at إلى وقت إنشاء المهمة، بالثواني وفق Unix. تعرض الأمثلة الحقول الموصى بها؛ وقد تتضمن الاستجابات حقولاً إضافية.
{
"id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
"created_at": 1788652848,
"model": "seedance-2-5-flash",
"status": "completed",
"task_created_at": 1788652800,
"billing_status": "charged",
"credits": 50,
"failed_reason": null,
"data": {
"results": [
"https://cdn.seevio.ai/api/videos/example.mp4"
],
"video_expires_at": "2026-09-07T00:00:00Z",
"last_frame_url": null,
"processing_time": 48
}
}فشلت المهمة: بيانات استدعاء ذاتي غير ناجح
عند فشل عملية الإنشاء، ستحتوي استجابة الاستدعاء الذاتي على status=failed. استخدم المعرّف (id) لتحديد المهمة، وfailed_reason لمعرفة سبب الفشل، وcredits_refunded لمعرفة عدد الرصيد المسترد.
{
"id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
"created_at": 1788652848,
"model": "seedance-2-5-flash",
"status": "failed",
"task_created_at": 1788652800,
"billing_status": "refunded",
"credits": 50,
"failed_reason": "provider_failed",
"credits_refunded": 50
}مثال للمستقبل (Receiver)
export async function POST(request: Request) {
const callbackData = await request.json();
if (callbackData.status === "completed") {
const videoUrls = callbackData.data.results;
// Save the video URLs and mark this task as completed in your application.
console.log(callbackData.id, videoUrls);
}
if (callbackData.status === "failed") {
const { failed_reason, credits_refunded } = callbackData;
// Record the failure reason and refunded credits for this task.
console.error(callbackData.id, failed_reason, credits_refunded);
}
return new Response(null, { status: 200 });
}يقرأ نموذج Next.js هذا نص استجابة JSON للتعامل مع المهام المكتملة والفاشلة مباشرةً. يُرجى إضافة ميزة الحفظ الدائم وتجنب تكرار معرفات المهام (Task-ID) في تطبيقك، مع جدولة المهام البطيئة في قائمة انتظار قبل تأكيد الاستدعاء الذاتي.
متطلبات الوسائط والقيود
- يجب أن تكون جميع روابط الوسائط وخطاطيف الويب روابط HTTPS عامة. تجنب الاستضافة المحلية (localhost)، وعناوين IP الخاصة، والملفات التي تتطلب ملفات تعريف ارتباط (cookies) أو تسجيل دخول. يجب أن تؤدي روابط الفيديوهات/الصوتيات المرجعية إلى وسائط قابلة للقراءة مباشرة.
- في وضع reference-to-video، قدم مرجعًا واحدًا على الأقل، بما لا يتجاوز 30 صور، و 10 فيديوهات، و 10 ملفات صوتية، وبإجمالي لا يتجاوز 50 من المواد مجتمعة. يجب ألا تزيد المدة الإجمالية للفيديو والمدة الإجمالية للصوت عن 30 ثانية لكل منهما.
- يتجاهل وضع text-to-video كافة مراجع الوسائط. ويمرر وضع image-to-video صور الإطار الأول/الأخير فقط ويتجاهل مراجع الفيديو والصوت. استخدم reference-to-video لدمج الوسائط.
- يجب أن تتراوح مدة كل فيديو وصوت مرجعي بين 2 و 30 ثانية. لأمثلة تعديل الفيديو، استخدم مقاطع مصدر لا تقل عن 4 ثوانٍ.
متطلبات الصور
- يجب ألا يتجاوز حجم الصورة الواحدة 30 ميجابايت.
- الصيغ المدعومة: jpeg، png، webp، bmp، tiff، gif.
- نسبة العرض إلى الارتفاع: من 0.4 إلى 2.5 كحد أقصى.
- يجب أن يتراوح كل من العرض والارتفاع بين 300 و6,000 بكسل.
متطلبات الفيديو
- الصيغ المدعومة: mp4، mov.
- يجب ألا يتجاوز حجم مقطع الفيديو الواحد 100 ميجابايت.
- معدل الإطارات: من 24 إلى 60 إطاراً في الثانية.
- نسبة العرض إلى الارتفاع: من 0.4 إلى 2.5 كحد أقصى.
- إجمالي البكسلات (العرض × الارتفاع): من 407,696 إلى 8,295,044 بكسل. على سبيل المثال، 614 × 664 = 407,696 و3,326 × 2,494 = 8,295,044. هذه أمثلة توضيحية لإجمالي عدد البكسلات وليست أبعاداً ثابتة للعرض والارتفاع.
متطلبات الملفات الصوتية
- الصيغ المدعومة: wav، mp3.
- يجب ألا يتجاوز حجم الملف الصوتي الواحد 15 ميجابايت.