SeeDance Videos Generation API توضيح التكامل

ستتناول هذه المقالة توضيح تكامل SeeDance Videos Generation API، والذي يمكن من خلاله إنشاء مقاطع الفيديو الرسمية من SeeDance عن طريق إدخال معلمات مخصصة.

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

لاستخدام SeeDance Videos Generation API، يجب أولاً الذهاب إلى لوحة تحكم Ace Data Cloud للحصول على رمز API الخاص بك، احتفظ به للاستخدام لاحقًا.

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

📘 الوثائق الكاملة: SeeDance Videos Generation API →

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

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

يمكننا أن نرى هنا أننا قمنا بتعيين رؤوس الطلب، بما في ذلك:

accept: نوع الاستجابة التي ترغب في تلقيها، هنا يتم ملؤها بـ application/json، أي بتنسيق JSON.
authorization: مفتاح استدعاء API، يمكن اختياره مباشرة بعد التقديم.

كما تم تعيين جسم الطلب، بما في ذلك:

model: نموذج إنشاء الفيديو.
- سلسلة Seedance 1.x: 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.
- سلسلة Seedance 2.0 (تدعم المدخلات متعددة الوسائط مثل الوجه / مرجع الشخصية): doubao-seedance-2-0-260128 (قياسي)، doubao-seedance-2-0-fast-260128 (سريع)، doubao-seedance-2-0-mini-260615 (خفيف). انظر القسم التالي “الوجه ومرجع الشخصية (Seedance 2.0)”.
content: مصفوفة المحتوى المدخل، يمكن أن يكون type إما text (كلمة تلميح)، image_url (صورة مرجعية)، audio_url (صوت مرجعي، 2.0)، video_url (فيديو مرجعي، 2.0). يمكن تحديد استخدام الصورة من خلال role: first_frame (الإطار الأول) / last_frame (الإطار الأخير) / reference_image (وجه / شخصية / مرجع رئيسي).
resolution: دقة الإخراج، يمكن اختيار 480p / 720p / 1080p (نموذج 2.0 القياسي يدعم أيضًا 4k؛ 2.0 من fast / mini أعلى دقة 720p).
ratio: نسبة العرض إلى الارتفاع، يمكن اختيار 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 21:9 / adaptive.
duration: مدة الفيديو (بالثواني)، نطاق 1.x من 2–12، نطاق 2.0 من 2–15.
seed: البذور العشوائية، عدد صحيح، من -1 إلى 4294967295.
camerafixed: هل يتم تثبيت الكاميرا، true / false.
watermark: هل يتم إضافة علامة مائية، true / false.
generate_audio: هل يتم إنشاء فيديو صوتي، true / false، يدعم فقط doubao-seedance-1-5-pro-251215.
return_last_frame: هل يتم إرجاع عنوان URL لصورة الإطار الأخير من الفيديو في النتيجة.
execution_expires_after: وقت انتهاء المهمة (بالثواني)، نطاق 3600–259200.
callback_url: عنوان رد الاتصال غير المتزامن، بعد تعيينه، سيعيد API على الفور task_id، وعند الانتهاء من المهمة، سيتم إرسال النتيجة عبر POST إلى هذا العنوان.
async: اختياري، إذا تم تعيينه إلى true، سيعيد الواجهة على الفور task_id، دون الحاجة لتقديم callback_url، ثم يمكن الاستعلام عن النتائج من خلال واجهة استعلام المهام المقابلة.

بعد الاختيار، يمكننا أن نرى أن الجانب الأيمن قد أنشأ أيضًا الكود المقابل، كما هو موضح في الصورة:

يمكنك الضغط على زر “Try” لإجراء اختبار، كما هو موضح في الصورة أعلاه، هنا حصلنا على النتيجة التالية:

{
  "success": true,
  "task_id": "9777f36b-4f44-47ff-962d-45cd2f7aeaa8",
  "trace_id": "ce5da2ca-6695-4459-9d2c-2ef9f86db752",
  "data": {
    "task_id": "7e4e1773-510a-4a73-9ab4-98dd1a0b2a7f",
    "status": "succeeded",
    "model": "doubao-seedance-2-0-fast-260128",
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9",
    "video_url": "https://platform2.cdn.acedata.cloud/seedance/036f24ed-a9b1-49b3-92c4-30049a3bc152.mp4"
  }
}

تتضمن النتيجة العائدة عدة حقول، كما يلي:

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": [{"type":"text","text":"A white ceramic coffee mug on a glossy marble countertop with soft morning window light. The camera slowly orbits 360 degrees around the mug, steam gently rising."}],
  "model": "doubao-seedance-2-0-fast-260128",
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}'

توضيح المعلمات المضمنة

في نهاية كلمة التلميح content[].text، يمكن تمرير معلمات الإنشاء عن طريق إضافة --parameter value (طريقة قديمة، تحقق ضعيف، إذا كانت المدخلات خاطئة، سيتم استخدام القيم الافتراضية تلقائيًا). قائمة المعلمات الكاملة كما يلي:

المعاملات المضمنة	الحقل المقابل	الشرح	نطاق القيم
`--rs`	`resolution`	دقة الإخراج	`480p` / `720p` / `1080p`
`--rt`	`ratio`	نسبة العرض إلى الارتفاع	`16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `21:9` / `adaptive`
`--dur`	`duration`	مدة الفيديو (ثواني)	2–12
`--frames`	`frames`	عدد إطارات الفيديو	عدد صحيح يحقق 25+4n في [29, 289]
`--fps`	`framespersecond`	معدل الإطارات	يدعم فقط `24`
`--seed`	`seed`	البذور العشوائية	-1 إلى 4294967295
`--cf`	`camerafixed`	هل يتم تثبيت الكاميرا	`true` / `false`
`--wm`	`watermark`	هل يتم إضافة علامة مائية	`true` / `false`

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

إنشاء فيديو صوتي

يدعم doubao-seedance-1-5-pro-251215 إنشاء فيديو مع صوت من خلال معامل generate_audio:

{
  "model": "doubao-seedance-1-5-pro-251215",
  "content": [
    {
      "type": "text",
      "text": "فتاة تحمل ثعلبًا، والرياح تهب شعرها، يمكنك سماع صوت الرياح"
    }
  ],
  "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": "فتاة تحمل ثعلبًا في ذراعيها. تفتح عينيها وتنظر برفق إلى الكاميرا، بينما يحتضنها الثعلب بحب. بينما تسحب الكاميرا ببطء، يهب الريح شعرها برفق. --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 درجة"
        },
        {
            "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 2.0)

سلسلة Seedance 2.0 (doubao-seedance-2-0-260128، doubao-seedance-2-0-fast-260128، doubao-seedance-2-0-mini-260615) تدعم إدخال مواد مرجعية لـ “أشخاص حقيقيين / شخصيات”: أضف عنصرًا من type كـ image_url و role كـ reference_image في content، واستخدم صورة الشخص كمرجع، سيحتفظ النموذج بخصائص مظهر هذا الشخص في الفيديو الناتج، مما يتيح “وضع نفس الشخص” في مشاهد أو حركات أو لقطات جديدة.

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

نقاط الاستخدام:

فقط نموذج سلسلة Seedance 2.0 يدعم reference_image؛ يرجى استخدام first_frame / last_frame (إطار البداية / النهاية للفيديو) لنماذج 1.x.
لا يمكن استخدام reference_image مع first_frame / last_frame معًا، يجب اختيار أحدهما فقط.
الحد الأقصى لعدد المراجع متعددة الوسائط: يمكن أن تحتوي image_url على 9 صور كحد أقصى؛ كما يدعم 2.0 أيضًا audio_url (دور reference_audio، بحد أقصى 3) و video_url (دور reference_video، بحد أقصى 3).
يُنصح باستخدام صور مرجعية لشخص واحد، من الأمام، واضحة، وغير محجوبة، كلما كانت ملامح الوجه أوضح، كانت درجة التشابه أعلى.

مثال 1: لقطة مقربة للحفاظ على مظهر الشخص

قم بإدخال صورة وجه، ليبتسم الشخص أمام الكاميرا ويهز يده. الكود المقابل:

import requests

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

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

payload = {
    "model": "doubao-seedance-2-0-fast-260128",
    "content": [
        {
            "type": "text",
            "text": "The woman looks at the camera, gives a warm natural smile and waves her hand, soft studio lighting, gentle camera push-in."
        },
        {
            "type": "image_url",
            "role": "reference_image",
            "image_url": {
                "url": "https://platform2.cdn.acedata.cloud/nanobanana/8e075897-0f50-4443-8500-666751791c6c.jpg"
            }
        }
    ],
    "resolution": "480p",
    "ratio": "9:16",
    "duration": 5
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

النتيجة كما يلي، الفيديو الناتج يظهر الشخص متوافقًا مع الصورة المرجعية:

{
  "success": true,
  "task_id": "895eb5ea-bbe1-41a3-a9e9-48608e03f93a",
  "trace_id": "83544791-7a84-44de-b8d2-afe171a1c0e4",
  "data": {
    "task_id": "458abf29-cc39-4fd0-bcea-24f89a70d8de",
    "status": "succeeded",
    "video_url": "https://platform2.cdn.acedata.cloud/seedance/e71d3cc5-27e7-4719-be34-1f0e254eccaf.mp4",
    "model": "doubao-seedance-2-0-fast-260128",
    "resolution": "480p",
    "ratio": "9:16",
    "duration": 5
  }
}

مثال 2: وضع نفس الشخص في مشهد جديد تمامًا

تكمن قوة reference_image في: الاحتفاظ فقط بـ هوية الشخص، بينما يتم تحديد المشهد والملابس والحركات بالكامل بواسطة الكلمات الدالة. هنا نستخدم نفس صورة الوجه، ليظهر الشخص مرتديًا معطفًا بيجًا وهو يمشي في حديقة خريفية:

{
  "model": "doubao-seedance-2-0-fast-260128",
  "content": [
    {
      "type": "text",
      "text": "The same woman wearing a beige coat walks through a sunny autumn park, golden leaves falling around her, she smiles softly at the camera, cinematic tracking shot."
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "url": "https://platform2.cdn.acedata.cloud/nanobanana/8e075897-0f50-4443-8500-666751791c6c.jpg"
      }
    }
  ],
  "resolution": "720p",
  "ratio": "9:16",
  "duration": 5
}

النتيجة كما يلي، مظهر الشخص محفوظ، بينما تم تغيير المشهد إلى حديقة خريفية:

{
  "success": true,
  "task_id": "00872de7-16b7-431f-b4f7-6bf38ae86157",
  "trace_id": "577a07c3-4f5f-4cc7-86fe-535bb8332614",
  "data": {
    "task_id": "32fe1537-ba3e-452a-8749-3ef8890d37fd",
    "status": "succeeded",
    "video_url": "https://platform2.cdn.acedata.cloud/seedance/44f47593-556b-4fda-afa5-7a71eefcd228.mp4",
    "model": "doubao-seedance-2-0-fast-260128",
    "resolution": "720p",
    "ratio": "9:16",
    "duration": 5
  }
}

💡 إذا كنت ترغب في جعل الشخص يعيد إنتاج التكوين الموجود في الصورة بدقة (بدلاً من “نفس الشخص في مشهد مختلف”)، يمكنك استخدام first_frame (إطار البداية للفيديو)، مما يجعل الفيديو يبدأ من هذه الصورة.

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

نظرًا لأن واجهة برمجة تطبيقات SeeDance Videos Generation تستغرق وقتًا طويلاً للتوليد (حوالي 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 Videos Generation من خلال الكلمات الدالة، والصور المرجعية، وكذلك مرجع الوجه / الشخصية في Seedance 2.0 لإنشاء الفيديو. نأمل أن تساعدك هذه الوثيقة في التوصيل والاستخدام الأفضل لهذه الواجهة. إذا كان لديك أي استفسارات، فلا تتردد في الاتصال بفريق الدعم الفني لدينا.

البداية

دردشة الذكاء الاصطناعي

صورة الذكاء الاصطناعي

فيديو الذكاء الاصطناعي

الصوت الذكي

الويب والبيانات

CAPTCHA

الهوية

وكيل

متقدم

SeeDance Videos Generation API توضيح التكامل

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

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

توضيح المعلمات المضمنة

إنشاء فيديو صوتي

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

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

مرجع الوجه والشخصيات (Seedance 2.0)

مثال 1: لقطة مقربة للحفاظ على مظهر الشخص

مثال 2: وضع نفس الشخص في مشهد جديد تمامًا

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

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

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

الخاتمة

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

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

​توضيح المعلمات المضمنة

​إنشاء فيديو صوتي

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

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

​مرجع الوجه والشخصيات (Seedance 2.0)

​مثال 1: لقطة مقربة للحفاظ على مظهر الشخص

​مثال 2: وضع نفس الشخص في مشهد جديد تمامًا

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

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

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

​الخاتمة

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

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

توضيح المعلمات المضمنة

إنشاء فيديو صوتي

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

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

مرجع الوجه والشخصيات (Seedance 2.0)

مثال 1: لقطة مقربة للحفاظ على مظهر الشخص

مثال 2: وضع نفس الشخص في مشهد جديد تمامًا

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

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

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

الخاتمة