Seedance 2.5

الإمكانيات

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

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

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

• بدون إدخال فيديو: ثواني المخرجات × سعر عدم وجود فيديو.
• مع إدخال فيديو: (ثواني المخرجات + ثواني الفيديو المرجعي المقاسة) × سعر وجود فيديو. يقوم الخادم بقياس المدة الإجمالية للفيديو المرجعي ويقربها لأعلى إلى أقرب ثانية كاملة قبل الاحتساب.
• تطبق مراجع الصور أو الصوت وحدها سعر عدم وجود فيديو. لا يطبق سعر فوترة الفيديو المرجعي إلا في وضع مرجع إلى فيديو عند توفير مراجع فيديو.

تُحجز الأرصدة عند تقديم الطلب وتُخصم عند النجاح. تدخل المهام الفاشلة أو التي انتهت مهلتها في مسار استرداد الأموال. تعني حالة الفوترة refund_failed أن عملية الاسترداد لم تكتمل؛ يرجى مراجعة سجلات الـ API أو الاتصال بالدعم.

المصادقة

أنشئ مفتاح API في لوحة التحكم. يظهر المفتاح الكامل مرة واحدة فقط. احتفظ به في خادمك وأرسله كرمز حامل (Bearer token) مع كل طلب.

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",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "generation_type": "text-to-video",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }
}'

مثال على استجابة إنشاء المهمة

بعد قبول الطلب أعلاه، ترجع واجهة برمجة التطبيقات (API) استجابة JSON هذه. يمثل taskId معرف المهمة المستخدم في عمليات الاستعلام اللاحقة عن الحالة؛ بينما يمثل credits عدد النقاط المحجوزة لهذه المهمة. تؤكد هذه الاستجابة إنشاء المهمة بنجاح، ولا تعني أن الفيديو جاهز بعد. يتعين عليك تتبع حالة المهمة بشكل دوري (Poll) أو استخدام Webhook لتلقي نتائج الفيديو.

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 100
}

إنشاء مهمة

أرسل كائن JSON يحتوي على النموذج والمدخلات، بالإضافة إلى callback_url اختياري. حدد دائمًا معرف النموذج الموضح في هذه الصفحة؛ حيث يؤدي حذف النموذج إلى اختيار seedance-2-0 تلقائيًا.

جسم الطلب (Request body)

معلمات الإدخال

يرجى توفير image_urls و video_urls و audio_urls في شكل مصفوفات من سلاسل عناوين URL (string[]). يجب أن يكون كل عنوان URL متوفرًا بشكل عام للوصول إليه عبر بروتوكول HTTPS، بما في ذلك الوسائط التي تم تجاهلها بواسطة الوضع المحدد.

يجب أن تكون الحقول المنطقية قيم JSON true أو false، وليست نصوصًا أو أرقامًا.

استجابة الإنشاء

تعيد استجابة HTTP 200 المعرف taskId (نص) والرصيد credits (رقم). هذا تأكيد على إنشاء المهمة وليس اكتمالها. القيمة أدناه تتوافق مع البدء السريع لـ 5 ثوانٍ بدقة 720p.

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 100
}

أوضاع التوليد وأمثلة

نص إلى فيديو

التوليد من وصف نصي. لا يتم تمرير عناوين 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",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "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",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "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",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "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",
  "input": {
    "prompt": "Follow the reference camera movement and keep the character consistent. Use the audio for ambience.",
    "duration": 5,
    "resolution": "720p",
    "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",
  "input": {
    "prompt": "Create a coastal sunrise scene matching the rhythm of this audio.",
    "duration": 5,
    "resolution": "720p",
    "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",
  "input": {
    "prompt": "Edit the source video: change the character’s coat to blue and preserve the camera movement.",
    "duration": -1,
    "resolution": "720p",
    "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",
  "input": {
    "prompt": "Continue the camera movement from the source video, revealing a forest clearing.",
    "duration": 8,
    "resolution": "720p",
    "generation_type": "reference-to-video",
    "video_urls": [
      "https://example.com/source.mp4"
    ],
    "aspect_ratio": "adaptive"
  }
}'

الاستعلام عن مهمة

استبدل معرف المثال بـ 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"

مهمة مكتملة: استجابة الاستعلام مع نتائج الفيديو

عندما ترجع نتيجة الاستعلام status=completed، فهذا يعني أن عملية إنشاء الفيديو قد انتهت بنجاح. يمكنك قراءة روابط الفيديو من data.results وتنزيلها قبل حلول تاريخ data.video_expires_at. تشير القيمة billing_status=charged إلى أنه تم خصم الرصيد المحجوز بالفعل.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652800,
  "model": "seedance-2-5",
  "status": "completed",
  "billing_status": "charged",
  "credits": 100,
  "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",
  "status": "failed",
  "billing_status": "refunded",
  "credits": 100,
  "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",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "generation_type": "text-to-video",
    "aspect_ratio": "16:9",
    "generate_audio": true
  },
  "callback_url": "https://example.com/webhooks/seevio"
}'

تختلف بيانات خطاطيف الويب عن استجابات استعلام المهام: فهي تحذف billing_status و credits؛ وتكون تفاصيل الفشل داخل data.failed_reason و data.credits_refunded. حقل created_at في خطاف الويب يمثل وقت إنشاء الحدث بثواني Unix.

اكتملت المهمة: بيانات الاستدعاء الذاتي الناجح

عند نجاح عملية الإنشاء، ستحتوي استجابة الاستدعاء الذاتي على status=completed. استخدم المعرّف (id) لتحديد المهمة، وdata.results للحصول على روابط الفيديو. يُرجى تنزيل النتائج وحفظها قبل تاريخ صلاحية الفيديو الموضح في data.video_expires_at.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652800,
  "model": "seedance-2-5",
  "status": "completed",
  "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) لتحديد المهمة، وdata.failed_reason لمعرفة سبب الفشل، وdata.credits_refunded لمعرفة عدد الرصيد المسترد.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652800,
  "model": "seedance-2-5",
  "status": "failed",
  "data": {
    "failed_reason": "provider_failed",
    "credits_refunded": 100
  }
}

مثال للمستقبل (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.data;
    // 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 ثوانٍ.

الأخطاء

تحتوي أخطاء HTTP على كائن خطأ يضم الرمز (code) والرسالة (message). يمكن للمهمة المقبولة بنجاح أن تفشل لاحقًا؛ لذا استعلم عن المهمة أو تعامل مع خطاك الراجع للفشل.

{
  "error": {
    "code": "invalid_request",
    "message": "input.prompt is required."
  }
}

حدود معدل الطلبات

إنشاء المهام: يتيح كل مفتاح واجهة برمجة تطبيقات (API key) ما يصل إلى 100 طلب في الدقيقة افتراضيًا. حدود معدل الطلبات المخصصة غير متوفرة حاليًا.

الاستعلام عن المهام: يتيح كل مفتاح واجهة برمجة تطبيقات (API key) ما يصل إلى 120 طلبًا في الدقيقة افتراضيًا. ويتم احتساب طلبات الاستعلام وطلبات إنشاء المهام بشكل منفصل.