Seedance 2.0

Seedance 2.0 هو نموذج توليد الفيديو من ByteDance (Dreamina Seedance 2.0). أرسل جسم المهمة الرسمي من ModelArk، واحتفظ بمعرّف المهمة المُعاد، ثم اقرأ الفيديو المكتمل من المهمة. وتوضع الصور والفيديوهات والصوت في content على شكل روابط.

معرّفات النموذج

تقبل المعرّفات الثلاثة المعاملات نفسها. راجع صفحة النموذج للاطلاع على الأسعار الحالية.

مثال سريع

curl https://api.seedrouter.ai/v1/contents/generations/tasks \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0",
    "content": [{"type": "text", "text": "A red paper boat drifts across a calm pond at sunrise, slow dolly-in"}],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "generate_audio": true
  }'

نقطة النهاية

POST https://api.seedrouter.ai/v1/contents/generations/tasks

الجسم هو طلب «إنشاء مهمة توليد فيديو» الرسمي من ModelArk. وإذا كنت تستدعي ModelArk بالفعل، فلا تغيّر سوى الرابط الأساسي إلى https://api.seedrouter.ai/v1 ومفتاح API. والاستجابة هي {"id": "task_..."} لا الفيديو المكتمل. واحتفظ بمفاتيح API في شفرة تعمل على الخادم.

المعاملات

عناصر content

تُرفض الحقول غير المعروفة. غير مدعوم: seed، وcallback_url (استعلم عن المهمة بدلًا منه)، وdraft وdraft_task، وtools، وframes وcamera_fixed الخاصّان بالإصدار 1.x فقط، وكذلك output_format وomni_reference_task_type (في Seedance 2.5 فقط). ولا يمكن إلغاء المهام أو حذفها.

الأوضاع

يُستنتج الوضع من عناصر content؛ ولا يوجد معامل للوضع.

لا يمكن الجمع بين أوضاع الإطار الأول وعناصر المراجع. وعند وجود عدة صور أو أي وسائط أخرى، تحتاج كل صورة إلى role.

مثال المراجع

curl https://api.seedrouter.ai/v1/contents/generations/tasks \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0",
    "content": [
      {"type": "text", "text": "The character from the image walks through the market in the video, same camera move"},
      {"type": "image_url", "image_url": {"url": "https://example.com/character.png"}, "role": "reference_image"},
      {"type": "video_url", "video_url": {"url": "https://example.com/market.mp4"}, "role": "reference_video"}
    ],
    "ratio": "adaptive",
    "duration": 8
  }'

استبدل روابط المثال بملفاتك أنت بحيث يمكن الوصول إليها.

مدخلات الوسائط

لا تقبل هذه الواجهة سوى الإشارة عبر الروابط. ولا تُقبل بيانات base64 ولا روابط data: ولا معرّفات asset:// ولا الرفع بصيغة multipart. ويرفع Playground الملفات المختارة إلى التخزين قبل إرسال روابطها.

يجب أن تكون الوسائط روابط HTTP(S) عامة وأن تستوفي الحدود الرسمية للنموذج:

لا يدعم النموذج الصور والفيديوهات المرجعية التي تحتوي على وجوه بشرية حقيقية.

تُفحص الوسائط عند بدء المهمة، قبل أي توليد. والمهمة التي تخالف وسائطها أحد هذه الحدود تنتهي بالحالة failed مع invalid_request_error ورسالة تسمّي القاعدة المخالَفة، مثل The request was rejected: content reference videos must total at most 15 seconds.، ولا تُحتسب عليها رسوم. أما الملف الذي يتعذّر قراءته في تلك المرحلة فيُمرَّر إلى النموذج، فيقبله أو يرفضه؛ ولا تُحتسب رسوم على المهمة الفاشلة في الحالتين.

عوامل التكلفة

راجع قسم أسعار النموذج للاطلاع على الأسعار الحالية. يحتسب Seedance 2.0 توكنات الفيديو، وهي الوحدة الرسمية:

video tokens = (output seconds + reference video seconds) × width × height × 24 / 1024

يعتمد السعر لكل مليون توكن على دقة المخرجات وعلى ما إذا كان الطلب يتضمن فيديو مرجعيًا؛ فالطلب الذي يتضمن فيديو مرجعيًا يُحتسب بسعر أقل لجميع توكناته. ولا تُحتسب مدخلات النص والصور والصوت. وبنسبة 16:9، تساوي الثانية الواحدة 10,044 توكن بدقة 480p (864×496)، و21,600 بدقة 720p، و48,600 بدقة 1080p، و194,400 بدقة 4K.

تتبع الرسوم التوكنات التي يبلّغ عنها الفيديو المكتمل (usage.completion_tokens)، لذا يُحتسب duration: -1 على أساس الطول المولَّد فعليًا. وتتجاوز المقاطع المولَّدة الطول المطلوب بقليل: فالطلب الذي مدته 5 ثوانٍ بدقة 720p ونسبة 16:9 يولّد 121 إطارًا ويبلّغ عن 108,900 توكن بدلًا من 108,000. راجع الرسوم النهائية في سجل الاستخدام الخاص بحسابك. ولا تُحتسب رسوم على المهام الفاشلة أو المنتهية الصلاحية.

بنية المخرجات

يعيد الإرسال معرّف المهمة:

{"id": "task_..."}

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

curl https://api.seedrouter.ai/v1/contents/generations/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY"

استعلم كل 10 إلى 20 ثانية حتى تصبح قيمة status هي succeeded أو failed أو expired. وانتهاء مهلة الشبكة أثناء الاستعلام لا يعني فشل التوليد: احتفظ بمعرّف المهمة واستأنف التحقق منها. ولا تنشئ مهمة أخرى لمعرفة التقدّم.

مثال استعلام كامل

شغّل هذا بعد مثال الإرسال بلغة Python الوارد أعلاه.

import time

deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    result = requests.get(
        f"https://api.seedrouter.ai/v1/contents/generations/tasks/{task_id}",
        headers={"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"},
        timeout=30,
    )
    result.raise_for_status()
    task = result.json()
    if task["status"] == "succeeded":
        print(task["content"]["video_url"])
        break
    if task["status"] in ("failed", "expired"):
        raise RuntimeError(task["error"]["message"])
    time.sleep(15)
else:
    raise TimeoutError(f"Still waiting. Resume polling task {task_id}.")

المهمة الناجحة

{
  "id": "task_...",
  "model": "dreamina-seedance-2-0",
  "status": "succeeded",
  "content": {
    "video_url": "https://static.seedrouter.ai/media/tasks/task_example/0.mp4",
    "last_frame_url": "https://static.seedrouter.ai/media/tasks/task_example/last_frame/0.jpg"
  },
  "usage": {"completion_tokens": 108900, "total_tokens": 108900},
  "seed": 42,
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "framespersecond": 24,
  "generate_audio": true,
  "draft": false,
  "output_format": "mp4",
  "service_tier": "default",
  "execution_expires_after": 172800,
  "priority": 0,
  "created_at": 1790321515,
  "updated_at": 1790321652
}

تُستضاف روابط الفيديو على تخزيننا. واحفظ الملف في تخزينك الخاص إذا احتجت إلى نسخة دائمة.

عرض قائمة المهام

curl "https://api.seedrouter.ai/v1/contents/generations/tasks?page_num=1&page_size=20&filter.status=succeeded" \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY"

يعيد {"total": N, "items": [...]} مع كائنات المهام من آخر 7 أيام، مرتّبة من الأحدث إلى الأقدم. وتتراوح قيمتا page_num وpage_size من 1 إلى 500 (والقيمتان الافتراضيتان 1 و20). عوامل التصفية: filter.status وfilter.model وfilter.task_ids (قابل للتكرار) وfilter.service_tier.

الأخطاء

الطلبات المرفوضة قبل إنشاء المهمة تعيد خطأ HTTP مصحوبًا بكائن error ولا تُحتسب عليها رسوم. أما المهمة التي تفشل بعد قبولها فتعيد عند الاستعلام رمز HTTP 200 مع status: "failed" (أو "expired") وكائن error. والمخرجات التي تحجبها تصفية المحتوى تفشل بالرمز content_policy_violation؛ والمهمة التي تتجاوز execution_expires_after تنتهي بالحالة expired مع task_expired.

راجع كتالوج الأخطاء المشترك للاطلاع على الرموز وحالات HTTP وإرشادات إعادة المحاولة.

{
  "id": "task_...",
  "model": "dreamina-seedance-2-0",
  "status": "failed",
  "error": {
    "code": 60001,
    "message": "The request was rejected by the content policy. Please revise the prompt or input images."
  }
}

إذا انتهت مهلة الإرسال نفسه، فراجع قائمة مهامك قبل الإرسال مجددًا: فربما قُبل الطلب الأول.

نصائح

• صِف الموضوع والحركة وحركة الكاميرا والإضاءة بجمل كاملة.
• أنشئ المسودة بدقة 480p مع duration قصيرة، ثم ولّد النسخة المختارة بدقة أعلى.
• اربط اللقطات عبر return_last_frame: استخدم الإطار المُعاد بوصفه first_frame للمهمة التالية.

مواضيع ذات صلة

• Playground وأسعار Seedance 2.0
• تنزيل OpenAPI
• Markdown قابل للنسخ