Seedance 2.5 API: دليل المطوّر لنقاط النهاية والمصادقة وتوليد الفيديو

Seedance 2.5 API: دليل المطوّر لنقاط النهاية والمصادقة وتوليد الفيديو

Seedance 2.5 هو نموذج فيديو طويل الأمد ومتعدد الأنماط، مما يعني أنّ الواجهة (API) التي تشغّله غير متزامنة (async)، وليست طلبًا واحدًا بطلب واستجابة. أنت تُرسِل مهمة توليد، وتُقترع للتأكد من اكتمالها، ثم تُنزِّل النتيجة. متى فهمت هذا النمط، إلى جانب نقطة النهاية، وترويسة المصادقة، وحقول الحمولة الخاصة بالمدة والدقة والمراجع، يصبح ما تبقّى مباشرًا.

يستعرض هذا الدليل عقد Seedance 2.5 API كاملًا: نقطة النهاية، والمصادقة، ونص الطلب، والاقتراع غير المتزامن، وأمثلة curl و Python جاهزة للتشغيل. وهو يستهدف مسار PixMind لمنصة api-platform، الذي يعكس عقد ByteDance للنموذج نفسه. ويضيف الدليل كذلك مقارنة جنبًا إلى جنبٍ لأنماط كل من Seedance 2.0 API و Kling API، ودراسة حالة كاملة لخط أنابيب إنتاج متكامل، وموارد للمطوّرين من أطراف ثالثة، وقسم أسئلة شائعة موسّع يغطّي حدود المعدل، والتزامن، وويبهوك، والتحقق من الأرصدة. جميع تفاصيل نقاط النهاية والمصادقة موثّقة مقابل الواجهة الخلفية الحيّة حتى تاريخ 2026-07-31.

نظرة شاملة على نموذج Seedance 2.5

أبرز النقاط

• نقطة النهاية: POST /api-platform/v1/generations لإنشاء مهمة، وGET /api-platform/v1/task/{task_id} لاقتراع النتيجة.
• المصادقة: Authorization: Bearer <API_KEY> (أو الترويسة X-API-Key)؛ أنشئ مفتاحًا بنطاق فيديو من لوحة تحكم PixMind.
• الحمولة: { model, prompt, duration, resolution, aspect_ratio, reference_images, reference_videos, generate_audio }.
• العملية غير متزامنة: تستجيب دالة الإنشاء بـ taskId؛ تُقترع حتى يصبح status بقيمة ready، ثم تقرأ videoUrl.
• البنية عبر المزوّدين: كلٌّ من Seedance 2.5 و Seedance 2.0 و Kling تستخدم نمط «أرسل ثم اقترع» نفسه. تختلف في مسار نقطة النهاية، وميزانية المراجع، وأسماء الحقول.
• نمط الإنتاج: أضِف Idempotency-Key عند الإنشاء، واقترع بعدد محدود من المحاولات مع تراجع متزايد، وتحقّق من الأرصدة قبل الإرسال، واعتمد على مسار أرخص للتكرار.
• الوصول إلى الـ API قريبًا على PixMind؛ المسار موثّق وجاهز، والاتصال بالواجهة الخلفية في مرحلة الإنجاز النهائية.

المتطلبات المسبقة: الحصول على مفتاح API

تُصادَق استدعاءات Seedance 2.5 بمفتاح API مرتبط بنطاق حسابك. أنشئ واحدًا من لوحة تحكم PixMind لمنصة api-platform وخزّنه بأمان؛ تعامل معه كأيّ سرّ. حمّل المفتاح من متغيّر بيئة داخل الكود بدلًا من تثبيته في نظام التحكم بالنسخ:

export PIXMIND_API_KEY="pk-xxxxxxxxxxxxxxxx"

أنشئ مفتاح API

على PixMind، تكون صلاحيات المفتاح مرتبطة بنطاق كل عبء عمل (صورة / فيديو). تأكّد من تفعيل صلاحية الفيديو على مفتاحك قبل استدعاء Seedance 2.5.

ملاحظة للمطوّر: دوِّر المفاتيح بحسب البيئة (تطوير / staging / إنتاج)، وقيّد كل مفتاح بأدنى عبء عمل يحتاجه. مفتاح staging بنطاق فيديو فقط لا يمكن أن يتسرّب إلى خط أنابيب الصور، مما يحدّ من نطاق الضرر إذا انكشف المفتاح. أعد إصدار المفاتيح على إيقاع ثابت وسجّل طابع آخر استخدام زمني كي يسهل العثور على المفاتيح الخاملة وإبطالها.

شاهد: شرح كامل لسير عمل Seedance 2.5

أسرع طريقة لفهم ترقية 2.5 قبل كتابة الكود هي مشاهدة لقطات العرض الرسمية وتحليل المجتمع. يغطّي شرحا العمل هذين التوليد الأصلي بمدة 30 ثانية، وإخراج 4K، والتحرير على مستوى المنطقة، وسير العمل مع 50 مرجعًا الذي تعرّفه الواجهة:

بديل noscript: عرض Seedance 2.5 على YouTube، يغطّي اللقطات الأصلية بمدة 30 ثانية، والتحرير على مستوى المنطقة، و50 مرجعًا متعدد الأنماط.

ولنقاش تحريري أعمق لما تعنيه ترقيات سير العمل لخط أنابيب إنتاج، يستحق تحليل «Seedance 2.5 Changes Everything» المشاهدة بجانب المقطع الرسمي:

بديل noscript: Seedance 2.5 Changes Everything على YouTube.

عقد Seedance 2.5 API

نقطة النهاية

إنشاء مهمة توليد:

POST /api-platform/v1/generations

الاقتراع لاكتمال المهمة:

GET /api-platform/v1/task/{task_id}

نقطة نهاية الإنشاء هي بوابة التوليد الموحّدة: تقرأ الحقل model وتُوجِّه الطلب وفقًا له. أرسِل model: "seedance-2.5" ويتولّى المسار خط أنابيب الفيديو.

المصادقة

أرسِل مفتاح الـ API كرمز Bearer (متوافق مع OpenAI SDK):

Authorization: Bearer $PIXMIND_API_KEY

تقبل وسيطة المصادقة كذلك الترويسة X-API-Key إذا كنت تفضّل هذا الشكل. كلاهما مدعوم؛ اختر أحدهما واستخدمه باتساق عبر كود العميل حتى يسهل تتبّع السجلّات وإعادة المحاولة.

نص الطلب

حول المراجع: يقبل Seedance 2.5 ما يصل إلى 50 مدخلًا متعدد الأنماط في طلب واحد، صورًا وفيديوهات ونصًا وصوتًا مجتمعة. أعطِ كل مرجع دورًا صريحًا واحدًا (الهوية، الشكل، الحركة، لوحة الألوان، الإيقاع) واحذف الأصول التي تتنافس على الخاصية ذاتها.

كيف تقارن Seedance 2.5 API بكلٍّ من Seedance 2.0 و Kling

تتشارك معظم واجهات توليد الفيديو الحالية البنية غير المتزامنة نفسها: طلب POST واحد لإنشاء مهمة، وطلب GET واحد للاقتراع حتى الاكتمال. وتكمن الاختلافات في مسار نقطة النهاية، واصطلاح المصادقة، وميزانية المراجع، وأسماء الحقول في الحمولة. يعرض الجدول التالي هذه الاختلافات للواجهات الثلاث التي يقارنها المطوّرون غالبًا عند التخطيط للتكامل.

ملاحظة مباشرة: البنية غير المتزامنة المشتركة تعني أنّ كود العميل قابل لإعادة الاستخدام عبر المزوّدين. لُفّ حلقة الإنشاء والاقتراع في دالة واحدة generate_video(model, payload) وبدّل مُعرِّف النموذج فقط، فتتمكن من إجراء اختبار A/B على Seedance 2.5 و Seedance 2.0 Fast و Kling من الإطار نفسه. هذا هو أرخص طريق لاختيار المسار المناسب لكل لقطة دون إعادة كتابة كود التكامل.

الخلاصة العملية: إذا كان فريقك قد بنى عميل اقتراع لـ Seedance 2.0 بالفعل، فإنّ اعتماد 2.5 هو مجرد تغيير في سلسلة النموذج، مع إضافة حقول المراجع والمدة الجديدة. لست بحاجة إلى إعادة تصميم التكامل.

مقارنة Seedance 2.5 مقابل Kling

الخطوة 1: إنشاء مهمة توليد

إليك طلب إنشاء بأدنى حدٍّ، مقطع بدقة 720p و 16:9 ومدة 5 ثوانٍ مع موجز نصّي. الترويسة Idempotency-Key اختيارية لكنها موصى بها لأي إرسال إنتاجي:

curl -X POST https://aihub-admin.aimix.pro/api-platform/v1/generations \
  -H "Authorization: Bearer $PIXMIND_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "A courier in a yellow jacket cycling through a neon-lit rainy Tokyo street at night, tracking shot, cinematic, no text",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

تُعيد الاستجابة الناجحة مُعرِّف مهمة. أنت لا تحصل على الفيديو هنا، بل على مقبض للاقتراع:

{
  "code": 1000,
  "data": {
    "taskId": "47264",
    "type": "video",
    "status": "processing"
  }
}

إذا ظهر لك code: 400 مع رسالة «النموذج غير موجود أو غير مُعدّ»، فهذا يعني أنّ مسار seedance-2.5 لم يُفعَّل بعد على نقطة النهاية هذه. هذه هي حالة «قريبًا» على PixMind أثناء إنجاز الاتصال.

الخطوة 2: اقتراع المهمة حتى تصبح جاهزة

توليد الفيديو غير متزامن. اقترع نقطة نهاية المهمة باستخدام taskId من الخطوة 1:

curl -X GET https://aihub-admin.aimix.pro/open-api/v1/task/47264 \
  -H "Authorization: Bearer $PIXMIND_API_KEY"

يتنقّل الحقل status بين pending ثم processing ثم ready. اقترع كل 3 إلى 5 ثوانٍ. وعندما تصبح المهمة جاهزة، تتضمّن الاستجابة رابط الفيديو النهائي:

{
  "code": 1000,
  "data": {
    "taskId": "47264",
    "status": "ready",
    "progress": 100,
    "videoUrl": "https://.../seedance-2-5-47264.mp4",
    "coverUrl": "https://.../seedance-2-5-47264-cover.webp"
  }
}

حالات الفشل النهائية هي failed و error و canceled و cancelled. تعامل معها وأظهر الحقل description في سجلّاتك.

ملاحظة للمطوّر: فترات اقتراع من 3 إلى 5 ثوانٍ مقبولة لمهمة واحدة، لكنها تتضاعف بسرعة عند التوسّع. لطابور من 20 مهمة، يُفضَّل حلقة مُرسِل واحدة تقترع كل مهمة مفتوحة مرة واحدة في كل دورة، مع تراجع متزايد أسيًّا (5 ثوانٍ، 5 ثوانٍ، 10 ثوانٍ، 15 ثانية، بحد أقصى 30 ثانية) كلما تقدّمت المهمة في العمر. هذا يحافظ على حجم الطلبات بأدب دون تمديد زمن الاستجابة p99 للدفعة كلها.

الخطوة 3: تنزيل النتيجة واستخدامها

بمجرّد أن يصبح status بقيمة ready، نزّل videoUrl (و coverUrl اختياريًا لإطار الملصق). الملف بصيغة MP4 قياسية؛ بَرمِجه أو استضِفه أو ادمجه حسب حاجات تطبيقك.

بالنسبة لصفحة هبوط على الويب، ستضغطه عادةً إلى مقطع H.264 بمدة 8 إلى 10 ثوانٍ مع fast-start للتشغيل التلقائي، وتستخرج ملصق WebP، وتستضيف كليهما على شبكة CDN خاصة بك. (يستضيف PixMind وسائط حالات Seedance 2.5 على cdn.pixmind.io.) لا تربط مباشرًا بـ videoUrl المستضاف على الواجهة في الإنتاج، لأنّ رابط الواجهة ليس مضمونًا أن يبقى.

مثال Python الكامل

إليك مقطع Python كامل وقابل للتشغيل، ينشئ مهمة، ويقترع حتى تصبح جاهزة، ويطبع رابط الفيديو. يضيف Idempotency-Key، وحلقة إعادة محاولة محدودة، وسقفًا زمنيًا، وهي الأشياء الثلاثة التي يحتاجها عميل إنتاجي والتي يهملها عادةً مثال «مرحبًا بالعالم»:

import time
import uuid
import requests

API_BASE = "https://aihub-admin.aimix.pro"
API_KEY = "your-pixmind-api-key"  # scope: video

GEN = f"{API_BASE}/api-platform/v1/generations"
TASK = f"{API_BASE}/open-api/v1/task"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

# 1. Create with an idempotency key so a retry does not start a second billed task
payload = {
    "model": "seedance-2.5",
    "prompt": "A 30-second continuous hero shot: a character walking through a neon city that flows into a product reveal",
    "duration": 30,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "generate_audio": True,
}
headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())}
create = requests.post(GEN, headers=headers, json=payload, timeout=30).json()
task_id = create["data"]["taskId"]
print(f"Task created: {task_id}")

# 2. Poll with bounded retries and gentle backoff
max_attempts, delay = 100, 5
for attempt in range(max_attempts):
    time.sleep(delay)
    t = requests.get(f"{TASK}/{task_id}", headers=HEADERS, timeout=15).json()
    status = t["data"]["status"].lower()
    print(f"attempt={attempt + 1} status={status} progress={t['data'].get('progress', 0)}%")
    if status in ("ready", "succeeded", "completed"):
        print("Video URL:", t["data"]["videoUrl"])
        break
    if status in ("failed", "error", "canceled", "cancelled"):
        raise RuntimeError(f"Task failed: {t['data']}")
    delay = min(delay + 2, 30)  # backoff, capped at 30s
else:
    raise TimeoutError(f"Task {task_id} did not finish in {max_attempts * 5}s")

دراسة حالة متكاملة: خط أنابيب فيديو منتج بمدة 30 ثانية

هذا هو الجزء الذي تتخطّاه أدلة الواجهات غالبًا: كيف يربط فريق حقيقي العقد أعلاه في خط أنابيب إنتاج قابل للتكرار. السيناريو هو فريق إبداعي من أربعة أشخاص في علامة D2C يُنتج فيديو بطولًا بمدة 30 ثانية لإطلاق منتج، بميزانية ثابتة وموعد نهائي صارم. النمط التالي هو الشكل الذي يُسلَّم باستمرار في الوقت المحدد.

نظرة عامة على خط الأنابيب

يقسّم الفريق العمل إلى أربع مراحل: التكرار (اختبارات A/B رخيصة على Seedance 2.0 Fast)، والتوليد النهائي (تشغيل واحد لـ Seedance 2.5 بدقة 1080p / 30 ثانية)، والمراجعة والتحرير الموضعي (إعادة توليد موجَّهة على Seedance 2.5)، والتسليم (ترميز، ملصق، رفع إلى CDN). كل مرحلة تستخدم كود العميل نفسه؛ ما يتغيّر فقط هو مُعرِّف النموذج والحمولة. هذا الفصل هو ما يجعل خط الأنابيب قابلًا للتكرار عبر الحملات.

توزيع المراجع

قبل أي استدعاء للواجهة، يُسنِد الفريق لكل مرجع دورًا صريحًا واحدًا، مُسجَّلًا في جدول بيانات مشترك كي يبقى الموجز والحمولة متزامنين. خمسة مراجع من ميزانية الـ 50 مدخلًا، كلٌّ بوظيفة واحدة:

يربط الموجز كل عنصر صراحةً: «أبقِ الشخصية من @Image 1 دون تغيير؛ طابِق المنتج في @Image 2؛ استخدم @Video 1 لحركة الكاميرا فقط؛ عايِر القطعات مع @Audio 1». هذا الربط هو العقد بين التوجيه الإبداعي وحمولة الواجهة. إذا لم يُسنَد دورٌ لمرجع، فلا يدخل في الطلب.

مرحلة التكرار (التحكم بالتكلفة)

قبل الإنفاق على تشغيل 2.5 بمدة 30 ثانية، يتحقّق الفريق من الموجز والمراجع على Seedance 2.0 Fast بمدة 5 ثوانٍ ودقة 720p. هذا هو الاستدعاء نفسه POST /api-platform/v1/generations مع model: "seedance-2.0-fast". تكلف ثلاث تكرارات جزءًا صغيرًا من تشغيل 2.5 واحد، وتكشف تعارضات المراجع قبل الالتزام بالميزانية. يُسجِّل المُرسِل taskId لكل تكرار وحالته وعدد الثواني المنقضية كي يتمكّن القائد الإبداعي من مقارنة النسخ جنبًا إلى جنب.

ملاحظة مباشرة: الفرق التي تتخطّى هذه المرحلة وتنتقل مباشرة إلى توليد 2.5 بمدة 30 ثانية تحرق عادةً ثلاثة أو أربعة تشغيلات بسعر كامل لإصلاح تعارضات في الموجز كان يمكن التقاطها على Fast. مرحلة التكرار هي الجزء ذو أعلى عائد في خط الأنابيب، والفرق التي تُسلِّم بانتظام هي التي تتعامل معها كإلزامية.

التوليد النهائي (Seedance 2.5 بمدة 30 ثانية / دقة 1080p)

عندما يؤكّد تكرار Fast أنّ الموجز يُقرأ بشكل سليم، يُرسِل الفريق التوليد الحقيقي: model: "seedance-2.5" و duration: 30 و resolution: "1080p"، مع إرفاق المراجع الخمسة كاملةً والموجز المُرابَط بالأدوار. يتضمّن استدعاء الإنشاء Idempotency-Key كي لا تبدأ إعادة محاولة شبكية من مشغّل CI مهمة ثانية محاسَبة. يراجع القائد الإبداعي سجلّ إرسال taskId النهائي قبل أن يُسمَح للمُرسِل بالالتزام به، وهذا فحص دقيقة واحدة يمنع الأخطاء المطبعية المكلفة في الموجز.

الاقتراع، والأخطاء، والتساوي التام

يقترع مُرسِل واحد المهمة كل 5 ثوانٍ مع تراجع حتى 30 ثانية، بحد أقصى 100 محاولة (نحو 8 دقائق). تُطلِق حالات الفشل النهائية (failed و error) إعادة محاولة واحدة بـ Idempotency-Key جديد فقط إذا أشار الوصف إلى مشكلة عابرة في الواجهة الخلفية. تُعرَض أخطاء المراجع أو الموجز على القائد الإبداعي وتُصحَّح قبل إعادة الإرسال، لا أن تُعاد تجربتها بشكل أعمى. يكتب المُرسِل سطر سجلّ مُنظَّمًا لكل محاولة (مُعرِّف المهمة، الحالة، التقدّم، الثواني المنقضية) كي تكون التكلفة وزمن الاستجابة قابلتين للتدقيق بعد الإطلاق.

التحرير الموضعي

عند المراجعة، يطلب العميل استبدال المنتج على الرف الأيمن في اللقطة النهائية. يُرسِل الفريق مهمة تحرير على مستوى المنطقة تستهدف تلك المنطقة فقط، مع الحفاظ على حركة وهوية باقي المقطع. هذه هي ميزة 2.5 الأكثر قيمة لعملاء العميل: رحلة يوم كامل تُصبح إعادة توليد بـ 10 دقائق. يُبقي خط الأنابيب taskId الأصلي و taskId للتحرير مترابطَين في سجلّ المشروع كي يكون سلف كل إطار مُسلَّم قابلًا للتتبّع.

التسليم

يُنزَّل videoUrl الجاهز، ويُرمَّز إلى H.264 مع fast-start للتشغيل التلقائي على الويب، ويُقرَن بملصق WebP مستخرَج من coverUrl، ويُرفَع إلى شبكة CDN الخاصة بالفريق. تُدفَع الأصول النهائية إلى صفحة الهبوط وتُراجَع إطارًا بإطار (الهوية، الأيادي، أبعاد المنتج، الشعارات، تزامن الصوت) قبل النشر.

الانضباط في التكلفة

يحدّ خط الأنابيب من الإنفاق في ثلاث نقاط. أولًا، تحدث عمليات التكرار على Fast بدلًا من 2.5. ثانيًا، يُلغي فحصٌ مسبَق للأرصدة قبل كل إرسال إلى 2.5 إذا كان رصيد المحفظة أقل من العتبة المختارة للمدة والدقة. ثالثًا، يرفض ميزانية صارمة لكل مهمة في المُرسِل إرسال مهام جديدة بمجرّد بلوغها. تسعير Seedance 2.5 غير منشور، لذا يتعامل الفريق مع أي رقم لكل ثانية كتقدير، ويقرأ المولّد الحيّ للأرصدة الحالية قبل كل حملة.

التعامل مع المراجع متعددة الأنماط البالغ عددها 50

الميزة الرئيسية، ما يصل إلى 50 مدخلًا متعدد الأنماط، تظهر في الحمولة كمصفوفات من الروابط العامة:

{
  "model": "seedance-2.5",
  "prompt": "Keep the character from the first image unchanged; use the video for body motion and the audio for rhythm",
  "duration": 20,
  "resolution": "1080p",
  "aspect_ratio": "16:9",
  "reference_images": ["https://cdn.example.com/character.jpg", "https://cdn.example.com/product.jpg"],
  "reference_videos": ["https://cdn.example.com/motion.mp4"],
  "generate_audio": true
}

يجب أن تكون جميع روابط المراجع قابلة للوصول بشكل عام. أسنِد لكل واحد دورًا واحدًا وصف ذلك الدور في الموجز ("use @Video 1 only for body motion")، كي يعرف النموذج أيّ مدخل يتحكّم بأيّ خاصية.

ملاحظة للمطوّر: تحقّق مسبقًا من أنّ كل رابط مرجع يُعيد HTTP 200 مع نوع المحتوى المتوقَّع قبل الإرسال. وجود 403 واحد على أصل محميّ بـ CDN هو السبب الأكثر شيوعًا لمهام failed في الإنتاج، وهو يُهدر ميزانية توليد كاملة. فحص بطلب HEAD من سطرين في عميلك يمنع فئة الفشل هذه بأكملها. كذلك استخدم روابط مستقرة موجهة بالمحتوى (مثلًا بـ hash أو إصدار في المسار) كي لا يؤدّي استبدال أصل في منتصف الحملة إلى تغيير ما يستقبله النموذج بصمت.

معالجة الأخطاء والتساوي التام

• 401 «مفتاح API غير صالح»، مفتاح خاطئ، أو أنّ المفتاح لا يملك نطاق فيديو. تحقّق من المفتاح وصلاحياته.
• 400 «النموذج غير موجود أو غير مُعدّ»، مسار seedance-2.5 غير مُفعَّل على هذه الواجهة الخلفية بعد. على PixMind هذه هي حالة «قريبًا».
• 4001 «الرصيد غير كافٍ»، الطلب صالح لكن محفظتك لا تملك أرصدة؛ المهمة لا تُنشَأ.
• 429 حد المعدل، تراجَع أسيًّا وأعِد المحاولة؛ تُطبِّق نقطة إنشاء حدودًا للتزامن ومعدّل الطلبات لكل مفتاح. إذا واجهت ذلك بانتظام، تواصل مع الدعم لرفع الحدود أو وزّع الإرسالات على فترات قصيرة.
• 502 / 504 بوابة، عابر؛ أعِد محاولة استدعاء الإنشاء بـ Idempotency-Key نفسه كي يُلغي الخادم الخلفي التكرار ولا تبدأ مهمة ثانية محاسَبة.
• انتهاء مهلة الاقتراع، سُقّ المحاولات (مثلًا 100 × 5 ثوانٍ، نحو 8 دقائق) وتعامل مع المهلة كفشل مع إعادة محاولة واحدة.

بالنسبة للإنتاج، أرسِل ترويسة Idempotency-Key في كل استدعاء إنشاء كي لا تبدأ إعادة محاولة العميل مهمة ثانية محاسَبة. استخدم UUID لكل مهمة منطقية (لا لكل محاولة HTTP)، يُولَّد مرة واحدة ويُخزَّن عندك، كي تُزال تكرارات المهمة المنطقية نفسها عبر إعادات المحاولة وإعادات تشغيل CI وإعادة تشغيل الطابور. النمط هو: ولِّد UUID عندما يقرّر المستخدم (أو مشغّل المهام) إنشاء المهمة، ادمِجه قبل أول استدعاء HTTP، وأعد استخدامه لكل إعادة محاولة لتلك المهمة المنطقية نفسها.

موارد المطوّرين من أطراف ثالثة

العقد أعلاه هو مسار التنفيذ على PixMind. للحصول على سياق أعمق حول النموذج الأساسي من ByteDance وسطح الواجهة الرسمي، هذه هي الموارد التي يلجأ إليها المطوّرون غالبًا، موثّقة حتى 2026-07-31:

• صفحة موارد Seedance 2.5 على BytePlus، ai.byteplus.com/lumina/en/resource/bytedance-seedance-2-5. تأطير ByteDance نفسه لـ 2.5، المتمحوك حول توليد الفيديو الإعلاني وعروض المنتجات. مفيد للسرد القدرات وحالات الاستخدام التي يستهدفها ByteDance نفسه. قائمة موثّقة، 2026-07-31.
• وثائق BytePlus ModelArk API، سطح المطوّر الرسمي لاستدعاء Seedance عبر سحابة ByteDance. راجِع أسماء الحقول والأوضاع عندما تحتاج تأكيد ما يكشفه المسار المتصل، ثم عكس هذه الأسماء في عميلك.
• وثائق Volcengine 火山方舟 (Volcano Engine Ark)، volcengine.com/docs/82379. نقطة النهاية المحلية (الصين) لعائلة النموذج نفسه. نمط «أرسل ثم اقترع» غير المتزامن هو نفسه مسار PixMind؛ تختلف أسماء الحقول وتدفّق المصادقة قليلًا. قائمة موثّقة، 2026-07-31؛ أكّد المسار الحيّ قبل التكامل.
• دليل إعادة إنشاء عروض MakeFun AI، makefun.ai/seedance-2-5-demo-videos/. يشرح إعادة إنشاء سير عمل عروض BytePlus ModelArk الغنيّة بالمراجع. مفيد عندما تريد استنساخ المظهر الرسمي قبل تصميم موجزك الخاص.
• تحليلات المجتمع، تحليل Topview/Medium لـ 2.5، وتغطية Pixo لـ FORCE، والدليل الشامل من ToSea؛ كلها تغطّي ترقيات سير العمل من زاوية تحريرية. مفيدة للسياق، لا لتفاصيل نقاط النهاية؛ أكّد التفاصيل التقنية دائمًا مقابل الواجهة الحيّة.

ملاحظة للمطوّر: أدلة الأطراف الثالثة تتقادم بسرعة. تعامل مع أيٍّ منها كنقطة انطلاق وأكّد مسارات نقاط النهاية، وأسماء الحقول، وتكلفة الأرصدة مقابل المسار المتصل في يوم التكامل. تفاصيل نقاط النهاية والمصادقة في هذا الدليل موثّقة حتى 2026-07-31، لكنّ النموذج لا يزال قيد الطرح، لذا أعد التحقّق قبل إطلاق الإنتاج.

الأسئلة الشائعة عن Seedance 2.5 API

ما هي نقطة نهاية Seedance 2.5 API؟

أنشئ مهمة بـ POST /api-platform/v1/generations، ثم اقترع GET /api-platform/v1/task/{task_id} حتى يصبح status بقيمة ready. حقل النموذج هو seedance-2.5.

كيف أُصادِق على Seedance 2.5 API؟

أرسِل مفتاح الـ API كـ Authorization: Bearer <key>. تُقبل الترويسة X-API-Key أيضًا. أنشئ مفتاحًا بصلاحية فيديو من لوحة تحكم PixMind وحمّله من متغيّر بيئة بدلًا من تضمينه في المصدر.

هل Seedance 2.5 API متاح على PixMind؟

المسار موثّق وجاهز؛ والوصول إلى الواجهة الخلفية في مرحلة الإنجاز، والنموذج مُعلَّم بـ «قريبًا». تحتوي صفحة /api-platform/models/seedance-2-5 على مرجع نقطة النهاية والمُعامِلات، وتستضيف صفحة /ai-video/seedance-2-5 المولّد على الويب في غضون ذلك.

كم مرجعًا يمكنني إرساله في طلب Seedance 2.5 واحد؟

حتى 50 مدخلًا متعدد الأنماط، صور وفيديو ونص وصوت مجتمعة، في طلب واحد. هذا أعلى من 9 في Seedance 2.0. يجب أن يكون كل مرجع رابطًا قابلًا للوصول بشكل عام.

هل تُعيد الواجهة الفيديو بشكل متزامن؟

لا. توليد الفيديو غير متزامن. يُعيد استدعاء الإنشاء taskId؛ تقترع نقطة نهاية المهمة حتى يصبح status بقيمة ready، ثم تقرأ videoUrl. تستغرق عملية التوليد النموذجية بمدة 30 ثانية عدة دقائق، لذا صمّم عميلك للاقتراع، لا للحظر.

ما هي حدود المعدل وسدود التزامن؟

تُطبِّق نقطة الإنشاء حدود معدّل الطلبات والتزامن لكل مفتاح. إذا تجاوزتها، تُعيد الاستجابة 429 وينبغي أن تتراجع أسيًّا. لأحمال الدفعات (أكثر من بضع مهام متزامنة)، وزّع الإرسالات على فترات قصيرة وتواصل مع الدعم لرفع الحدود إذا واجهت 429 بانتظام. الأرقام الدقيقة للحدود مضبوطة لكل حساب، لذا تحقّق منها على مفتاحك قبل تصميم مهمة دفعات كبيرة.

هل تدعم الواجهة ويبهوك أو استدعاءات راجعة؟

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

كم مهمة متزامنة يمكنني تشغيلها؟

التزامن محدود بسدود مفتاحك وبرصيد محفظتك. لعمل بدقة 1080p ومدة 30 ثانية، توقّع تشغيل بضع مهام بالتوازي بدلًا من عشرات. تعامل مع السقف الحيّ كموثَّق على حسابك: أرسِل دفعة معايرة صغيرة، وقِس كم مهمة تنتقل من pending إلى processing في آن واحد، واضبط حجم طابورك وفقًا لذلك الرقم.

ما صيغة الفيديو التي تُعيدها الواجهة؟

تُعيد المهمة الجاهزة videoUrl يشير إلى ملف MP4 قياسي، بالإضافة إلى coverUrl لإطار الملصق. نزِّل وبرمِج إلى الصيغة التي يحتاجها هدف التسليم (H.264 مع fast-start للويب، وترميزات عمودية للتواصل الاجتماعي، و ProRes لإتقان التحرير). لا تربط مباشرة بـ videoUrl المستضاف على الواجهة في الإنتاج لأنّه ليس مضمونًا أن يبقى؛ انسخ الملف إلى شبكة CDN خاصة بك عند ready.

كيف أتحقّق من الأرصدة قبل الإرسال؟

اقرأ المولّد الحيّ لمعرفة تكلفة الأرصدة الحالية بالمدة والدقة المختارة، ثم تحقّق من رصيد محفظتك. تُعيد الواجهة 4001 "الرصيد غير كافٍ" إذا كان الرصيد منخفضًا، وعندها لا تُنشَأ المهمة. لخطوط أنابيب الإنتاج، أضِف فحص رصيد قبل الإرسال يُلغي مبكرًا إذا كان الرصيد أقل من عتبة المهمة، كي لا تضع في الطابور عملًا لا تستطيع المحفظة تغطيته.

كيف أُصلِح خطأ «النموذج غير موجود أو غير مُعدّ»؟

تُعني هذه الاستجابة 400 أنّ مسار seedance-2.5 غير مُفعَّل على نقطة الواجهة الخلفية التي تستدعيها. على PixMind هذه هي حالة «قريبًا» أثناء إنجاز الاتصال بالواجهة الخلفية. أكّد أنّك تستدعي المسار الموثَّق /api-platform/v1/generations مع model: "seedance-2.5" (بحروف صغيرة، مضبوط). إذا كان كلاهما صحيحًا واستمرّ الخطأ، فالمسار غير مفتوح بعد على حسابك؛ تابِع صفحة /api-platform/models/seedance-2-5 لمعرفة التوفّر.

ما الدقات والمدد التي يمكنني طلبها؟

مدد حتى 30 ثانية في لقطة واحدة؛ ودقات 480p و 720p و 1080p و 4K أصلية. أكّد الخيارات الدقيقة في المولّد الحيّ قبل الإرسال، إذ قد يكشف المسار المتصل مجموعة فرعية منها.

هل تسعير Seedance 2.5 API منشور؟

ليس بعد. تعامل مع أي رقم لكل ثانية تراه في مكان آخر كتقدير. اقرأ المولّد الحيّ للأرصدة الحالية بالمدة والدقة المختارة قبل الإرسال، وهيكّل خط أنابيبك كي يمتص تحديثًا للسعر دون إعادة كتابة التكامل.

ابدأ البناء مع Seedance 2.5 API

Seedance 2.5 API هو عقد توليد فيديو غير متزامن قياسي: استدعاء إنشاء واحد، حلقة اقتراع واحدة، تنزيل واحد. بمجرّد أن تملك مفتاحًا بنطاق فيديو، فإنّ أمثلة curl و Python أعلاه هي كل ما تحتاجه لإطلاق تكامل أول. يُوضّح جدول المقارنة ودراسة حالة خط الأنابيب كيف تُوسِّع هذا العقد من مقطع واحد إلى سير عمل إنتاج قابل للتكرار يصمد أمام تعديلات العميل، وضغط الميزانية، والمواعيد النهائية.

→ اقرأ مرجع مسار Seedance 2.5 API الكامل، أو جرّب النموذج في المولّد على الويب أثناء إنجاز الوصول إلى الـ API.

قارن كل مسارات Seedance

تفاصيل نقاط النهاية والمصادقة موثّقة مقابل الواجهة الخلفية لـ PixMind لمنصة api-platform بتاريخ 2026-07-31. روابط موارد الأطراف الثالثة موثّقة بتاريخ 2026-07-31. حقول مقارنة Kling API مُعلَّمة كتقديرية ويجب تأكيدها مقابل وثائق Kling الحيّة. تسعير Seedance 2.5 غير منشور ومُعلَّم كتقديري فقط.