> ## 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. # شرح تكامل واجهة برمجة تطبيقات توليد فيديوهات Sora > Sora Video Generation 集成指南 - XHuoAPI تقدم هذه الوثيقة شرحًا لكيفية تكامل واجهة برمجة تطبيقات توليد فيديوهات Sora، والتي تتيح إدخال معلمات مخصصة لتوليد فيديوهات رسمية من Sora. تدعم هذه الواجهة نوعين من الأوضاع: * **الإصدار 1 (الوضع الكلاسيكي)**: يدعم معلمات مثل `duration` (10/15/25 ثانية)، `orientation` (وضع أفقي/عمودي)، `size` (وضوح صغير/كبير)، صور مرجعية `image_urls`، ورابط الشخصية `character_url` وغيرها. * **الإصدار 2 (وضع الشركاء)**: يدعم معلمات مثل `seconds` (4/8/12 ثانية)، دقة بكسلية `size` (مثل 1280x720)، صور مرجعية `input_reference` وغيرها. ## عملية التقديم لاستخدام الواجهة، يجب أولاً التقديم للحصول على الخدمة من خلال صفحة [Sora Videos Generation API](https://api.xhuoapi.ai/documents/99a24421-2e22-4028-8201-e19cb834b67e). بعد الدخول إلى الصفحة، اضغط على زر "Acquire" كما هو موضح في الصورة: ![](https://cdn.xhuoapi.ai/q6ytrc.png) إذا لم تكن مسجلًا أو مسجلاً دخولك، سيتم توجيهك تلقائيًا إلى صفحة تسجيل الدخول والتسجيل، وبعدها تعود تلقائيًا إلى الصفحة الحالية. عند التقديم لأول مرة، ستحصل على رصيد مجاني لاستخدام الواجهة مجانًا. ## الاستخدام الأساسي (الإصدار 1) أولاً، لفهم طريقة استخدام الإصدار 1 الأساسية، يتم إدخال كلمة مفتاحية `prompt`، ومصفوفة روابط الصور المرجعية `image_urls`، ونموذج `model` للحصول على النتيجة المعالجة، كما يلي:

يمكن ملاحظة إعدادات رؤوس الطلب (Request Headers) والتي تشمل: * `accept`: نوع الاستجابة المرغوب، هنا `application/json` أي بصيغة JSON. * `authorization`: مفتاح استدعاء الواجهة، يمكن اختياره من القائمة بعد التقديم. كما تم إعداد جسم الطلب (Request Body) ويشمل: * `model`: نموذج توليد الفيديو، يدعم `sora-2` (الوضع القياسي) و `sora-2-pro` (وضع الوضوح العالي). يدعم `sora-2-pro` مدة 25 ثانية، بينما يدعم `sora-2` فقط 10 و15 ثانية. * `size`: وضوح الفيديو، `small` للوضوح القياسي، و`large` للوضوح العالي (خاص بالإصدار 1 فقط). * `duration`: مدة الفيديو، يدعم 10، 15، 25 ثانية، حيث 25 ثانية فقط لـ `sora-2-pro` (خاص بالإصدار 1). * `orientation`: اتجاه الفيديو، يدعم `landscape` (أفقي) و `portrait` (عمودي) (خاص بالإصدار 1). * `image_urls`: مصفوفة روابط الصور المرجعية لتوليد الفيديو من الصور (خاص بالإصدار 1). * `character_url`: رابط الشخصية، لا يجب أن يحتوي الفيديو على أشخاص حقيقيين (خاص بالإصدار 1). * `character_start`/`character_end`: أوقات ظهور الشخصية بالثواني، بفارق 1-3 ثوانٍ (خاص بالإصدار 1). * `prompt`: كلمة المفتاح (مطلوبة). * `callback_url`: رابط استدعاء رد الاتصال غير المتزامن. * `version`: إصدار الواجهة، `"1.0"` (افتراضي) أو `"2.0"`. بعد الاختيار، يظهر على الجانب الأيمن الكود المقابل كما في الصورة:

اضغط على زر "Try" لاختبار الطلب، وستحصل على النتيجة كما في المثال التالي: ```json theme={null} { "success": true, "task_id": "6bf7fb83-5814-4e3e-a4ad-bfa0c26c0b33", "trace_id": "96166698-4b66-478d-a26b-77a7269c9e01", "data": [ { "id": "sora-2:task_01k7770rgsevxsmtpbn7xnm5gh", "video_url": "https://filesystem.site/gptimage/vg-assets/assets%2Ftask_01k7770rgsevxsmtpbn7xnm5gh%2Ftask_01k7770rgsevxsmtpbn7xnm5gh_genid_0bf958d3-cae7-4298-b7b6-99ae439a1ea6_25_10_10_14_06_975715%2Fvideos%2F00000%2Fsrc.mp4?st=2025-10-10T12%3A30%3A38Z&se=2025-10-16T13%3A30%3A38Z&sks=b&skt=2025-10-10T12%3A30%3A38Z&ske=2025-10-16T13%3A30%3A38Z&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skoid=8ebb0df1-a278-4e2e-9c20-f2d373479b3a&skv=2019-02-02&sv=2018-11-09&sr=b&sp=r&spr=https%2Chttp&sig=jigY6Z5qp8%2BTXYobaW0EAJ4%2Fbx6G7t6V1P0iyDeUq48%3D&az=oaivgprodscus", "state": "succeeded" } ] } ``` تتضمن النتيجة عدة حقول، وهي: * `success`: حالة نجاح مهمة توليد الفيديو. * `task_id`: معرف مهمة توليد الفيديو. * `trace_id`: معرف تتبع المهمة. * `data`: قائمة نتائج مهمة توليد الفيديو. * `id`: معرف الفيديو. * `video_url`: رابط الفيديو الناتج. * `state`: حالة المهمة. يمكنك الحصول على فيديو Sora الناتج من خلال رابط الفيديو في `data`. كما يمكن نسخ كود التكامل مباشرة، مثل كود CURL التالي: ```shell theme={null} curl -X POST 'https://api.xhuoapi.ai/v1/sora/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "size": "large", "duration": 15, "orientation": "landscape", "prompt": "cat running on the river", "model": "sora-2" }' ``` ## مهمة توليد فيديو من صورة (الإصدار 1) لإجراء مهمة توليد فيديو من صورة، يجب تمرير معلمة `image_urls` التي تحتوي على روابط الصور المرجعية، ويمكن تحديد المحتويات التالية: * `image_urls`: مصفوفة روابط الصور المرجعية المستخدمة في المهمة. يجب عدم تمرير صور لأشخاص حقيقيين لتجنب فشل المهمة. مثال تعبئة:

بعد التعبئة، يتم توليد الكود التالي تلقائيًا:

الكود المقابل: ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/sora/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "size": "large", "duration": 15, "orientation": "landscape", "prompt": "cat running on the river", "model": "sora-2", "image_urls": ["https://cdn.xhuoapi.ai/11wfp4.png"] } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` بعد التشغيل، ستحصل على نتيجة فورية مثل: ``` { "success": true, "task_id": "dd392ff0-dcb7-4c7a-afd0-9bd4f65c803a", "trace_id": "04fd151c-e942-4c1c-a6ab-9a1b1fe54172", "data": [ { "id": "sora-2:task_01k777af4hfmg9g7yfvwsc6zws", "video_url": "https://filesystem.site/gptimage/vg-assets/assets%2Ftask_01k777af4hfmg9g7yfvwsc6zws%2Ftask_01k777af4hfmg9g7yfvwsc6zws_genid_92bae0c5-1703-4a5f-9d9f-c9ed2f9e7176_25_10_10_14_12_924695%2Fvideos%2F00000%2Fsrc.mp4?st=2025-10-10T12%3A37%3A32Z&se=2025-10-16T13%3A37%3A32Z&sks=b&skt=2025-10-10T12%3A37%3A32Z&ske=2025-10-16T13%3A37%3A32Z&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skoid=aa5ddad1-c91a-4f0a-9aca-e20682cc8969&skv=2019-02-02&sv=2018-11-09&sr=b&sp=r&spr=https%2Chttp&sig=5j4dibeaSsDmEka5c%2B9CKHZhRPdqfClQ0tIh03TWXsM%3D&az=oaivgprodscus", "state": "succeeded" } ] } ``` يمكن ملاحظة أن النتيجة تم توليدها باستخدام الصورة المرجعية، والنتيجة مشابهة لما سبق. ## مهمة توليد فيديو من شخصية (الإصدار 1) لإجراء مهمة توليد فيديو من شخصية، يجب تمرير معلمة `character_url` التي تحتوي على رابط فيديو لإنشاء الشخصية، مع ملاحظة عدم وجود أشخاص حقيقيين في الفيديو لتجنب الفشل، ويمكن تحديد المحتويات التالية: * `character_url`: رابط فيديو لإنشاء الشخصية، يجب ألا يحتوي الفيديو على أشخاص حقيقيين. مثال تعبئة:

بعد التعبئة، يتم توليد الكود التالي تلقائيًا:

الكود المقابل: ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/sora/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "size": "small", "duration": 10, "orientation": "landscape", "prompt": "cat running on the river", "character_url": "https://cdn.xhuoapi.ai/pdidf5.mp4", "model": "sora-2", "character_end": 3, "character_start": 1 } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` بعد التشغيل، ستحصل على نتيجة فورية مثل: ``` { "success": true, "task_id": "d9bf5461-29b5-47fd-be90-1fe9197df259", "trace_id": "b7992643-9207-40d6-956b-7577728acc67", "data": [ { "id": "sora-2:task_01k8ykrztefavaypw6xanw305b", "video_url": "https://filesystem.site/cdn/20251101/bee4eeeb4c4660b46dac4548a1ffbc.mp4", "state": "succeeded" } ] } ``` يمكن ملاحظة أن النتيجة تم توليدها باستخدام شخصية، والنتيجة مشابهة لما سبق. ## وضع الإصدار 2.0 بالإضافة إلى وضع الإصدار 1.0، تدعم الواجهة أيضًا وضع الإصدار 2.0 من خلال تعيين معلمة `version` إلى `"2.0"`. يدعم الإصدار 2.0 مدة فيديو أقصر وتحكمًا دقيقًا في الدقة البكسلية. ### شرح معلمات الإصدار 2.0 | المعلمة | النوع | إلزامي | الوصف | | -------------- | ------- | ------ | ------------------------------------------------------------------------------------------------- | | `version` | string | نعم | تعيين إلى `"2.0"` | | `prompt` | string | نعم | كلمة مفتاحية لتوليد الفيديو | | `model` | string | لا | `sora-2` (افتراضي) أو `sora-2-pro` | | `duration` | integer | لا | مدة الفيديو: `4` (افتراضي)، `8`، `12` ثانية | | `size` | string | لا | الدقة: `720x1280` (افتراضي)، `1280x720`، `1024x1792`، `1792x1024` | | `image_urls` | array | لا | مصفوفة روابط الصور المرجعية، تستخدم الصورة الأولى فقط، يجب أن تتطابق أبعاد الصورة مع معلمة `size` | | `callback_url` | string | لا | رابط رد الاتصال غير المتزامن | ### مثال أساسي ```shell theme={null} curl -X POST 'https://api.xhuoapi.ai/v1/sora/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "version": "2.0", "prompt": "cat running on the river", "model": "sora-2", "duration": 8, "size": "1280x720" }' ``` كود Python المقابل: ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/sora/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "version": "2.0", "prompt": "cat running on the river", "model": "sora-2", "seconds": 8, "size": "1280x720" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` كود JavaScript المقابل: ```javascript theme={null} const response = await fetch('https://api.xhuoapi.ai/v1/sora/videos', { method: 'POST', headers: { 'accept': 'application/json', 'authorization': 'Bearer {token}', 'content-type': 'application/json' }, body: JSON.stringify({ version: '2.0', prompt: 'cat running on the river', model: 'sora-2', seconds: 8, size: '1280x720' }) }); const data = await response.json(); console.log(data); ``` تنسيق النتيجة مماثل للإصدار 1: ```json theme={null} { "success": true, "task_id": "6bf7fb83-5814-4e3e-a4ad-bfa0c26c0b33", "trace_id": "96166698-4b66-478d-a26b-77a7269c9e01", "data": [ { "id": "c0cc8dad-0954-421f-be8d-02eb063b3263", "video_url": "https://platform.cdn.xhuoapi.ai/sora/xxxxx.mp4", "state": "succeeded" } ] } ``` ### استخدام الصور المرجعية (الإصدار 2.0) في وضع الإصدار 2.0، يمكن تمرير معلمة `image_urls` لإدخال صورة مرجعية لتوجيه توليد الفيديو (تستخدم الصورة الأولى فقط): ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/sora/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "version": "2.0", "prompt": "a person walking through a beautiful garden", "model": "sora-2", "duration": 4, "size": "1280x720", "image_urls": ["https://cdn.xhuoapi.ai/11wfp4.png"] } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` > **ملاحظة**: يجب أن تتطابق أبعاد الصورة المرجعية مع معلمة `size`، على سبيل المثال إذا كانت `size` تساوي `1280x720`، يجب أن تكون أبعاد الصورة 1280×720. ### مقارنة معلمات الإصدار 1.0 و 2.0 | المعلمة | الإصدار 1.0 | الإصدار 2.0 | | --------------- | --------------------- | --------------------------------------- | | `version` | 1.0 (افتراضي) | 2.0 | | `prompt` | ✅ | ✅ | | `model` | ✅ sora-2 / sora-2-pro | ✅ sora-2 / sora-2-pro | | `duration` | ✅ 10/15/25 ثانية | ✅ 4/8/12 ثانية | | `orientation` | ✅ landscape/portrait | ❌ | | `size` | ✅ small/large | ✅ 720x1280/1280x720/1024x1792/1792x1024 | | `image_urls` | ✅ عدة صور مرجعية | ✅ تستخدم الصورة الأولى فقط | | `character_url` | ✅ | ❌ | | `callback_url` | ✅ | ✅ | ## رد الاتصال غير المتزامن (Async Callback) نظرًا لأن توليد فيديوهات Sora يستغرق وقتًا نسبيًا (حوالي 1-2 دقيقة)، وإذا لم يستجب API لفترة طويلة، سيبقى طلب HTTP مفتوحًا مما يستهلك موارد النظام، لذا توفر الواجهة دعمًا لرد الاتصال غير المتزامن. العملية كالتالي: عند إرسال الطلب، يتم تمرير معلمة `callback_url` التي تحدد رابطًا لاستقبال النتيجة. بعد إرسال الطلب، يعيد API فورًا ردًا يحتوي على `task_id` الذي يمثل معرف المهمة. عند الانتهاء من توليد الفيديو، يتم إرسال النتيجة عبر طلب POST بصيغة JSON إلى رابط `callback_url`، ويشمل الرد أيضًا `task_id` لربط النتيجة بالمهمة. فيما يلي مثال توضيحي. أولًا، يجب أن يكون Webhook رابطًا يمكنه استقبال طلبات HTTP، ويجب على المطور استخدام URL لخادم HTTP خاص به. لأغراض العرض، يمكن استخدام موقع Webhook عام مثل [https://webhook.site/،](https://webhook.site/،) حيث يمكن الحصول على رابط Webhook كما في الصورة: ![](https://cdn.xhuoapi.ai/cjjfly.png) انسخ هذا الرابط لاستخدامه كـ Webhook، كمثال: `https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa`. بعدها، قم بتعيين معلمة `callback_url` إلى هذا الرابط، وأدخل المعلمات الأخرى كما في الصورة:

بعد الضغط على تشغيل، ستحصل على نتيجة فورية مثل: ``` { "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea" } ``` بعد فترة قصيرة، يمكنك مراقبة نتيجة توليد الفيديو على الرابط `https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa` كما في الصورة: ![](https://cdn.xhuoapi.ai/0j7nra.png) المحتوى كالتالي: ```json theme={null} { "success": true, "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea", "trace_id": "fb751e1e-4705-49ea-9fd4-5024b7865ea2", "data": [ { "id": "sora-2:task_01k777hjrbfrgs2060q5zvf2a5", "video_url": "https://filesystem.site/gptimage/vg-assets/assets%2Ftask_01k777hjrbfrgs2060q5zvf2a5%2Ftask_01k777hjrbfrgs2060q5zvf2a5_genid_b8e2e5d1-a579-49ca-a21c-cb3869685cce_25_10_10_14_15_147334%2Fvideos%2F00000%2Fsrc.mp4?st=2025-10-10T12%3A38%3A49Z&se=2025-10-16T13%3A38%3A49Z&sks=b&skt=2025-10-10T12%3A38%3A49Z&ske=2025-10-16T13%3A38%3A49Z&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skoid=aa5ddad1-c91a-4f0a-9aca-e20682cc8969&skv=2019-02-02&sv=2018-11-09&sr=b&sp=r&spr=https%2Chttp&sig=p4aMqXqkP%2FI1IhOVGCB9JL8vUUvfNBBF12ESpKhKXOk%3D&az=oaivgprodscus", "state": "succeeded" } ] } ``` يمكن ملاحظة وجود حقل `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" } ``` ## الخلاصة من خلال هذه الوثيقة، تعلمت كيفية استخدام واجهة برمجة تطبيقات توليد فيديوهات Sora لإنشاء فيديوهات عبر إدخال كلمات مفتاحية وصور مرجعية. نأمل أن تساعدك هذه الوثيقة في التكامل والاستخدام الأمثل للواجهة. لأي استفسارات، يرجى التواصل مع فريق الدعم الفني لدينا.