كيفية استخدام Seedance 2.0 API 2026

ملخص

تم إطلاق واجهة برمجة تطبيقات Seedance 2.0 في 2 أبريل 2026 عبر Volcengine Ark. يمكنك الآن إرسال مهمة إنشاء فيديو عبر طلب POST، ثم استقصاء نقطة نهاية GET حتى تصل الحالة إلى "succeeded" (نجحت). تدعم الواجهة تحويل النص إلى فيديو، الصورة إلى فيديو، التحكم في الإطار الأول والأخير، المراجع متعددة الوسائط، وتوليد الصوت الأصلي. تكلفة فيديو 1080p لمدة 5 ثوانٍ تقريباً 0.93 دولار أمريكي. يجب تنزيل الفيديو خلال 24 ساعة من إنشائه، حيث تنتهي صلاحية الرابط بعد ذلك.

جرّب Apidog اليوم

Hypereal AI

جرب Hypereal AI

مقدمة

في 2 أبريل 2026 أطلقت منصة Volcengine Ark التابعة لشركة ByteDance واجهة برمجة تطبيقات Seedance 2.0. قبل ذلك، كان إنشاء فيديوهات Seedance 2.0 يقتصر على واجهة الويب فقط. هذا الدليل يركز مباشرة على استدعاء الواجهة البرمجية للمطورين.

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

تغطي المقالة جميع أنواع الإدخال المدعومة، وطريقة حساب التكلفة، والأخطاء الأكثر شيوعاً في بيئة الإنتاج.

ما هو Seedance 2.0؟

Seedance 2.0 هو نموذج فيديو من ByteDance عبر Volcengine Ark معرّف بـ

• doubao-seedance-2-0-260128 (قياسي)
• doubao-seedance-2-0-fast-260128 (سريع وجودة أقل)

يدعم أنماط إدخال متقدمة مقارنة بالإصدار 1.5:

• التحكم في الإطار الأول والأخير (صورتان محددتان)
• مراجع متعددة الوسائط (صور، فيديو، صوت)
• توليد الصوت الأصلي (حوار، مؤثرات، موسيقى، بيئة)
• مزامنة الشفاه بأكثر من 8 لغات
• تحكم في حركة الكاميرا عبر أوامر نصية (dolly, tracking, crane)
• إخراج حتى 15 ثانية بدقة تصل إلى 2K

النموذج يخرج فيديو بمعدل 24 إطار/ث مع نسب عرض إلى ارتفاع من 1:1 حتى 21:9. اختر الدقة عند كل طلب.

ما الذي تغير: الدليل مقابل واجهة برمجة التطبيقات الرسمية

في السابق، كانت الأدلة تشرح فقط واجهة الويب. الآن يمكنك استدعاء واجهة برمجة التطبيقات مباشرة من أي لغة، وأتمتة إنشاء الفيديو ودمجها في منتجاتك. هذا الدليل هو المرجع العملي للمطورين.

المتطلبات الأساسية

• حساب Volcengine: volcengine.com
• بعد التفعيل، اذهب إلى لوحة Ark:

  https://console.volcengine.com/ark/region:ark+cn-beijing/apikey

• أنشئ مفتاح API وصدّره كمتغير بيئة:

  export ARK_API_KEY="your-api-key-here"

• كل طلب يجب أن يحمل:

  Authorization: Bearer YOUR_ARK_API_KEY

الحسابات الجديدة تحصل على رصيد تجريبي مجاني يكفي لـ 8 فيديوهات كاملة (15 ثانية 1080p).

النص إلى فيديو: طلبك الأول

النقطة الأساسية للواجهة:

https://ark.cn-beijing.volces.com/api/v3

لإنشاء فيديو من نص، أرسل POST إلى /v1/contents/generations/tasks.

مثال cURL

curl -X POST "https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {
        "type": "text",
        "text": "A golden retriever running through a sunlit wheat field, wide tracking shot, cinematic"
      }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5,
    "watermark": false
  }'

الاستجابة:

{"id": "cgt-2025xxxxxxxx-xxxx"}

مثال بايثون (SDK الرسمي)

أولاً ثبت الـ SDK:

pip install volcenginesdkarkruntime

ثم:

import os
from volcenginesdkarkruntime import Ark

client = Ark(api_key=os.environ.get("ARK_API_KEY"))

resp = client.content_generation.tasks.create(
    model="doubao-seedance-2-0-260128",
    content=[
        {
            "type": "text",
            "text": "A golden retriever running through a sunlit wheat field, wide tracking shot, cinematic"
        }
    ],
    resolution="1080p",
    ratio="16:9",
    duration=5,
    watermark=False,
)

print(resp.id)

احتفظ بـ task id للاستقصاء.

نمط المهام غير المتزامنة: إرسال، استقصاء، تنزيل

إنشاء الفيديو ليس فورياً. فيديو 1080p/5 ثواني يستغرق عادة 60-120 ثانية.

حالة المهمة:

queued → running → succeeded
      → failed
      → expired
      → cancelled

استقصِ نقطة النهاية GET حتى تتغير الحالة.

حلقة استقصاء بايثون كاملة

import os
import time
import requests
from volcenginesdkarkruntime import Ark

client = Ark(api_key=os.environ.get("ARK_API_KEY"))

# 1. إرسال المهمة
resp = client.content_generation.tasks.create(
    model="doubao-seedance-2-0-260128",
    content=[
        {"type": "text", "text": "Aerial shot of a mountain lake at sunrise, slow dolly forward"}
    ],
    resolution="1080p",
    ratio="16:9",
    duration=5,
    watermark=False,
)

task_id = resp.id
print(f"Task submitted: {task_id}")

# 2. حلقة الاستقصاء (تراجع أسي)
wait = 10
while True:
    result = client.content_generation.tasks.get(task_id=task_id)
    status = result.status
    print(f"Status: {status}")

    if status == "succeeded":
        video_url = result.content.video_url
        print(f"Video URL: {video_url}")
        break
    elif status in ("failed", "expired", "cancelled"):
        print(f"Task ended with status: {status}")
        break

    time.sleep(wait)
    wait = min(wait * 2, 60)  # حد أقصى 60 ثانية

# 3. تنزيل الفيديو فور النجاح
if status == "succeeded":
    response = requests.get(video_url, stream=True)
    with open("output.mp4", "wb") as f:
        for chunk in response.iter_content(chunk_size=8192):
            f.write(chunk)
    print("Downloaded: output.mp4")

الصورة إلى فيديو (I2V): تحريك صورة ثابتة

لتحريك صورة:

resp = client.content_generation.tasks.create(
    model="doubao-seedance-2-0-260128",
    content=[
        {
            "type": "text",
            "text": "The woman slowly turns her head and smiles at the camera"
        },
        {
            "type": "image_url",
            "image_url": {"url": "https://example.com/portrait.jpg"}
        }
    ],
    ratio="adaptive",
    duration=5,
    watermark=False,
)

استخدم "ratio": "adaptive" لتفادي الاقتصاص. حجم الصورة ≤ 30MB. يمكنك رفع حتى 9 صور في الطلب.

الإطار الأول والأخير: التحكم في نقاط البداية والنهاية

استخدم صورتين نص + صورة أولى + صورة أخيرة:

resp = client.content_generation.tasks.create(
    model="doubao-seedance-2-0-260128",
    content=[
        {
            "type": "text",
            "text": "The flower blooms from bud to full open, macro lens, soft light"
        },
        {
            "type": "image_url",
            "image_url": {"url": "https://example.com/flower-bud.jpg"}
        },
        {
            "type": "image_url",
            "image_url": {"url": "https://example.com/flower-open.jpg"}
        }
    ],
    ratio="adaptive",
    duration=8,
    watermark=False,
)

رتب الصور: الأولى للإطار الأول، الثانية للأخير. استخدم return_last_frame: true إذا أردت صورة الإطار الأخير في الاستجابة.

مرجع متعدد الوسائط: دمج الصور والفيديو والصوت

يمكنك دمج نص + صور + فيديو + صوت في نفس الطلب:

resp = client.content_generation.tasks.create(
    model="doubao-seedance-2-0-260128",
    content=[
        {
            "type": "text",
            "text": "Match the visual style of the reference clip and add the provided background audio"
        },
        {
            "type": "image_url",
            "image_url": {"url": "https://example.com/style-reference.jpg"}
        },
        {
            "type": "video_url",
            "video_url": {"url": "https://example.com/motion-reference.mp4"}
        },
        {
            "type": "audio_url",
            "audio_url": {"url": "https://example.com/background-music.mp3"}
        }
    ],
    duration=10,
    ratio="16:9",
    watermark=False,
)

الحدود:

• حتى 9 صور
• حتى 3 فيديوهات (2-15 ثانية لكل منها، ≤ 50MB)
• حتى 3 ملفات صوتية (MP3, ≤ 15MB)

إذا أضفت مرجع فيديو، ينخفض التسعير إلى 3.90 دولار لكل مليون رمز.

توليد الصوت الأصلي

أضف generate_audio: true لإنشاء صوت متزامن مع الفيديو:

resp = client.content_generation.tasks.create(
    model="doubao-seedance-2-0-260128",
    content=[
        {
            "type": "text",
            "text": "A street musician plays guitar outside a cafe in Paris, crowds passing by, city sounds"
        }
    ],
    resolution="1080p",
    ratio="16:9",
    duration=10,
    generate_audio=True,
    watermark=False,
)

الصوت يشمل الحوار والمؤثرات والموسيقى. مزامنة الشفاه متقدمة. تكلفة الرموز تزداد قليلاً.

التحكم في الدقة والنسبة والمدة

• resolution: "480p", "720p", "1080p", "2K". الافتراضي "1080p". الدقة الأعلى تستهلك رموزاً أكثر.
• ratio: "16:9", "9:16", "4:3", "3:4", "21:9", "1:1", "adaptive".
• duration: عدد صحيح 4-15 ثانية (الافتراضي 5).

النموذج السريع (doubao-seedance-2-0-fast-260128) أسرع وأرخص لكن الجودة أقل. استخدمه للنماذج الأولية، و"القياسي" للإنتاج.

استخدم Seedance إذا احتجت صوت وفيديو متزامن، تحكم بالإطارات، أو مراجع وسائط متعددة.

قراءة التكلفة من الاستجابة

استجابة المهمة الناجحة تتضمن:

{
  "usage": {
    "completion_tokens": 246840,
    "total_tokens": 246840
  }
}

عدد الرموز يتناسب مع الطول والدقة.

• فيديو 1080p/15ث ≈ 308,880 رمز
• فيديو 1080p/5ث ≈ 102,960 رمز

السعر:

• T2V/I2V: 46 يوان لكل مليون رمز (~6.40 دولار)
• V2V: 28 يوان لكل مليون رمز (~3.90 دولار)

يمكنك حساب التكلفة بضرب completion_tokens بسعر المهمة.

هام: قم بتنزيل الفيديو في غضون 24 ساعة

حقل video_url ينتهي بعد 24 ساعة. بعد ذلك، ستحصل على خطأ 403 ولن تتمكن من تنزيل الملف.

دائماً نزّل الملف فور نجاح المهمة.

حقل execution_expires_after يعطي مدة الصلاحية بالثواني (عادةً 48 ساعة لسجل المهمة، لكن الفيديو نفسه متاح فقط 24 ساعة).

سجل المهام متاح لآخر 7 أيام فقط.

كيف تختبر واجهة برمجة تطبيقات Seedance باستخدام Apidog

نمط المهام غير المتزامنة يتطلب تدفقاً متسلسلاً. سيناريوهات اختبار Apidog تمكنك من ربط الطلبات، استخراج المتغيرات، وتكرار الاستقصاء حتى النجاح.

الخطوات العملية في Apidog:

1. أنشئ سيناريو اختبار جديد

انتقل لوحدة الاختبارات، أنشئ سيناريو باسم "إنشاء فيديو Seedance 2.0".

عين متغير البيئة ARK_API_KEY واستخدمه كرأس تخويل.

2. أضف طلب POST للإرسال

أرسل إلى:

https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks

رأس التخويل: Bearer {{ARK_API_KEY}}

اكتب جسم JSON للمهمة.

3. أضف معالج استخراج متغير

استخرج $.id من الاستجابة واحفظه في TASK_ID.

4. أضف معالج انتظار

أضف انتظار 30 ثانية.

5. أضف حلقة استقصاء

كتلة تكرار (حتى 20 مرة):

• طلب GET إلى

  https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks/{{TASK_ID}}

• انتظار 10 ثوانٍ بعد كل GET
• اكسر الحلقة إذا كان $.status == "succeeded" أو $.status == "failed"

6. أضف معالجات تأكيد

تحقق أن:

• $.status == "succeeded"
• $.content.video_url ليس فارغاً

7. تشغيل السيناريو

Apidog يعرض تقرير اختبار كامل مع كل خطوة.

يمكنك استيراد نقاط النهاية من cURL مباشرة لتسريع الإعداد.

تفاصيل التسعير: تكلفة فيديو مدته 10 ثوانٍ

التسعير حسب عدد الرموز المستهلكة. لا اشتراكات شهرية.

نوع المهمة	السعر (لكل مليون رمز مميز)
T2V / I2V بدقة 1080p	46 يوان (~6.40 دولار أمريكي)
V2V (مرجع فيديو)	28 يوان (~3.90 دولار أمريكي)

التكلفة التقريبية لفيديوهات شائعة (1080p):

المدة	الرموز المميزة التقريبية	التكلفة (T2V/I2V)
5 ثوانٍ	~103,000	~0.66 يوان / ~0.93 دولار
10 ثوانٍ	~206,000	~9.48 يوان / ~1.32 دولار
15 ثانية	~309,000	~14.21 يوان / ~1.97 دولار

الرصيد التجريبي يغطي نحو 8 فيديوهات كاملة (15 ثانية).

الدقة الأقل تقلل التكلفة بشكل كبير. ابدأ التطوير بدقة 720p، واحتفظ بالدقة الأعلى للإنتاج النهائي.

الأخطاء الشائعة والحلول

429 عدد كبير جداً من الطلبات

يعني تجاوز حد التزامن. استخدم التراجع الأسي: ابدأ بانتظار 10 ثوانٍ، ثم ضاعف حتى 60 ثانية.

حلقة الاستقصاء في الكود أعلاه تتعامل مع ذلك.

الحالة: "فشلت"

قد يكون السبب: مطالبة غير مقبولة (سياسة الأمان)، صورة تالفة/كبيرة جداً، معلمات غير صالحة. راجع وكرر الإرسال.

الحالة: "انتهت صلاحيتها"

بقيت المهمة في الانتظار طويلاً (خلال الذروة). أعد الإرسال.

403 على video_url

انتهت صلاحية الرابط (بعد 24 ساعة). أعد الإنشاء بنفس المعلمات والبذرة (seed) إذا حفظتها.

قابلية تكرار البذرة

لحفظ البذرة (seed) من استجابة سابقة، أعد إرسالها بنفس المعلمات لإعادة إنتاج نفس الفيديو.

الخاتمة

واجهة برمجة تطبيقات Seedance 2.0 تتيح إمكانيات إنشاء فيديو متقدمة برمجياً. نمط POST → استقصاء → تنزيل بسيط وفعال. دعم الوسائط المتعددة، التحكم في الإطارات، وتوليد الصوت الأصلي يُمكّن مطوري البرمجيات من بناء سير عمل فيديو متطور.

اختبر تدفقاتك جيداً باستخدام Apidog قبل إطلاق الإنتاج. سيناريوهات الاختبار المتسلسلة تكشف مشاكل الاستقصاء، الأخطاء، أو انتهاء صلاحية الروابط قبل وصولها للمستخدم النهائي.

الأسئلة الشائعة

س: ما الفرق بين doubao-seedance-2-0-260128 و doubao-seedance-2-0-fast-260128؟

ج: النموذج القياسي يعطي جودة أعلى، وهو الأنسب للإنتاج. النموذج السريع أسرع وجودته أقل، استخدمه أثناء اختبار المطالبات.

س: هل يمكنني استخدام Seedance 2.0 خارج الصين؟

ج: نقطة النهاية في بكين. يمكنك استخدامها من أي مكان، لكن زمن الاستجابة أعلى. تحقق من شروط Volcengine لقيود الموقع.

س: كيف أوصل عدة مقاطع لإنشاء فيديو طويل؟

ج: استخدم return_last_frame: true مع كل طلب. استخدم صورة الإطار الأخير كإطار أول للطلب التالي. بعد ذلك، دمج جميع المقاطع عن طريق أدوات تحرير الفيديو.

س: هل توليد الصوت الأصلي أغلى؟

ج: نعم، يستهلك رموزاً أكثر، لكن زيادة التكلفة متواضعة.

س: هل يمكنني استخدام webhook بدلاً من الاستقصاء؟

ج: نعم. أضف callback_url في طلبك، وسترسل الواجهة النتيجة تلقائياً عندما تجهز المهمة.

س: ماذا لو أرسلت أكثر من 9 صور؟

ج: ستحصل على خطأ تحقق 400. قلل العدد إلى 9 صور أو أقل.

س: هل تعيد البذرة (seed) نفس الفيديو تماماً؟

ج: تزيد البذرة من قابلية التكرار، لكن لا يُضمن التطابق التام إذا تغيرت المعلمات أو إصدار النموذج.

س: كيف أتابع الإنفاق؟

ج: احسب completion_tokens لكل مهمة، واضرب بسعر الفئة. خزّن البيانات في قاعدة بياناتك الخاصة. لا توجد لوحة تحكم تلقائية لتتبع الإنفاق.