الانتقال إلى الوثائق
في هذه الصفحة

Seedance 2.5 Flash

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

معرف النموذج في الـ API: seedance-2-5-flash

عملية التوليد غير متزامنة. احفظ الـ taskId الذي يتم إرجاعه عند إنشاء المهمة، ثم استعلم عن حالتها أو استقبل النتيجة عبر خطاف الويب.

الإمكانيات

يدعم نموذج Seedance 2.5 Flash دقة 480p و 720p، وتعتبر دقة 720p هي الدقة الافتراضية. لا يدعم هذا النموذج دقة 1080p، أو 4k، أو معاينات Draft، أو إنشاء فيديو نهائي انطلاقًا من Draft.
الميزةالقيم المدعومة
دقة المخرجات480p · 720p
مدة المخرجات٤–30 ثوانٍ
نسبة العرض إلى الارتفاع16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptive
الصور المرجعيةحتى 30 صور
الفيديوهات المرجعيةحتى 10 مقاطع فيديو
الملفات الصوتية المرجعيةحتى 10 ملفات صوتية
كافة المراجع مدمجةحتى 50 من الملفات المرجعية إجمالاً
المدة الإجمالية لكل مجموعة فيديو/صوت30 ثانية
seed-1 إلى 2147483647
يقبل أيضًا القيمة duration=-1 في وضع مرجع إلى فيديو؛ انظر تفاصيل تعديل الفيديو والأسعار أدناه. لا يقبل وضع image-to-video سوى adaptive؛ اترك هذا الحقل فارغًا أو اضبطه على adaptive.

الأسعار والأرصدة

يتم احتساب تكلفة توليد الفيديو بالنقاط بناءً على مدة الفيديو الخاضعة للفوترة بالثواني. في حال عدم وجود فيديو مدخل، تكون المدة الخاضعة للفوترة هي مدة الفيديو الناتج؛ أما في حال وجود فيديو مدخل، فتشمل المدة أيضاً مدة الفيديو المرجعي.

يوضح الجدول أدناه النقاط المحتسبة لكل ثانية، وليس التكلفة الإجمالية للمهمة. تعتمد التعريفة على النموذج المستخدم، ودقة الفيديو الناتج، وما إذا كان قد تم إدخال مقاطع فيديو مرجعية في وضع "المرجع إلى فيديو" (reference-to-video). يرجى الاطلاع على المعادلات والأمثلة الموضحة أسفل الجدول لمعرفة كيفية حساب التكلفة الإجمالية.

دقة المخرجاتبدون إدخال فيديومع إدخال فيديو
480p7 رصيد/الثانية5 رصيد/الثانية
720p10 رصيد/الثانية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.ai
Authorization: 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 مطلوب في وضع image-to-video. يتطلب وضع reference-to-video مرجعًا واحدًا على الأقل من بين image_urls و video_urls و audio_urls.

يرجى توفير 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-video

text-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 الخاصة بالوسائط في example.com بملفات HTTPS الخاصة بك والمتاحة للعامة. عناوين URL التجريبية مخصصة لتوضيح هيكلية الطلب وليست أصولاً صالحة للتنزيل.

نص إلى فيديو

التوليد من وصف نصي. لا يتم تمرير عناوين 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"
    ]
  }
}'

تعديل الفيديو

لتعديل الفيديو في Seedance 2.5 Flash، يجب ضبط المدة (duration) على -1 وتحديد نسبة العرض إلى الارتفاع (aspect_ratio) لتكون متكيفة (adaptive). كلا الإعدادين مطلوبين لتجنب فشل عملية الإنشاء.

صف التعديل المطلوب وقدم الفيديو المصدر. اضبط 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"
  }
}'

تمديد الفيديو

بالنسبة لملحق الفيديو Seedance 2.5 Flash، يجب ضبط نسبة العرض إلى الارتفاع (aspect_ratio) على الخيار التكيفي (adaptive)؛ وإلا فقد يفشل التوليد. اضبط مدة الفيديو (duration) بشكل طبيعي حسب الطول المطلوب للمقطع الناتج ضمن النطاق المدعوم؛ لا داعي لاستخدام القيمة -1.

صف كيف يجب أن يستمر الفيديو المصدر. استخدم نسبة العرض إلى الارتفاع 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.
الحقلالنوعالوصف والقيود
idstring
معرف المهمة. هذا هو taskId المسترجع من استجابة الإنشاء.
created_atnumber
وقت إنشاء المهمة بثواني Unix.
modelstring
معرف النموذج العام المستخدم لهذه المهمة.
billing_statusstring
reserved (محجوز)، charged (مخصوم)، refunded (مسترد)، أو refund_failed (فشل الاسترد).
creditsnumber
الأرصدة المحجوزة لهذه المهمة. يتم الاحتفاظ بهذه القيمة بعد الاسترداد؛ تحقق من billing_status لمعرفة النتيجة النهائية للفوترة.
failed_reasonstring | null
سبب الفشل للمهام الفاشلة؛ ويكون null في الحالات الأخرى. تحذف استجابات الاستعلام الفاشلة حقل data.
dataobject
يكون متواجدًا في استعلامات المهام غير الفاشلة. يحتوي على تفاصيل المخرجات والمعالجة.
data.resultsstring[]
مصفوفة روابط الفيديو. وتكون فارغة حتى الاكتمال أو بعد انتهاء صلاحية الفيديو.
data.video_expires_atstring | null
وقت انتهاء صلاحية الفيديو كطابع زمني بتنسيق ISO 8601، أو null قبل توفره. احفظ النتيجة قبل هذا الوقت.
data.last_frame_urlstring | null
رابط الإطار الأخير عند طلبه وتوفره، وإلا يكون null.
data.processing_timenumber | 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 ميجابايت.