شرح تكامل Veo Videos Generation API

​

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

📘 الوثائق الكاملة: Veo Videos Generation API →

​

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

• 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 صور (دمج صور متعددة)، بينما تدعم النماذج الأخرى حتى صورتين (وضع الإطارين الأول والأخير).
• resolution: اختيار دقة الفيديو المُنشأ، حيث يدعم نموذج veo31 دقة 4k، ولا تدعمها النماذج الأخرى، وتدعم جميع النماذج دقة 1080p وgif، وإذا لم يتم تمرير هذه القيمة فسيتم استخدام دقة 720p افتراضيًا، وتنقسم بشكل أساسي إلى: 1080p، gif، 4k.
• prompt: كلمة التوجيه.
• callback_url: عنوان URL الذي يحتاج إلى نتيجة رد الاتصال.
• async: اختياري، عند تعيينه إلى true، تُرجع الواجهة task_id فورًا، ولا حاجة لتقديم callback_url، ثم يتم الحصول على النتيجة عبر الاستعلام الدوري من خلال واجهة الاستعلام عن المهمة المقابلة.

​

📌 ملخص شرح النماذج

​

🔑 شرح القواعد الرئيسية

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

• وضع Fast: veo3-fast وveo31-fast وveo31-fast-ingredients.
• وضع Quality: veo3 وveo31 (جودة إنشاء أعلى).

​

⚠️ ملاحظات

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

{
  "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://cdn.acedata.cloud/assets/examples/veo/f5389ec0-2eb5-4212-b4a8-04b513b0129a-0b0c3113d691.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، حالة مهمة إنشاء الفيديو في هذا الوقت.

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

​

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

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

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

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

​

الإنشاء بمقاس فيديو محدد

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

​

الاستدعاء غير المتزامن

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

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

​

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

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

​

الخلاصة