Skip to main content
توضح هذه المقالة طريقة تكامل HappyHorse Videos API. تدعم هذه الواجهة توليد الفيديو من النص، وتوليد الفيديو من صورة الإطار الأول، وتوليد الفيديو من الصور المرجعية، وتحرير الفيديو من خلال المدخل الموحد /happyhorse/videos ومعلمة action.

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

لاستخدام HappyHorse Videos API، انتقل أولاً إلى وحدة تحكم Ace Data Cloud للحصول على API Token الخاص بك، واحتفظ به للاستخدام لاحقًا. إذا لم تقم بتسجيل الدخول أو التسجيل بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك إلى التسجيل وتسجيل الدخول، وبعد الانتهاء ستعود تلقائيًا إلى الصفحة الحالية. يمكن لـ API Token واحد استدعاء جميع خدمات المنصة، ولا حاجة للتقديم بشكل منفصل لكل خدمة. سيُمنح لك رصيد مجاني عند أول تقديم، ويمكنك التجربة مجانًا؛ وعندما لا يكون الرصيد كافيًا، يمكنك شحن الرصيد العام من وحدة التحكم.
📘 الوثائق الكاملة: HappyHorse Videos API →

أنواع العمليات

تحدد action وضع التوليد لهذا الطلب:
  • generate: توليد الفيديو من النص، وهي action الافتراضية، وتدعم happyhorse-1.0-t2v وhappyhorse-1.1-t2v، ويجب تمرير prompt.
  • image_to_video: توليد الفيديو من صورة الإطار الأول، وتدعم happyhorse-1.0-i2v وhappyhorse-1.1-i2v، ويجب تمرير image_url.
  • reference_to_video: توليد الفيديو من الصور المرجعية، وتدعم happyhorse-1.0-r2v وhappyhorse-1.1-r2v، ويجب تمرير prompt و1–9 صور image_urls.
  • video_edit: تحرير الفيديو، ويدعم happyhorse-1.0-video-edit، ويجب تمرير prompt وvideo_url، ويمكن تمرير 0–5 صور مرجعية إضافية image_urls.
تستخدم كل عملية نموذج 1.1 افتراضيًا؛ أما video_edit فلا يتوفر حاليًا إلا بـ happyhorse-1.0-video-edit.

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

لا يتطلب توليد الفيديو من النص سوى توفير prompt، ويمكنك أيضًا تحديد معلمات مثل resolution وratio وduration:
مثال على النتيجة المُعادة كما يلي:
وصف الحقول:
  • success: ما إذا كان هذا الطلب ناجحًا.
  • task_id: معرّف المهمة من جانب Ace Data Cloud، ويمكن استخدامه للاستعلام عن حالة المهمة.
  • trace_id: معرّف تتبع هذا الطلب، ويُستخدم لاستكشاف المشكلات وإصلاحها.
  • data: قائمة نتائج الفيديو.
    • id: معرّف المهمة من جانب HappyHorse.
    • video_url: عنوان رابط CDN للفيديو المُولّد.
    • state: حالة المهمة، وتشمل pending / succeeded / error.
    • duration: مدة الفيديو التي يتم احتساب رسومها، بوحدة الثواني؛ وفي video_edit تكون إجمالي مدة فيديو الإدخال والإخراج.
    • resolution: دقة الإخراج.
    • ratio: نسبة العرض إلى الارتفاع للإخراج.
رمز CURL المقابل كما يلي:
رمز Python المقابل كما يلي:

توليد الفيديو من صورة الإطار الأول

عند استخدام image_to_video، سيتم استخدام image_url كإطار أول للفيديو. ستحاول نسبة العرض إلى الارتفاع للإخراج اتباع صورة الإطار الأول، لذلك لا تحتاج هذه العملية إلى تمرير ratio.

توليد الفيديو من الصور المرجعية

عند استخدام reference_to_video، يمكن تمرير 1–9 صور مرجعية في image_urls. يمكن استخدام character1 وcharacter2 وما إلى ذلك في النص الإرشادي للإشارة إلى الصور بالترتيب المقابل.

تحرير الفيديو

عند استخدام video_edit، يجب تمرير الفيديو المراد تحريره video_url ونية التحرير prompt. ستُستخدم image_urls الاختيارية كصور مرجعية، مثل تغيير الملابس أو نقل الأسلوب أو الاستبدال الجزئي. يمكن أن تكون audio_setting اختيارياً auto أو origin، حيث يشير origin إلى الاحتفاظ بصوت الفيديو الأصلي.

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

تحتاج عملية توليد الفيديو إلى وقت معين للمعالجة. إذا كنت لا ترغب في إبقاء الاتصال الطويل منتظرًا، يمكنك تمرير callback_url، وعندها ستُرجع API فورًا task_id، وبعد اكتمال المهمة سيتم إرسال النتيجة النهائية عبر POST إلى هذا العنوان:
تكون النتيجة المُعادة فورًا كما يلي:
إذا كنت ترغب في الاستعلام الدوري فقط ولا تحتاج إلى رد اتصال، يمكنك أيضًا تمرير "async": true، ثم الاستعلام عن نتيجة المهمة عبر HappyHorse Tasks API.

توضيح الفوترة

تُحتسب رسوم HappyHorse بناءً على عدد ثواني الفيديو الناتج ودقة العرض:
  • 720P: تبدأ من حوالي $0.105 / ثانية.
  • 1080P: تبدأ من حوالي $0.18 / ثانية.
  • video_edit: تُحتسب الرسوم وفقًا لإجمالي مدة الفيديو المُدخل والفيديو الناتج، وتخضع مدة الفوترة الفعلية للإحصاءات بعد اكتمال المهمة.
لا تُحتسب رسوم المهام الفاشلة، ولا تستهلك الرصيد المجاني.

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

عند حدوث مشكلة في الطلب، ستُرجع API رمز الخطأ والوصف المقابلين، ومن الشائع ما يلي:
  • 400: معلمات الطلب غير صحيحة، مثل عدم تطابق action مع model، أو غياب prompt / image_url / video_url، أو تجاوز duration للنطاق من 3 إلى 15 ثانية.
  • 401: فشل المصادقة، أو أن token غير صالح أو لا يتطابق مع API.
  • 403: الرصيد غير كافٍ، أو تم رفض الطلب لأن النص التوجيهي خضع لمراجعة المحتوى.
  • 429: الطلبات متكررة جدًا، مما أدى إلى تفعيل حدّ المعدل، يُرجى إعادة المحاولة لاحقًا.
  • 500: خطأ داخلي في الخادم أو فشل التوليد.