> ## Documentation Index > Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt > Use this file to discover all available pages before exploring further. # واجهة برمجة تطبيقات توليد مقاطع فيديو SeeDance > ByteDance Seedance Video Generation 集成指南 - XHuoAPI ستتناول هذه الوثيقة كيفية دمج واجهة برمجة تطبيقات توليد مقاطع فيديو SeeDance، والتي يمكن من خلالها إنشاء مقاطع فيديو رسمية من SeeDance عن طريق إدخال معلمات مخصصة. ## عملية التقديم لاستخدام واجهة برمجة التطبيقات، يجب أولاً زيارة صفحة [واجهة برمجة تطبيقات توليد مقاطع فيديو SeeDance](https://api.xhuoapi.ai/documents/seedance-videos) للتقدم للحصول على الخدمة المناسبة، بعد الدخول إلى الصفحة، انقر على زر "Acquire"، كما هو موضح في الصورة: ![](https://cdn.xhuoapi.ai/q6ytrc.png) إذا لم تكن قد قمت بتسجيل الدخول أو التسجيل بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، بعد تسجيل الدخول أو التسجيل، سيتم العودة تلقائيًا إلى الصفحة الحالية. عند التقديم لأول مرة، سيكون هناك حد مجاني متاح، يمكنك استخدام واجهة برمجة التطبيقات مجانًا. ## الاستخدام الأساسي أولاً، يجب أن نفهم طريقة الاستخدام الأساسية، وهي إدخال كلمة المرور `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" لإجراء اختبار، كما هو موضح في الصورة أعلاه، هنا حصلنا على النتيجة التالية: ```json theme={null} { "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.xhuoapi.ai/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 كما يلي: ```shell theme={null} curl -X POST 'https://api.xhuoapi.ai/v1/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` (طريقة قديمة، تحقق ضعيف، عند إدخال خطأ، سيتم استخدام القيم الافتراضية تلقائيًا). قائمة المعلمات الكاملة كما يلي: | المعلمة المضمنة | الحقل المقابل | الوصف | نطاق القيم | | --------------- | ----------------- | --------------------------------- | ------------------------------------------------------------- | | `--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`: ```json theme={null} { "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. الكود المقابل: ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/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.xhuoapi.ai/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` ككلمة مفتاحية. الكود المقابل: ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/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.xhuoapi.ai/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` لربطها. ```json theme={null} { "task_id": "f7096c6c-9430-4392-8201-d259632d7afd" } ``` عند الانتهاء من المهمة، المحتوى الذي يتم دفعه إلى `callback_url` هو كما يلي: ```json theme={null} { "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.xhuoapi.ai/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`: خطأ في الخادم الداخلي، حدث خطأ ما على الخادم. ### مثال على استجابة الخطأ ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## الخاتمة من خلال هذه الوثيقة، لقد فهمت كيفية استخدام واجهة برمجة تطبيقات توليد فيديوهات SeeDance من خلال إدخال كلمات مفتاحية وصور مرجعية لتوليد الفيديو. نأمل أن تساعدك هذه الوثيقة في التوصيل والاستخدام الأفضل لهذه الواجهة. إذا كان لديك أي استفسارات، فلا تتردد في الاتصال بفريق الدعم الفني لدينا.