توضيح تكامل واجهة برمجة تطبيقات توليد فيديوهات 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: مفتاح استدعاء واجهة برمجة التطبيقات، يمكن اختياره مباشرة بعد التقديم.

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

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، حيث يتم دمج محتوى الصور المتعددة لتوليد الفيديو.
تصنيف الأنماط:

نمط سريع: veo3-fast، veo31-fast، veo31-fast-ingredients.
نمط جودة: 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": "فنجان قهوة خزفي أبيض على سطح رخام لامع مع ضوء نافذة الصباح. الكاميرا تدور ببطء 360 درجة حول الفنجان، متوقفة لفترة وجيزة عند المقبض."
}'

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

إذا كنت ترغب في إنشاء فيديو بناءً على صور الإطارات الأولى والأخيرة، يمكنك تعيين المعامل 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": "دعها ترقص",
    "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

الهوية

وكيل

متقدم

Coding

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

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

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

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

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

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

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

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

تحديد حجم الفيديو الناتج

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

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

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

الخاتمة

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

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

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

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

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

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

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

​تحديد حجم الفيديو الناتج

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

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

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

​الخاتمة

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

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

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

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

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

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

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

تحديد حجم الفيديو الناتج

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

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

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

الخاتمة