/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.
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: نسبة العرض إلى الارتفاع للإخراج.
توليد الفيديو من صورة الإطار الأول
عند استخدام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: خطأ داخلي في الخادم أو فشل التوليد.

