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

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

لاستخدام واجهة برمجة التطبيقات، يجب أولاً الذهاب إلى واجهة برمجة تطبيقات توليد مقاطع الفيديو من Veo وتقديم طلب للحصول على الخدمة المناسبة، بعد الدخول إلى الصفحة، انقر على زر “Acquire”، كما هو موضح في الصورة: إذا لم تكن قد قمت بتسجيل الدخول أو التسجيل بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، وبعد تسجيل الدخول، سيتم العودة تلقائيًا إلى الصفحة الحالية. عند التقديم لأول مرة، سيكون هناك حد مجاني متاح، يمكنك استخدام واجهة برمجة التطبيقات مجانًا.

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

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

يمكنك أن ترى هنا أننا قمنا بتعيين رؤوس الطلب، بما في ذلك:
  • accept: نوع الاستجابة التي ترغب في تلقيها، هنا يتم ملؤها بـ application/json، أي بتنسيق JSON.
  • authorization: مفتاح استدعاء واجهة برمجة التطبيقات، بعد التقديم يمكنك اختياره مباشرة من القائمة المنسدلة.
بالإضافة إلى ذلك، تم تعيين جسم الطلب، بما في ذلك:
  • model: نموذج توليد الفيديو، والذي يتضمن veo2، veo2-fast، veo3، veo31، veo31-fast، veo31-fast-ingredients و veo3-fast.
  • action: سلوك مهمة توليد الفيديو هذه، والتي تتضمن ثلاثة سلوكيات، وهي: توليد فيديو من نص (text2video)، توليد فيديو من صورة (image2video)، والحصول على فيديو بدقة 1080p (get1080p).
  • image_urls: عند اختيار سلوك توليد فيديو من صورة image2video، يجب تحميل روابط صور الإطار الأول والأخير، بحد أقصى ثلاث صور مرجعية.
  • resolution: اختيار دقة الفيديو الناتج، حيث يدعم نموذج veo31 دقة 4k، بينما لا تدعم النماذج الأخرى، جميع النماذج تدعم دقة 1080p وgif، وإذا لم يتم تمرير هذه القيمة، سيتم استخدام دقة 720p بشكل افتراضي، والتي تنقسم إلى: 1080p، gif، 4k.
  • prompt: كلمة التلميح.
  • callback_url: URL الذي يحتاج إلى استدعاء النتائج.

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

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

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

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

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

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

انقر على زر “Try” لإجراء الاختبار، كما هو موضح في الصورة أعلاه، وهنا حصلنا على النتيجة التالية: 
{
  "success": true,
  "task_id": "dd01fc69-e1f7-4b68-aa8c-463f6b748d11",
  "trace_id": "9906dac0-1516-41dc-9fe3-067ca1ba8269",
  "data": [
    {
      "id": "253eedc47f1c4eb2a370ed2312168f4b",
      "video_url": "https://platform.cdn.acedata.cloud/veo/dd01fc69-e1f7-4b68-aa8c-463f6b748d11.mp4",
      "created_at": "2025-07-25 16:07:43",
      "complete_at": "2025-07-25 16:10:28",
      "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": "veo2",
  "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：نموذج إنشاء الفيديو، والذي يتضمن بشكل رئيسي veo2، veo2-fast، veo3 و veo3-fast.
  • 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": "veo2",
    "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"
ملاحظة، معرف الفيديو هنا هو معرف الفيديو الناتج بعد الإنشاء، إذا كنت لا تعرف كيفية إنشاء الفيديو، يمكنك الرجوع إلى الاستخدام الأساسي المذكور أعلاه لإنشاء الفيديو.
بعد ذلك، يجب علينا ملء الخطوة التالية التي تحتاج إلى توسيع الكلمات الرئيسية لتخصيص الفيديو الناتج، ويمكنك تحديد المحتويات التالية:
  • model：نموذج إنشاء الفيديو، والذي يتضمن بشكل رئيسي veo2، veo2-fast، veo3 و veo3-fast.
  • 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：نموذج إنشاء الفيديو، والذي يتضمن بشكل رئيسي veo2، veo2-fast، veo3 و veo3-fast.
  • 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. إذا كان لديك أي استفسارات، فلا تتردد في الاتصال بفريق الدعم الفني لدينا.