> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# شرح تكامل HappyHorse Videos API

> HappyHorse Video API guide - Ace Data Cloud

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

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

لاستخدام HappyHorse Videos API، انتقل أولاً إلى [وحدة تحكم Ace Data Cloud](https://platform.acedata.cloud/console/applications) للحصول على API Token الخاص بك، واحتفظ به للاستخدام لاحقًا.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

إذا لم تقم بتسجيل الدخول أو التسجيل بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك إلى التسجيل وتسجيل الدخول، وبعد الانتهاء ستعود تلقائيًا إلى الصفحة الحالية.

**يمكن لـ API Token واحد استدعاء جميع خدمات المنصة، ولا حاجة للتقديم بشكل منفصل لكل خدمة.** سيُمنح لك رصيد مجاني عند أول تقديم، ويمكنك التجربة مجانًا؛ وعندما لا يكون الرصيد كافيًا، يمكنك شحن الرصيد العام من [وحدة التحكم](https://platform.acedata.cloud/console/coin).

> 📘 الوثائق الكاملة: [HappyHorse Videos API →](https://platform.acedata.cloud/documents/happyhorse-videos)

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

تحدد `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`:

```json theme={null}
{
  "action": "generate",
  "model": "happyhorse-1.1-t2v",
  "prompt": "A cinematic white horse lifts its head, the mane moves gently in the sunrise wind, slow camera push in, warm film lighting",
  "resolution": "720P",
  "ratio": "16:9",
  "duration": 5
}
```

مثال على النتيجة المُعادة كما يلي:

```json theme={null}
{
  "success": true,
  "task_id": "27837f92-d1c1-4db4-ad9a-4e6e81d9f6c1",
  "trace_id": "6071ab5e-2f37-46f0-9e07-f1e378112e69",
  "data": [
    {
      "id": "9650580f-6d9e-4bc1-823a-29011790c5cb",
      "video_url": "https://cdn.acedata.cloud/assets/examples/happyhorse/27837f92-d1c1-4db4-ad9a-4e6e81d9f6c1-2c108ce23554.mp4",
      "state": "succeeded",
      "duration": 5,
      "resolution": "720P",
      "ratio": null
    }
  ]
}
```

وصف الحقول:

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

رمز CURL المقابل كما يلي:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/happyhorse/videos' \
-H 'authorization: Bearer ${bearer_token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "model": "happyhorse-1.1-t2v",
  "prompt": "A cinematic white horse lifts its head, the mane moves gently in the sunrise wind, slow camera push in, warm film lighting",
  "resolution": "720P",
  "ratio": "16:9",
  "duration": 5
}'
```

رمز Python المقابل كما يلي:

```python theme={null}
import requests

url = "https://api.acedata.cloud/happyhorse/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json",
}

payload = {
    "action": "generate",
    "model": "happyhorse-1.1-t2v",
    "prompt": "A cinematic white horse lifts its head, the mane moves gently in the sunrise wind, slow camera push in, warm film lighting",
    "resolution": "720P",
    "ratio": "16:9",
    "duration": 5,
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

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

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

```json theme={null}
{
  "action": "image_to_video",
  "model": "happyhorse-1.1-i2v",
  "image_url": "https://cdn.acedata.cloud/b1c82e4937.png",
  "prompt": "A cinematic white horse lifts its head, the mane moves gently in the sunrise wind, slow camera push in, warm film lighting",
  "resolution": "1080P",
  "duration": 5
}
```

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

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

```json theme={null}
{
  "action": "reference_to_video",
  "model": "happyhorse-1.1-r2v",
  "prompt": "character1 walks forward through a sunrise meadow with the warm leather and gold trim style from character2",
  "image_urls": [
    "https://cdn.acedata.cloud/b1c82e4937.png",
    "https://cdn.acedata.cloud/eb75d88a3f.png"
  ],
  "resolution": "720P",
  "ratio": "16:9",
  "duration": 5
}
```

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

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

```json theme={null}
{
  "action": "video_edit",
  "model": "happyhorse-1.0-video-edit",
  "prompt": "Apply the warm leather and gold trim style from the reference image while preserving the original camera motion",
  "video_url": "https://cdn.acedata.cloud/assets/examples/happyhorse/27837f92-d1c1-4db4-ad9a-4e6e81d9f6c1-2c108ce23554.mp4",
  "image_urls": [
    "https://cdn.acedata.cloud/eb75d88a3f.png"
  ],
  "resolution": "720P",
  "audio_setting": "auto"
}
```

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

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

```json theme={null}
{
  "action": "generate",
  "prompt": "A horse running through a snowy forest",
  "duration": 5,
  "callback_url": "https://your-domain.com/callback/happyhorse"
}
```

تكون النتيجة المُعادة فورًا كما يلي:

```json theme={null}
{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}
```

إذا كنت ترغب في الاستعلام الدوري فقط ولا تحتاج إلى رد اتصال، يمكنك أيضًا تمرير `"async": true`، ثم الاستعلام عن نتيجة المهمة عبر [HappyHorse Tasks API](https://platform.acedata.cloud/documents/happyhorse-tasks).

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

تُحتسب رسوم 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`: خطأ داخلي في الخادم أو فشل التوليد.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.