الانتقال إلى المحتوى الرئيسي
ستتناول هذه الوثيقة كيفية دمج واجهة برمجة تطبيقات توليد مقاطع فيديو SeeDance، والتي يمكن من خلالها إنشاء مقاطع فيديو رسمية من SeeDance عن طريق إدخال معلمات مخصصة.

​
عملية التقديم

لاستخدام واجهة برمجة التطبيقات، يجب أولاً زيارة صفحة واجهة برمجة تطبيقات توليد مقاطع فيديو SeeDance للتقدم للحصول على الخدمة المناسبة، بعد الدخول إلى الصفحة، انقر على زر “Acquire”، كما هو موضح في الصورة: إذا لم تكن قد قمت بتسجيل الدخول أو التسجيل بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، بعد تسجيل الدخول أو التسجيل، سيتم العودة تلقائيًا إلى الصفحة الحالية. عند التقديم لأول مرة، سيكون هناك حد مجاني متاح، يمكنك استخدام واجهة برمجة التطبيقات مجانًا.

​
الاستخدام الأساسي

أولاً، يجب أن نفهم طريقة الاستخدام الأساسية، وهي إدخال كلمة المرور content.text، النوع content.type=text، والنموذج model، للحصول على النتيجة المعالجة، المحتوى المحدد كما يلي:

يمكننا أن نرى هنا أننا قمنا بتعيين رؤوس الطلب، بما في ذلك:
  • accept: نوع الاستجابة التي ترغب في تلقيها، هنا يتم ملؤها بـ application/json، أي بتنسيق JSON.
  • authorization: مفتاح استدعاء واجهة برمجة التطبيقات، بعد التقديم يمكنك اختيارها مباشرة من القائمة المنسدلة.
بالإضافة إلى ذلك، تم تعيين جسم الطلب، بما في ذلك:
  • model: نموذج توليد الفيديو، القيم الاختيارية: doubao-seedance-1-0-pro-250528، doubao-seedance-1-0-pro-fast-251015، doubao-seedance-1-5-pro-251215، doubao-seedance-1-0-lite-t2v-250428، doubao-seedance-1-0-lite-i2v-250428.
  • content: مصفوفة المحتوى المدخل، type يمكن أن يكون text أو image_url.
  • resolution: دقة الإخراج، القيم الاختيارية 480p / 720p / 1080p.
  • ratio: نسبة العرض إلى الارتفاع، القيم الاختيارية 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 21:9 / adaptive.
  • duration: مدة الفيديو (بالثواني)، النطاق 2–12.
  • seed: البذور العشوائية، عدد صحيح، من -1 إلى 4294967295.
  • camerafixed: ما إذا كانت الكاميرا ثابتة، true / false.
  • watermark: ما إذا كان سيتم إضافة علامة مائية، true / false.
  • generate_audio: ما إذا كان سيتم إنشاء فيديو صوتي، true / false، يدعم فقط doubao-seedance-1-5-pro-251215.
  • service_tier: وضع الاستدلال، default (عبر الإنترنت) أو flex (غير متصل، السعر 50% من السعر عبر الإنترنت).
  • return_last_frame: ما إذا كان سيتم إرجاع عنوان URL للصورة الأخيرة من الفيديو في النتيجة.
  • execution_expires_after: وقت انتهاء المهمة (بالثواني)، النطاق 3600–259200.
  • callback_url: عنوان رد الاتصال غير المتزامن، بعد الإعداد، ستعيد واجهة برمجة التطبيقات مباشرة task_id، وعند الانتهاء من المهمة، سيتم نشر النتيجة إلى هذا العنوان.
بعد الاختيار، يمكنك أن ترى أن الكود المقابل قد تم إنشاؤه على الجانب الأيمن، كما هو موضح في الصورة:

انقر على زر “Try” لإجراء اختبار، كما هو موضح في الصورة أعلاه، هنا حصلنا على النتيجة التالية: 
{
  "success": true,
  "task_id": "ec22ae22-0140-4033-8c86-a48b536da595",
  "trace_id": "1cc87db0-8ee5-4436-969b-35cc571a9fd5",
  "data": {
    "task_id": "cgt-20251222005129-62fhb",
    "status": "succeeded",
    "video_url": "https://platform.cdn.acedata.cloud/seedance/f592800a-b87c-4705-8796-cbb8018cae35.mp4",
    "model": "doubao-seedance-1-0-pro-250528"
  }
}
تتضمن النتيجة العائدة عدة حقول، كما يلي:
  • success: حالة مهمة توليد الفيديو في ذلك الوقت.
  • task_id: معرف مهمة توليد الفيديو في ذلك الوقت.
  • trace_id: معرف تتبع توليد الفيديو في ذلك الوقت.
  • data: قائمة نتائج مهمة توليد الفيديو في ذلك الوقت.
    • task_id: معرف خادم مهمة توليد الفيديو في ذلك الوقت.
    • video_url: رابط الفيديو لمهمة توليد الفيديو في ذلك الوقت.
    • status: حالة مهمة توليد الفيديو في ذلك الوقت.
      • model: النموذج المستخدم في توليد الفيديو.
يمكننا أن نرى أننا حصلنا على معلومات الفيديو المرضية، كل ما علينا هو الحصول على الفيديو الذي تم إنشاؤه من SeeDance بناءً على عنوان URL للفيديو في data في النتيجة. بالإضافة إلى ذلك، إذا كنت ترغب في توليد كود التكامل المقابل، يمكنك نسخه مباشرة، على سبيل المثال، كود CURL كما يلي: 
curl -X POST 'https://api.acedata.cloud/seedance/videos' \
-H 'authorization: Bearer ${bearer_token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "content": [{"text":"A kitten yawning at the camera. --rs 720p --rt 16:9 --dur 5 --fps 24 --wm true --seed 11 --cf false","type":"text"}],
  "model": "doubao-seedance-1-0-pro-250528"
}'

​
شرح المعلمات المضمنة

في نهاية كلمة المرور content[].text، يمكنك تمرير معلمات التوليد عن طريق إضافة --parameter value (طريقة قديمة، تحقق ضعيف، عند إدخال خطأ، سيتم استخدام القيم الافتراضية تلقائيًا). قائمة المعلمات الكاملة كما يلي:
المعلمة المضمنةالحقل المقابلالوصفنطاق القيم
--rsresolutionدقة الإخراج480p / 720p / 1080p
--rtratioنسبة العرض إلى الارتفاع16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 21:9 / adaptive
--durdurationمدة الفيديو (بالثواني)2–12
--framesframesعدد إطارات الفيديوعدد صحيح يحقق 25+4n في [29, 289]
--fpsframespersecondمعدل الإطاراتيدعم فقط 24
--seedseedالبذور العشوائية-1 إلى 4294967295
--cfcamerafixedما إذا كانت الكاميرا ثابتةtrue / false
--wmwatermarkما إذا كان سيتم إضافة علامة مائيةtrue / false
الممارسة الموصى بها: استخدم مباشرة الحقول العلوية المقابلة في جسم الطلب (مثل resolution، ratio، إلخ)، لنمط التحقق القوي، عند إدخال خطأ في المعلمات، ستعيد رسالة خطأ واضحة، مما يسهل استكشاف الأخطاء وإصلاحها.

​
توليد فيديو صوتي

يدعم doubao-seedance-1-5-pro-251215 توليد فيديو مع صوت من خلال معلمة generate_audio: 
{
  "model": "doubao-seedance-1-5-pro-251215",
  "content": [
    {
      "type": "text",
      "text": "A girl holds a fox, the wind blows her hair, you can hear the sound of the wind"
    }
  ],
  "generate_audio": true,
  "ratio": "16:9",
  "duration": 5
}
其他模型 لا تدعم هذا المعامل، وسيتم تجاهله عند تمريره.

​
صورة توليد الفيديو الإطار الأول

إذا كنت ترغب في توليد فيديو من صورة، يجب أن يحتوي معامل content أولاً على عنصر من النوع image_url، ويجب أن يكون حقل image_url بتنسيق كائن: {"url": "https://..."} أو بتنسيق Base64 {"url": "data:image/png;base64,..."}.
ملاحظة: image_url لا تدعم تمريرها بتنسيق سلسلة مباشرة (مثل "image_url": "https://...")، يجب استخدام تنسيق الكائن "image_url": {"url": "https://..."}، وإلا ستتلقى خطأ 400.
الكود المقابل: 
import requests

url = "https://api.acedata.cloud/seedance/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "content": [
        {
            "type": "image_url",
            "image_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/i2v_foxrgirl.png"
            }
        },
        {
            "type": "text",
            "text": "A girl holds a fox in her arms. She opens her eyes and gazes tenderly at the camera, while the fox affectionately holds her back. As the camera slowly pulls away, her hair is gently blown by the wind. --ratio adaptive  --dur 5"
        }
    ],
    "model": "doubao-seedance-1-0-pro-250528"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
عند النقر على التشغيل، يمكنك أن ترى أنك ستحصل على نتيجة على الفور، كما يلي: 
{
    "success": true,
    "task_id": "dc7cceb5-3c12-4de7-a5f4-abcbba3e8e39",
    "trace_id": "b3b09de3-b7fa-4bb0-88b5-aad4b4a96fd4",
    "data": {
        "task_id": "cgt-20251222072003-x2259",
        "status": "succeeded",
        "video_url": "https://platform.cdn.acedata.cloud/seedance/6afb78b8-5ba8-424f-adcd-69423a700b50.mp4",
        "model": "doubao-seedance-1-0-pro-250528"
    }
}
يمكنك أن ترى أن التأثير الناتج هو توليد فيديو من صورة، والنتيجة مشابهة لما سبق.

​
صورة توليد الفيديو الإطار الأول والأخير

إذا كنت ترغب في توليد فيديو من صورة للإطار الأول والأخير، يجب أولاً تمرير معامل content من النوع image_url، وتعيين role إلى first_frame و last_frame، يمكنك تحديد المحتوى كما يلي:
  • role: تحديد الإطار الأول أو الأخير.
  • image_url
    • url رابط الصورة في نفس الوقت، يجب أن يتضمن content نوع text ككلمة مفتاحية.
الكود المقابل: 
import requests

url = "https://api.acedata.cloud/seedance/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
   "model": "doubao-seedance-1-0-pro-250528",
    "content": [
         {
            "type": "text",
            "text": "360-degree shot"
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_first_frame.jpeg"
            },
            "role": "first_frame"
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_last_frame.jpeg"
            },
            "role": "last_frame"
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
عند النقر على التشغيل، يمكنك أن ترى أنك ستحصل على نتيجة على الفور، كما يلي: 
{
    "success": true,
    "task_id": "f7096c6c-9430-4392-8201-d259632d7afd",
    "trace_id": "4a4a3721-00fb-43d2-aff2-3b516ac01a8a",
    "data": {
        "task_id": "cgt-20251222073134-54qcw",
        "status": "succeeded",
        "video_url": "https://platform.cdn.acedata.cloud/seedance/95f9f5f0-fc50-4c71-bc6f-e154582c141e.mp4",
        "model": "doubao-seedance-1-0-pro-250528"
    }
}
يمكنك أن ترى أن التأثير الناتج هو توليد فيديو من صورة، والنتيجة مشابهة لما سبق.

​
ردود غير متزامنة

نظرًا لأن واجهة برمجة تطبيقات توليد فيديوهات SeeDance تستغرق وقتًا طويلاً (حوالي 1-2 دقيقة)، يمكنك استخدام حقل callback_url في وضع غير متزامن، لتجنب احتلال اتصال HTTP لفترة طويلة. العملية الكاملة: عند بدء العميل الطلب، يتم تحديد callback_url، وتقوم واجهة برمجة التطبيقات بإرجاع استجابة تحتوي على task_id على الفور؛ بعد الانتهاء من المهمة، ستقوم المنصة بإرسال النتائج المولدة إلى callback_url بشكل POST JSON، وستحتوي النتائج أيضًا على task_id لربطها. 
{
  "task_id": "f7096c6c-9430-4392-8201-d259632d7afd"
}
عند الانتهاء من المهمة، المحتوى الذي يتم دفعه إلى callback_url هو كما يلي: 
{
  "success": true,
  "task_id": "f7096c6c-9430-4392-8201-d259632d7afd",
  "trace_id": "4a4a3721-00fb-43d2-aff2-3b516ac01a8a",
  "data": {
    "task_id": "cgt-20251222073134-54qcw",
    "status": "succeeded",
    "video_url": "https://platform.cdn.acedata.cloud/seedance/95f9f5f0-fc50-4c71-bc6f-e154582c141e.mp4",
    "model": "doubao-seedance-1-0-pro-250528"
  }
}
حقل task_id في النتيجة يتطابق مع ما تم إرجاعه عند الطلب، من خلال هذا الحقل يمكنك ربط المهمة.

​
معالجة الأخطاء

عند استدعاء واجهة برمجة التطبيقات، إذا واجهت خطأ، ستقوم واجهة برمجة التطبيقات بإرجاع رمز الخطأ والمعلومات المناسبة. على سبيل المثال:
  • 400 token_mismatched: طلب غير صحيح، ربما بسبب معلمات مفقودة أو غير صالحة.
  • 400 api_not_implemented: طلب غير صحيح، ربما بسبب معلمات مفقودة أو غير صالحة.
  • 401 invalid_token: غير مصرح، رمز تفويض غير صالح أو مفقود.
  • 429 too_many_requests: عدد كبير جدًا من الطلبات، لقد تجاوزت الحد الأقصى لمعدل الطلبات.
  • 500 api_error: خطأ في الخادم الداخلي، حدث خطأ ما على الخادم.

​
مثال على استجابة الخطأ

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
الخاتمة

من خلال هذه الوثيقة، لقد فهمت كيفية استخدام واجهة برمجة تطبيقات توليد فيديوهات SeeDance من خلال إدخال كلمات مفتاحية وصور مرجعية لتوليد الفيديو. نأمل أن تساعدك هذه الوثيقة في التوصيل والاستخدام الأفضل لهذه الواجهة. إذا كان لديك أي استفسارات، فلا تتردد في الاتصال بفريق الدعم الفني لدينا.