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

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

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

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

يحدد action وضع التوليد لهذا الطلب:
  • generate: توليد فيديو من النص، وهو الإجراء الافتراضي، ويدعم 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، يمكن لـ image_urls تمرير 1–9 صور مرجعية. يمكن في النص التوجيهي استخدام character1 وcharacter2 وغيرها للإشارة إلى الصور بالترتيب المقابل.

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

ترث مدة الإخراج وأبعاد الإطار في video_edit فيديو المصدر، ولن يؤدي تمرير duration أو ratio إلى تغييرهما؛ كما أن أبعاد الإطار لفيديو توليد الصور ترث صورة المصدر. تُحسب تكلفة التحرير وفقًا لمجموع مدة فيديو الإدخال والإخراج. عند استخدام 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: خطأ داخلي في الخادم أو فشل الإنشاء.