/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.
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، يمكن لـ 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: خطأ داخلي في الخادم أو فشل الإنشاء.

