توضيح تكامل واجهة برمجة تطبيقات توليد مقاطع الفيديو من Veo

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

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

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

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

📘 الوثائق الكاملة: واجهة برمجة تطبيقات توليد مقاطع الفيديو من Veo →

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

أولاً، يجب أن نفهم طريقة الاستخدام الأساسية، وهي إدخال كلمة التلميح prompt، وسلوك التوليد action، ومصفوفة صور الإطار الأول والأخير image_urls، والنموذج model، للحصول على النتيجة المعالجة. أولاً، نحتاج إلى تمرير حقل action، الذي تكون قيمته text2video، والذي يتضمن ثلاثة سلوكيات رئيسية: توليد فيديو من نص (text2video)، توليد فيديو من صورة (image2video)، والحصول على فيديو بدقة 1080p (get1080p). ثم نحتاج أيضًا إلى إدخال النموذج model، والذي يتضمن حاليًا النماذج الرئيسية التالية: veo31-fast، veo3، veo31، veo3-fast و veo31-fast-ingredients، والمحتوى المحدد كما يلي:

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

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

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

model: نموذج توليد الفيديو، والذي يتضمن بشكل رئيسي veo31-fast، veo3، veo31، veo3-fast و veo31-fast-ingredients.
action: سلوك مهمة توليد الفيديو هذه، والذي يتضمن ثلاثة سلوكيات رئيسية: توليد فيديو من نص (text2video)، توليد فيديو من صورة (image2video)، والحصول على فيديو بدقة 1080p (get1080p).
image_urls: عند اختيار سلوك توليد فيديو من صورة image2video، يجب تحميل روابط الصور المرجعية. يدعم veo31-fast-ingredients حتى 3 صور (دمج صور متعددة)، بينما تدعم النماذج الأخرى حتى 2 صورة (نموذج الإطار الأول والأخير).
resolution: اختيار دقة الفيديو الناتج، حيث يدعم نموذج veo31 دقة 4k، بينما لا تدعم النماذج الأخرى، وتدعم جميع النماذج دقة 1080p ودقة gif، وإذا لم يتم تمرير هذه القيمة، سيتم استخدام دقة 720p بشكل افتراضي، وتنقسم إلى: 1080p، gif، 4k.
prompt: كلمة التلميح.
callback_url: URL الذي يحتاج إلى استدعاء النتائج.
async: اختياري، إذا تم تعيينه إلى true، ستقوم الواجهة بإرجاع task_id على الفور، دون الحاجة لتوفير callback_url، ثم يمكن استعلام النتائج من خلال واجهة استعلام المهام المقابلة.

📌 ملخص توضيح النموذج

اسم النموذج	أنماط الدعم	قواعد إدخال الصور
veo3-fast	توليد فيديو من نص (بدون صورة) توليد فيديو من صورة (مع صورة)	1 صورة → نموذج الإطار الأول 2 صورة → نموذج الإطار الأول والأخير
veo31-fast	توليد فيديو من نص (بدون صورة) توليد فيديو من صورة (مع صورة)	1 صورة → نموذج الإطار الأول 2 صورة → نموذج الإطار الأول والأخير
veo31-fast-ingredients	❌ توليد فيديو من نص (غير مدعوم) ✅ دمج صور متعددة إجباري (يجب تمرير الصور)	1-3 صور → نموذج دمج الصور المتعددة (حتى 3 صور)
veo3	توليد فيديو من نص (بدون صورة) توليد فيديو من صورة (مع صورة)	1 صورة → نموذج الإطار الأول 2 صورة → نموذج الإطار الأول والأخير
veo31	توليد فيديو من نص (بدون صورة) توليد فيديو من صورة (مع صورة)	1 صورة → نموذج الإطار الأول 2 صورة → نموذج الإطار الأول والأخير

🔑 توضيح القواعد الأساسية

المنطق العام:
- بدون إدخال صورة → يتم تفعيل نموذج توليد الفيديو من نص تلقائيًا.
- مع إدخال صورة → يتم تفعيل نموذج توليد الفيديو من صورة (يحدد السلوك عدد الصور المدخلة).
أنواع نموذج توليد الفيديو من صورة:
- نموذج الإطار الأول (1 صورة): يتم تثبيت الإطار الأول على الصورة المدخلة.
- نموذج الإطار الأول والأخير (2 صورة): يتم تثبيت الإطار الأول والأخير على الصور المدخلة.
- نموذج دمج الصور المتعددة (1-3 صور): يدعم فقط veo31-fast-ingredients، حيث يتم دمج محتوى الصور المتعددة لتوليد الفيديو.
تصنيف الأنماط:

نمط Fast: veo3-fast، veo31-fast، veo31-fast-ingredients.
نمط Quality: veo3، veo31 (توليد بجودة أعلى).

⚠️ ملاحظات هامة

النموذج الوحيد الذي يتطلب إدخال صورة: veo31-fast-ingredients يجب تمرير الصور (1-3 صور)، وإلا فلن يعمل.
حدود عدد الصور:
- يدعم veo31-fast-ingredients 1-3 صور للإدخال (نموذج دمج الصور المتعددة).
- تدعم النماذج الأخرى حتى 2 صورة للإدخال (نموذج الإطار الأول والأخير).

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

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

{
  "success": true,
  "task_id": "697ea2fc-58fd-48c8-8191-29041ff23c3c",
  "trace_id": "70e1cb12-c619-4292-a416-90191205996b",
  "data": [
    {
      "id": "24ac06a5-9cc7-448f-802e-0b4db19f6e96",
      "video_url": "https://platform2.cdn.acedata.cloud/veo/f5389ec0-2eb5-4212-b4a8-04b513b0129a.mp4",
      "created_at": "2026-06-30T04:01:50.364Z",
      "complete_at": "2026-06-30T04:03:20.495Z",
      "state": "succeeded"
    }
  ]
}

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

success، حالة مهمة إنشاء الفيديو في هذه اللحظة.
task_id، معرف مهمة إنشاء الفيديو في هذه اللحظة.
data، نتيجة مهمة إنشاء الفيديو في هذه اللحظة.
- id، معرف الفيديو لمهمة إنشاء الفيديو في هذه اللحظة.
- video_url، رابط الفيديو لمهمة إنشاء الفيديو في هذه اللحظة.
- created_at، وقت إنشاء مهمة إنشاء الفيديو في هذه اللحظة.
- complete_at، وقت إكمال مهمة إنشاء الفيديو في هذه اللحظة.
- state، حالة مهمة إنشاء الفيديو في هذه اللحظة.

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

curl -X POST 'https://api.acedata.cloud/veo/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "veo31-fast",
  "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle."
}'

وظيفة إنشاء الفيديو من الصور

إذا كنت ترغب في إنشاء فيديو بناءً على صور البداية والنهاية، يمكنك تعيين المعامل action إلى image2video، وإدخال مصفوفة روابط صور البداية والنهاية image_urls. بعد ذلك، يجب علينا ملء الخطوة التالية التي تحتاج إلى توسيع الكلمات الرئيسية لتخصيص الفيديو الناتج، ويمكنك تحديد المحتويات التالية:

model：نموذج إنشاء الفيديو، والذي يتضمن بشكل رئيسي veo31-fast، veo3، veo31، veo3-fast و veo31-fast-ingredients.
image_urls：عند اختيار سلوك إنشاء الفيديو من الصور image2video، يجب تحميل روابط الصور المرجعية.
prompt：الكلمات الرئيسية.

مثال على ملء البيانات كما يلي:

بعد ملء البيانات، تم إنشاء الكود تلقائيًا كما يلي:

الكود المقابل بلغة Python:

import requests

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

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

payload = {
    "action": "image2video",
    "model": "veo31-fast",
    "prompt": "Let it dance",
    "image_urls": ["https://cdn.acedata.cloud/7p1jhy.png"]
}

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

عند النقر على التشغيل، يمكنك أن تجد نتيجة كما يلي:

{
  "success": true,
  "task_id": "98e309f3-35bc-438d-8cb3-4015fc864b87",
  "trace_id": "8bc68066-36de-41ef-ae5e-b7d61ff6aee8",
  "data": [
    {
      "id": "59f12222b1fa4fbe9331ff2400ad1583",
      "video_url": "https://platform.cdn.acedata.cloud/veo/98e309f3-35bc-438d-8cb3-4015fc864b87.mp4",
      "created_at": "2025-07-25 16:13:07",
      "complete_at": "2025-07-25 16:16:12",
      "state": "succeeded"
    }
  ]
}

يمكننا أن نرى أن محتوى النتيجة متطابق مع ما سبق، مما يحقق وظيفة إنشاء الفيديو من الصور.

وظيفة الحصول على فيديو بدقة 1080p

إذا كنت ترغب في الحصول على فيديو Veo الذي تم إنشاؤه بدقة 1080p، يمكنك تعيين المعامل action إلى get1080p، وإدخال معرف الفيديو الذي تحتاج إلى الحصول على 1080p له، يتم الحصول على معرف الفيديو بناءً على الاستخدام الأساسي كما هو موضح في الصورة أدناه:

في هذه الحالة، يمكنك رؤية معرف الفيديو كالتالي:

"id": "59f12222b1fa4fbe9331ff2400ad1583"

ملاحظة، هنا معرف الفيديو video_id هو معرف الفيديو بعد الإنشاء، إذا كنت لا تعرف كيفية إنشاء الفيديو، يمكنك الرجوع إلى الاستخدام الأساسي المذكور أعلاه لإنشاء الفيديو.

بعد ذلك، يجب علينا ملء الخطوة التالية التي تحتاج إلى توسيع الكلمات الرئيسية لتخصيص الفيديو الناتج، ويمكنك تحديد المحتويات التالية:

model：نموذج إنشاء الفيديو، والذي يتضمن بشكل رئيسي veo31-fast، veo3، veo31، veo3-fast و veo31-fast-ingredients.
video_id：معرف الفيديو المرجعي، المستخدم للحصول على فيديو بدقة 1080p.

مثال على ملء البيانات كما يلي:

بعد ملء البيانات، تم إنشاء الكود تلقائيًا كما يلي:

عند النقر على التشغيل، يمكنك أن تجد نتيجة كما يلي:

{
  "success": true,
  "task_id": "47a51cfe-2e24-4aba-93b3-546c2dc52984",
  "trace_id": "a8922eec-6f50-4f77-8104-00ded071d59d",
  "data": [
    {
      "id": "59f12222b1fa4fbe9331ff2400ad1583",
      "video_url": "https://platform.cdn.acedata.cloud/veo/47a51cfe-2e24-4aba-93b3-546c2dc52984.mp4",
      "created_at": "2025-07-25 16:13:07",
      "complete_at": "2025-07-25 16:16:12",
      "state": "succeeded"
    }
  ]
}

يمكننا أن نرى أن محتوى النتيجة متطابق مع ما سبق، مما يحقق وظيفة الحصول على فيديو بدقة 1080p.

تحديد حجم الفيديو عند الإنشاء

إذا كنت ترغب في تحديد حجم فيديو Veo المخصص عند الإنشاء، يمكنك تعيين المعامل aspect_ratio إلى الحجم المطلوب، بعد ذلك يجب علينا ملء الخطوة التالية التي تحتاج إلى توسيع الكلمات الرئيسية لتخصيص الفيديو الناتج، ويمكنك تحديد المحتويات التالية:

model：نموذج إنشاء الفيديو، والذي يتضمن بشكل رئيسي veo31-fast، veo3، veo31، veo3-fast و veo31-fast-ingredients.
aspect_ratio：حجم الفيديو، حاليًا يدعم: 16:9، 16:9، 3:4، 4:3، 1:1، الافتراضي هو 16:9.
translation：هل ترغب في تفعيل الترجمة التلقائية للكلمات الرئيسية، الافتراضي هو false. مثال على ملء البيانات كما يلي:

بعد ملء البيانات، تم إنشاء الكود تلقائيًا كما يلي:

عند النقر على التشغيل، يمكنك أن تجد نتيجة كما يلي:

{
  "success": true,
  "task_id": "d2b93290-ab0e-4d20-ae45-60c062a32687",
  "trace_id": "9834e64d-c8fe-43ae-8114-ee2b5f93d886",
  "data": [
    {
      "id": "fc667e7d3b8f44beaa61a3c339af0e50",
      "video_url": "https://platform.cdn.acedata.cloud/veo/d2b93290-ab0e-4d20-ae45-60c062a32687.mp4",
      "created_at": "2025-08-24 20:09:06",
      "complete_at": "2025-08-24 20:10:45",
      "state": "succeeded"
    }
  ]
}

يمكن ملاحظة أن محتوى النتيجة يتوافق مع ما سبق، مما يحقق وظيفة إنشاء الفيديو بحجم محدد.

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

نظرًا لأن وقت إنشاء فيديوهات Veo Videos Generation API طويل نسبيًا، حيث يحتاج حوالي 1-2 دقيقة، إذا لم يكن هناك استجابة من API لفترة طويلة، ستظل طلبات HTTP متصلة، مما يؤدي إلى استهلاك موارد النظام الإضافية، لذا فإن هذه API توفر أيضًا دعمًا للردود غير المتزامنة. تتمثل العملية العامة في: عندما يقوم العميل بإرسال الطلب، يحدد حقل callback_url إضافي، بعد أن يقوم العميل بإرسال طلب API، ستقوم API على الفور بإرجاع نتيجة تحتوي على معلومات حقل task_id، الذي يمثل معرف المهمة الحالية. عند اكتمال المهمة، سيتم إرسال نتيجة إنشاء الفيديو إلى callback_url المحدد من قبل العميل عبر POST JSON، والتي تتضمن أيضًا حقل task_id، بحيث يمكن ربط نتيجة المهمة من خلال المعرف. دعونا نفهم كيفية القيام بذلك من خلال مثال. أولاً، ردود Webhook هي خدمة يمكنها استقبال طلبات HTTP، يجب على المطورين استبدالها بعنوان URL الخاص بخادم HTTP الذي قاموا بإنشائه. هنا، لتسهيل العرض، نستخدم موقع Webhook عام https://webhook.site/، بفتح هذا الموقع يمكنك الحصول على عنوان URL لـ Webhook، كما هو موضح في الصورة:

قم بنسخ هذا العنوان URL، يمكنك استخدامه كـ Webhook، والعينة هنا هي https://webhook.site/aed5cd28-f8aa-4dca-9480-8ec9b42137dc. بعد ذلك، يمكننا تعيين حقل callback_url إلى عنوان URL الخاص بـ Webhook المذكور أعلاه، مع ملء المعلمات المناسبة، كما هو موضح في الصورة:

عند النقر على تشغيل، يمكنك أن تلاحظ أنك ستحصل على نتيجة على الفور، كما يلي:

{
  "task_id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed"
}

بعد لحظات، يمكنك ملاحظة نتيجة إنشاء الفيديو على https://webhook.site/aed5cd28-f8aa-4dca-9480-8ec9b42137dc، كما هو موضح في الصورة:

المحتوى كما يلي:

{
  "success": true,
  "task_id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed",
  "trace_id": "d1d53c04-58c5-4c40-bb63-f00188540e56",
  "data": [
    {
      "id": "2f43ceed37944b4d836e1a1899dad0a1",
      "video_url": "https://platform.cdn.acedata.cloud/veo/1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed.mp4",
      "created_at": "2025-07-25 17:19:20",
      "complete_at": "2025-07-25 17:21:45",
      "state": "succeeded"
    }
  ]
}

يمكنك أن ترى أن النتيجة تحتوي على حقل task_id، بينما الحقول الأخرى مشابهة لما سبق، من خلال هذا الحقل يمكن تحقيق ارتباط المهمة.

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

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

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"
}

الخاتمة

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

البداية

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

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

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

الصوت الذكي

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

CAPTCHA

الهوية

وكيل

متقدم

توضيح تكامل واجهة برمجة تطبيقات توليد مقاطع الفيديو من Veo

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

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

📌 ملخص توضيح النموذج

🔑 توضيح القواعد الأساسية

⚠️ ملاحظات هامة

وظيفة إنشاء الفيديو من الصور

وظيفة الحصول على فيديو بدقة 1080p

تحديد حجم الفيديو عند الإنشاء

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

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

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

الخاتمة

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

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

​📌 ملخص توضيح النموذج

​🔑 توضيح القواعد الأساسية

​⚠️ ملاحظات هامة

​وظيفة إنشاء الفيديو من الصور

​وظيفة الحصول على فيديو بدقة 1080p

​تحديد حجم الفيديو عند الإنشاء

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

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

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

​الخاتمة

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

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

📌 ملخص توضيح النموذج

🔑 توضيح القواعد الأساسية

⚠️ ملاحظات هامة

وظيفة إنشاء الفيديو من الصور

وظيفة الحصول على فيديو بدقة 1080p

تحديد حجم الفيديو عند الإنشاء

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

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

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

الخاتمة