> ## 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.

# دليل تكامل Flux Videos API

> Flux API guide - Ace Data Cloud

يستخدم Flux Videos API ‏`POST /flux/videos` لإكمال إنشاء الفيديو، وإنشاء فيديو من صور الإطارات الرئيسية، واستكمال الفيديو، وتحسين المسودة. `action=generate` (افتراضيًا)، ويحدد `mode` وضع الإنشاء؛ ويُستخدم `POST /flux/tasks` الموجود بالفعل بشكل موحد للاستعلام عن النتائج.

> حاليًا في Beta. تم فتح إنشاء الفيديو من النص، وإنشاء الفيديو من الصور، واستكمال الفيديو، وتحسين المسودة. يشير HTTP 200 ومعرّف المهمة فقط إلى قبول المهمة، ويجب الاستمرار في الاستعلام عن النتيجة النهائية.

## 1. الحصول على API Token

1. سجّل أو سجّل الدخول في [وحدة تحكم Ace Data Cloud](https://platform.acedata.cloud/console/applications)، وأنشئ تطبيقًا واحصل على API Token. يمكن لـ API Token عام استدعاء خدمات المنصة؛ يُرجى التأكد من أن التطبيق يمتلك صلاحية استدعاء خدمة Flux ورصيدًا متاحًا.
2. اعرض الباقات وأسعار كل عملية في [صفحة خدمة Flux](https://platform.acedata.cloud/services/flux?tab=pricing). عند عدم كفاية الرصيد، أعد الشحن في [صفحة رصيد وحدة التحكم](https://platform.acedata.cloud/console/coin).
3. تستخدم الطلبات `Authorization: Bearer <الـ Token الخاص بك>`. يجب حفظ Token في متغيرات بيئة الخادم، ولا تكتبه في صفحات الواجهة الأمامية أو المستودعات العامة أو لقطات الشاشة أو عناوين URL الخاصة برد النداء.

![طلب API Token من وحدة التحكم](https://cdn.acedata.cloud/dvc3cg.jpg)

تقرأ أكواد هذه المقالة متغير البيئة بشكل موحد:

```bash theme={null}
export ACEDATACLOUD_API_TOKEN='替换为你自己的 API Token'
```

| العنصر | القيمة |
| - | - |
| عنوان جذر API | `https://api.acedata.cloud` |
| إرسال مهمة فيديو | `POST /flux/videos` |
| الاستعلام عن مهمة موجودة | `POST /flux/tasks` |
| المصادقة | `Authorization: Bearer $ACEDATACLOUD_API_TOKEN` |
| تنسيق الطلب | `Content-Type: application/json` |

للاطلاع على الحقول الكاملة والتصحيح عبر الإنترنت، راجع [Flux Videos API](https://platform.acedata.cloud/documents/flux-videos)، ولاستعلام المهمة راجع [Flux Tasks API](https://platform.acedata.cloud/documents/flux-tasks).

## 2. اختيار العملية والإدخال

| action | mode | الإدخال | النتيجة |
| - | - | - | - |
| `generate` (القيمة الافتراضية عند حذف action) | `t2v` | `prompt` | إنشاء فيديو من النص |
| `generate` | `i2v` | `prompt`、`keyframes` | إنشاء فيديو من إطار رئيسي واحد أو عدة إطارات رئيسية |
| `generate` | `v2v` | `prompt`、`start_video` | استكمال بناءً على فيديو الإدخال |
| `generate` | `draft_enhance` | `draft_task_id` لمسودة أكملتها بنفسك | تحسين هذه المسودة |

نموذج الإنشاء هو `flux-3`، و`action` هو `generate` (افتراضيًا). اختر إنشاء الفيديو من النص أو الصور أو استكمال الفيديو أو تحسين المسودة عبر `mode`.

### معلمات الإنشاء العامة

| المعلمة | الوصف |
| - | - |
| `mode` | مطلوب؛ `t2v` أو `i2v` أو `v2v` أو `draft_enhance` |
| `prompt` | مطلوب للإنشاء العادي؛ لا يسمح تحسين المسودة بتجاوز النص الأصلي |
| `duration` | لـ t2v/i2v عدد صحيح من 5–20 ثانية، ولـ v2v عدد صحيح من 5–15 ثانية، أو `auto`؛ قد تختلف مدة الإخراج النهائية قليلًا عن القيمة المطلوبة |
| `resolution` | `hd` أو `fhd` أو `qhd` أو `uhd`؛ القيمة الافتراضية للإنشاء العادي هي `hd`، ولتحسين المسودة هي `fhd` |
| `aspect_ratio` | `auto` أو `21:9` أو `2:1` أو `16:9` أو `4:3` أو `1:1` أو `3:4` أو `9:16` أو `9:21` |
| `draft` | ما إذا كان سيتم إنشاء مسودة أولًا؛ تدعم المسودة `hd` فقط |
| `generate_audio` | ما إذا كان سيتم إنشاء صوت متزامن؛ `false` قيمة صالحة، يُرجى الاحتفاظ بالقيمة المنطقية الصريحة |
| `safety_tolerance` | اختياري؛ عدد صحيح من 0–4 |
| `async` | يُوصى بتعيينه إلى `true`، لإرجاع معرّف مهمة المنصة فورًا ثم استطلاع النتيجة |
| `callback_url` | اختياري؛ عنوان HTTP(S) يستقبل نتيجة JSON النهائية؛ سيتم قبوله أيضًا بشكل غير متزامن بعد الإعداد |

يجب أن يكون عنوان URL للمادة قابلًا للقراءة من قبل الخدمة. إذا استُخدم عنوان URL موقّع مؤقت، فيجب تخصيص مدة صلاحية كافية للتنزيل والمعالجة. لا تستخدم عنوان صفحة ويب كعنوان لملف صورة أو فيديو.

## 3. إنشاء فيديو من النص: طلب كامل مختبر ونتيجته

تم تنفيذ الطلب التالي بنجاح على واجهة الإنتاج قبل تعديل السعر في 2026-10-02. أدى حذف `action` إلى التحقق من سلوك الإنشاء الافتراضي؛ ويتجنب `async=true` الانتظار الطويل لاتصال HTTP.

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/flux/videos' \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "flux-3",
    "mode": "t2v",
    "prompt": "A small toy sailboat floating on calm blue water in warm morning light, steady camera, no text.",
    "duration": 5,
    "resolution": "hd",
    "draft": true,
    "async": true
  }'
```

استجابة القبول (معرّف مهمة حقيقي):

```json theme={null}
{
  "task_id": "4341eb66-3845-4972-bb86-712a6cfae845",
  "trace_id": "b0f851bd-0925-43ca-acc3-6f634c70d607"
}
```

احفظ `task_id` من استجابتك الخاصة، وتابع الاستعلام؛ لا تستخدم معرّف المهمة الموجود في مثال الوثائق للاستعلام عن نتائج حسابات أخرى.

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/flux/tasks' \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"action":"retrieve","id":"替换为本次返回的 task_id"}'
```

يتضمن حقل `response` الذي يعيده استعلام المهمة نتيجة الأعمال النهائية. فيما يلي `response` الناجح الذي تم اختباره هذه المرة، مع حذف البيانات الوصفية للمهمة الخارجية. تم استبدال عنوان URL للفيديو في الوثائق بنسخة من الملف نفسه على CDN تجريبي طويل الأمد (SHA-256 متطابق)، بينما ستعيد الاستدعاءات الفعلية عنوان URL لنتيجة هذه المهمة الخاصة:

```json theme={null}
{
  "success": true,
  "task_id": "4341eb66-3845-4972-bb86-712a6cfae845",
  "trace_id": "b0f851bd-0925-43ca-acc3-6f634c70d607",
  "data": [
    {
      "id": "4341eb66-3845-4972-bb86-712a6cfae845",
      "model": "flux-3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/flux/4341eb66-3845-4972-bb86-712a6cfae845-5f4391e1942c.mp4",
      "seconds": 5.041667,
      "width": 1280,
      "height": 704,
      "fps": 24,
      "draft_task_id": "4341eb66-3845-4972-bb86-712a6cfae845"
    }
  ],
  "usage": {
    "action": "generate",
    "seconds": 5.041667,
    "output_mp_seconds": 4.3326825781250005,
    "mode": "t2v",
    "resolution": "hd",
    "draft": true
  },
  "cost": {
    "amount": 2.6884689277500002,
    "currency": "credit",
    "list_amount": 2.9871876975000005
  }
}
```

[عرض فيديو الاختبار الفعلي هذا](https://cdn.acedata.cloud/assets/examples/flux/4341eb66-3845-4972-bb86-712a6cfae845-5f4391e1942c.mp4). يؤكد فحص الوسائط أن الناتج هو MP4 بدقة 1280×704، ومعدل 24 إطارًا في الثانية، ومدة 5.041667 ثانية، وحجم ملف 2,607,276 بايت.

| حقل الاستجابة | الاستخدام |
| - | - |
| `success` | ما إذا كانت المهمة النهائية ناجحة؛ إعادة task\_id في مرحلة القبول لا تعني success=true |
| `task_id` | معرّف مهمة المنصة، يُستخدم للاستعلام الدوري ومعالجة عدم التكرار في الأعمال |
| `trace_id` | يُقدَّم لموظفي الدعم عند استكشاف المشكلات وإصلاحها |
| `data[].video_url` | عنوان نتيجة الفيديو القابل للقراءة |
| `data[].seconds/width/height/fps` | المدة والأبعاد ومعدل الإطارات الفعلية للناتج التي يقيسها الخادم |
| `data[].draft_task_id` | معرّف الإدخال لتعزيز المسودة؛ يظهر فقط عند إرجاع مسودة قابلة لإعادة الاستخدام |
| `usage` | استخدام الفوترة النهائي؛ لا تستخدم duration في الطلب لاستبدال seconds الفعلية |
| `cost.amount` | Credits التي خُصمت نهائيًا هذه المرة؛ `currency=credit` ليست دولارًا |
| `cost.list_amount` | Credits لاستهلاك مستخدم التطبيق قبل خصم الاستهلاك؛ تُعاد عند الاقتضاء |

هذا اختبار فعلي تاريخي قبل تعديل السعر: `list_amount=2.9871876975` Credits، وكان الحساب يتمتع حينها بخصم استهلاك بنسبة 10%، وكان `amount=2.68846892775` Credits الفعلي. انخفض السعر الجديد في 2026-10-02 بنحو 6.33%؛ تبلغ تكلفة المسودة نفسها لمدة 5.041667 ثانية بالسعر الحالي 2.798125185 Credits (قبل خصم الاستهلاك)، وإذا استمر التمتع بخصم استهلاك بنسبة 10% فستبلغ 2.5183126665 Credits. لا يُعاد احتساب فواتير المهام التاريخية. قد تختلف الباقات والخصومات للحسابات الأخرى؛ وهذا ليس سعرًا ثابتًا بالدولار لجميع المستخدمين.

## 4. تحويل الصور إلى فيديو: عادي ومع إطارات رئيسية زمنية

فيما يلي أمثلة للمعلمات، ويجب استبدال عناوين URL للمواد، وليست إقرارًا بأن هذا المثال قد نُفذ بنجاح بالفعل. بعد اكتمال التوليد، استعلم وفق العملية المذكورة أعلاه، وبنية النتيجة هي نفسها.

تستخدم صورة واحدة أو صورتان مصفوفة عادية:

```json theme={null}
{
  "action": "generate",
  "model": "flux-3",
  "mode": "i2v",
  "prompt": "The camera slowly moves around the product in soft studio light.",
  "keyframes": ["https://example.com/first-frame.jpg"],
  "duration": 5,
  "resolution": "hd",
  "generate_audio": false,
  "async": true
}
```

عند تحديد لحظات الإطارات الرئيسية، استخدم أزواج `[عدد الثواني، عنوان URL للصورة]`:

```json theme={null}
{
  "action": "generate",
  "model": "flux-3",
  "mode": "i2v",
  "prompt": "A smooth transition from morning light to a warm sunset.",
  "keyframes": [[0, "https://example.com/start.jpg"], [5, "https://example.com/end.jpg"]],
  "duration": 5,
  "resolution": "hd",
  "async": true
}
```

يُسمح بـ 1–10 إطارات رئيسية. يجب أن تكون المصفوفة ذات التوقيت مرتبة تصاعديًا حسب الوقت، وأن يكون الوقت من 0–20 ثانية، ولا يجوز خلط عناوين URL العادية مع العناصر ذات التوقيت. يجب تحديد duration بوضوح لثلاثة إطارات رئيسية عادية أو أكثر، ولا يمكن استخدام auto.

### ناتج الاختبار الفعلي لتحويل الصور إلى فيديو

فيما يلي الإدخال المطابق لهذا الاختبار الفعلي (تُستبدل فقط سلسلة base64 الكاملة بنص توضيحي، أما الحقول الأخرى فهي طلب حقيقي):

```json theme={null}
{
  "async": true,
  "action": "generate",
  "model": "flux-3",
  "prompt": "The toy sailboat drifts slowly across calm water. A steady camera, gentle daylight, no people or text.",
  "duration": 5,
  "resolution": "hd",
  "generate_audio": false,
  "draft": false,
  "mode": "i2v",
  "keyframes": [
    "<سلسلة base64 الأصلية لملف PNG في الصورة أدناه>"
  ]
}
```

![الإطار الرئيسي المرجعي لتحويل الصور إلى فيديو في هذا الاختبار](https://cdn.acedata.cloud/assets/examples/flux/b1106de8-d586-4e23-b489-381e2f86a10f-input-b0525db595d2.png)

بعد [تنزيل إطار PNG الرئيسي هذا](https://cdn.acedata.cloud/assets/examples/flux/b1106de8-d586-4e23-b489-381e2f86a10f-input-b0525db595d2.png)، يمكن استخدام `base64.b64encode(image_bytes).decode("ascii")` في Python للحصول على السلسلة الأصلية ووضعها في مصفوفة keyframes. لا تستخدم النص التوضيحي في الوثيقة كإدخال للصورة.

فيما يلي response النهائي الحقيقي لمهمة إنتاج بتاريخ 2026-10-01 (وليس استجابة محاكاة)؛ تم فقط استبدال عنوان URL للفيديو بنسخة مثال طويلة الأجل لها نفس التجزئة. استخدم الإدخال الفعلي للاختبار سلسلة base64 الأصلية لصورة PNG بدقة 1280×720 كإطار رئيسي واحد؛ وإدخال URL أعلاه هو مثال مستقل للمعلمات.

```json theme={null}
{
  "success": true,
  "task_id": "b1106de8-d586-4e23-b489-381e2f86a10f",
  "trace_id": "f62d5c56-cfb2-4f8f-b339-ef019d4c0d10",
  "data": [
    {
      "id": "b1106de8-d586-4e23-b489-381e2f86a10f",
      "model": "flux-3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/flux/b1106de8-d586-4e23-b489-381e2f86a10f-bef14458cc9d.mp4",
      "seconds": 5.041667,
      "width": 1280,
      "height": 704,
      "fps": 24
    }
  ],
  "usage": {
    "action": "generate",
    "seconds": 5.041667,
    "output_mp_seconds": 4.3326825781250005,
    "mode": "i2v",
    "resolution": "hd",
    "draft": false
  },
  "cost": {
    "amount": 7.617328628625,
    "currency": "credit",
    "list_amount": 8.46369847625
  }
}
```

[عرض الفيديو المُختبَر فعليًا](https://cdn.acedata.cloud/assets/examples/flux/b1106de8-d586-4e23-b489-381e2f86a10f-bef14458cc9d.mp4)。

## 5. متابعة الفيديو

يمرّر `start_video` عنوان ملف فيديو موجود، و`mode=v2v`، والمدة بحد أقصى 15 ثانية.

```json theme={null}
{
  "action": "generate",
  "model": "flux-3",
  "mode": "v2v",
  "prompt": "Continue the sailboat drifting forward with the same steady camera.",
  "start_video": "https://example.com/source.mp4",
  "duration": 5,
  "resolution": "hd",
  "async": true
}
```

### مخرجات اختبار متابعة الفيديو الفعلية

إدخال الاختبار الفعلي الكامل هذه المرة كما يلي؛ عند إعادة إنتاج تحسين المسودة يجب استبداله بمعرّف المسودة الخاص بك. يستخدم رابط المادة نسخة مثال طويلة الأجل من الملف نفسه:

```json theme={null}
{
  "action": "generate",
  "model": "flux-3",
  "mode": "v2v",
  "start_video": "https://cdn.acedata.cloud/assets/examples/flux/b41293be-94c0-4dc7-9f39-ce04f0a8798d-c055a3079059.mp4",
  "prompt": "Continue the same sailboat drifting gently across calm water in the same continuous steady shot.",
  "duration": 5,
  "resolution": "hd",
  "generate_audio": false,
  "async": true
}
```

فيما يلي الاستجابة النهائية الحقيقية لمهمة الإنتاج بتاريخ 2026-10-01 (وليست استجابة محاكاة)؛ تم استبدال رابط الفيديو فقط بنسخة مثال طويلة الأجل لها التجزئة نفسها.

```json theme={null}
{
  "success": true,
  "task_id": "8af9aa42-7e4d-47a4-bd61-144d97440c91",
  "trace_id": "4fb49afc-abca-4039-bbaa-adb66e293544",
  "data": [
    {
      "id": "8af9aa42-7e4d-47a4-bd61-144d97440c91",
      "model": "flux-3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/flux/8af9aa42-7e4d-47a4-bd61-144d97440c91-a512d6574811.mp4",
      "seconds": 5,
      "width": 1280,
      "height": 704,
      "fps": 24
    }
  ],
  "usage": {
    "action": "generate",
    "seconds": 5,
    "output_mp_seconds": 4.296875,
    "mode": "v2v",
    "resolution": "hd",
    "draft": false
  },
  "cost": {
    "amount": 18.219375,
    "currency": "credit",
    "list_amount": 20.24375
  }
}
```

[عرض الفيديو المُختبَر فعليًا](https://cdn.acedata.cloud/assets/examples/flux/8af9aa42-7e4d-47a4-bd61-144d97440c91-a512d6574811.mp4)。

كان `start_video` في إدخال الاختبار الفعلي هو [فيديو مسودة مكتمل](https://cdn.acedata.cloud/assets/examples/flux/b41293be-94c0-4dc7-9f39-ce04f0a8798d-c055a3079059.mp4)، وكانت المعلمات الأخرى duration=5 وresolution=hd وgenerate\_audio=false.

## 6. المسودة أولًا، ثم التحسين

1. استخدم `draft=true` و`resolution=hd` لإنشاء مسودة وانتظر النجاح.
2. استخرج معرّف مسودة المنصة من `data[0].draft_task_id` النهائي.
3. قدّم طلب التحسين باستخدام بيانات اعتماد التطبيق ذات الانتماء نفسه:

```json theme={null}
{
  "action": "generate",
  "model": "flux-3",
  "mode": "draft_enhance",
  "draft_task_id": "استبدله بمعرّف المسودة المكتملة الخاص بك",
  "resolution": "fhd",
  "async": true
}
```

لا يمكن لتحسين المسودة تمرير `prompt` أو `duration` أو `aspect_ratio` أو `version` أو `generate_audio` أو `draft` أو `keyframes` أو `start_video` للكتابة فوق المحتوى الأصلي. ذاكرة التخزين المؤقت للمسودة مورد مؤقت، يرجى تحسينها في الوقت المناسب؛ لا يوجد التزام بالحفظ الدائم أو بعدد أيام احتفاظ ثابت. لا يمكن إعادة استخدام مسودات غيرك/غير التطبيق الحالي، والمسودات غير المكتملة، وذاكرة التخزين المؤقت المنتهية الصلاحية. المسودة والتحسين مهمتان منفصلتان، ويتم احتساب الرسوم لكل منهما بشكل منفصل بعد النجاح.

### مخرجات اختبار تحسين المسودة الفعلية

إدخال الاختبار الفعلي الكامل هذه المرة كما يلي؛ عند إعادة إنتاج تحسين المسودة يجب استبداله بمعرّف المسودة الخاص بك. يستخدم رابط المادة نسخة مثال طويلة الأجل من الملف نفسه:

```json theme={null}
{
  "action": "generate",
  "model": "flux-3",
  "mode": "draft_enhance",
  "draft_task_id": "b41293be-94c0-4dc7-9f39-ce04f0a8798d",
  "resolution": "hd",
  "async": true
}
```

فيما يلي الاستجابة النهائية الحقيقية لمهمة الإنتاج بتاريخ 2026-10-01 (وليست استجابة محاكاة)؛ تم استبدال رابط الفيديو فقط بنسخة مثال طويلة الأجل لها التجزئة نفسها.

```json theme={null}
{
  "success": true,
  "task_id": "1db6243b-4a05-4484-828c-25bb17de7108",
  "trace_id": "64f93fa1-8d18-4c8b-a6d2-888009eb7cfa",
  "data": [
    {
      "id": "1db6243b-4a05-4484-828c-25bb17de7108",
      "model": "flux-3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/flux/1db6243b-4a05-4484-828c-25bb17de7108-058d92166607.mp4",
      "seconds": 5.041667,
      "width": 1280,
      "height": 704,
      "fps": 24
    }
  ],
  "usage": {
    "action": "generate",
    "seconds": 5.041667,
    "output_mp_seconds": 4.3326825781250005,
    "mode": "t2v",
    "resolution": "hd",
    "draft": false
  },
  "cost": {
    "amount": 7.617328628625,
    "currency": "credit",
    "list_amount": 8.46369847625
  }
}
```

[عرض الفيديو المُختبَر فعليًا](https://cdn.acedata.cloud/assets/examples/flux/1db6243b-4a05-4484-828c-25bb17de7108-058d92166607.mp4)。

كان إدخال الاختبار الفعلي هو draft\_task\_id=b41293be-94c0-4dc7-9f39-ce04f0a8798d وresolution=hd الخاصين بك؛ ويشير usage.mode=t2v النهائي إلى وضع المسودة الأصلي. تُحتسب رسوم هذه المهمة ورسوم المسودة الأصلية بشكل منفصل.

## 7. استدعاء Python من البداية إلى النهاية

ثبّت `requests`، واضبط Token الخاص بك، ثم شغّل البرنامج النصي أدناه لإكمال «إرسال مرة واحدة → الاستعلام الدوري → إخراج رابط الفيديو». يجب أن يستخدم كل من الاستعلام وإعادة محاولة الشبكة task\_id الأصلي، لتجنب إرسال مهام مدفوعة مكررة.

```python theme={null}
import os
import time
import requests

base_url = "https://api.acedata.cloud"
headers = {
    "Authorization": "Bearer " + os.environ["ACEDATACLOUD_API_TOKEN"],
    "Accept": "application/json",
}
payload = {
    "action": "generate",
    "model": "flux-3",
    "mode": "t2v",
    "prompt": "A small toy sailboat floating on calm blue water in warm morning light.",
    "duration": 5,
    "resolution": "hd",
    "draft": True,
    "async": True,
}
submitted = requests.post(base_url + "/flux/videos", json=payload, headers=headers, timeout=120)
submitted.raise_for_status()
accepted = submitted.json()
if accepted.get("error"):
    raise RuntimeError(accepted["error"])
task_id = accepted["task_id"]
print("Task ID:", task_id)  # 持久化保存，用于恢复轮询

# 30 分钟是本示例的客户端等待上限，不是服务的完成时限承诺。
deadline = time.monotonic() + 30 * 60
while time.monotonic() < deadline:
    polled = requests.post(
        base_url + "/flux/tasks",
        json={"action": "retrieve", "id": task_id},
        headers=headers,
        timeout=30,
    )
    polled.raise_for_status()
    task = polled.json()
    if task.get("error"):
        raise RuntimeError(task["error"])
    result = task.get("response") or task.get("result")
    if isinstance(result, dict) and result.get("success") is True:
        print("Video:", result["data"][0]["video_url"])
        print("Usage:", result.get("usage"))
        print("Cost:", result.get("cost"))
        break
    if isinstance(result, dict) and result.get("error"):
        raise RuntimeError(result["error"])
    time.sleep(10)
else:
    raise TimeoutError("Still processing; resume polling with task_id=" + task_id)
```

بعد انتهاء مهلة الشبكة، لا تعتبر الحالة غير المعروفة فشلاً ثم تعيد الإرسال فوراً. إذا تم الحصول على `task_id`، فاستمر في الاستعلام عن هذه المهمة؛ وسجّل `task_id` و`trace_id` لتسهيل التحقيق. لا تفرض واجهة الاستعلام الدوري نفسها رسوماً على التوليد.

## 8. استخدام رد الاتصال

أضف `callback_url` عند الإرسال، وبعد اكتمال المهمة سيتم إرسال نتيجة JSON النهائية عبر POST إلى هذا العنوان. تكون بنية النجاح متسقة مع response المذكور سابقاً، بينما يتضمن الفشل error.

```json theme={null}
{
  "action": "generate",
  "model": "flux-3",
  "mode": "t2v",
  "prompt": "A small sailboat on calm water.",
  "duration": 5,
  "resolution": "hd",
  "draft": true,
  "callback_url": "https://your-server.example/flux-callback"
}
```

يجب أن يكون عنوان رد الاتصال قابلاً للوصول من الإنترنت العام. بعد تلقي الإشعار، عالجه بصورة متكررة بشكل آمن وفقاً لـ task\_id، وأعد 2xx في أسرع وقت ممكن؛ ويمكن وضع معالجة الأعمال في قائمة انتظار. لا يصرّح هذا النص بأن رد الاتصال يمتلك مصادقة بالتوقيع: قبل تنفيذ عمليات حساسة مثل منح مزايا الأعمال، استخدم Token الخاص بك للاستعلام عن المهمة نفسها للتحقق من النتيجة. يمكن أيضاً متابعة الاستعلام الدوري عند عدم تلقي رد الاتصال، ولا تعِد التوليد.

## 9. الفوترة الحالية وجدول الأسعار

تحديث 2026-10-02: تم تخفيض سعر الوحدة لكل فئة في واجهة الفيديو هذه بنحو 6.33%، بينما تظل طريقة القياس والباقات وقواعد خصومات الاستهلاك دون تغيير. إن cost في response للاختبارات التاريخية الفعلية السابقة هو فاتورة وقت اكتمال المهمة، ولا يمثل العرض الحالي.

يتم احتساب رسوم توليد الفيديو وفقاً لـ **عدد ثواني الإخراج الفعلية**. فيما يلي أسعار الوحدة الحالية بـ Credits قبل تطبيق خصومات استهلاك الحساب، وهي متسقة مع قواعد [صفحة أسعار Flux](https://platform.acedata.cloud/services/flux?tab=pricing).

| العملية/الوضع | الدقة | سعر الوحدة بـ Credits |
| - | - | -: |
| مسودة t2v / i2v | hd | 0.555 / ثانية |
| مسودة v2v | hd | 1.11 / ثانية |
| t2v / i2v / تحسين المسودة المقابلة | hd | 1.5725 / ثانية |
| كما سبق | fhd | 2.6825 / ثانية |
| كما سبق | qhd | 3.7 / ثانية |
| كما سبق | uhd | 7.4 / ثانية |
| v2v / تحسين المسودة المقابلة | hd | 3.7925 / ثانية |
| كما سبق | fhd | 4.9025 / ثانية |
| كما سبق | qhd | 6.0125 / ثانية |
| كما سبق | uhd | 8.7875 / ثانية |

التحويل إلى الدولار الأمريكي: `التكلفة الفعلية (USD) = cost.amount (Credits) × price الباقة / amount الباقة`. تؤثر مستويات إعادة الشحن وخصومات الاستهلاك في السعر الفعلي، ولا يمكن اعتبار Credits دولاراً أمريكياً مباشرةً. لا تُفرض رسوم توليد على المهام الفاشلة؛ ويُعتد بالمبلغ النهائي وفقاً لنتيجة الاكتمال وسجل الاستدعاءات في لوحة التحكم.

## 10. الأسئلة الشائعة واستكشاف الأخطاء وإصلاحها

| الحالة | الاقتراح |
| - | - |
| خطأ في المعلمات (400) | تحقق من action=generate وmode وduration وتنسيق الإطارات الرئيسية؛ ولا تخلط الحقول الخاصة بأوضاع التوليد المختلفة |
| خطأ في المصادقة (401) | تحقق من Bearer Token وصلاحيات التطبيق وما إذا كانت بيانات الاعتماد صالحة |
| رفض مراجعة المحتوى (403) | عدّل المواد والموجهات، ولا ترسلها مراراً بالنص نفسه |
| تحديد المعدل (429) | خفّض التزامن، وأعد المحاولة بتراجع تدريجي |
| service\_unavailable (503) | العملية الحالية غير متاحة؛ وقد تُبلغ المهام غير المتزامنة المقبولة عن هذا الخطأ في response النهائي |
| تم إرجاع task\_id ولكن لا يوجد فيديو بعد | تابع الاستعلام عن response، ولا تعتبر HTTP 200 اكتمالاً للتوليد |
| لا يمكن إعادة استخدام المسودة | تأكد من المستخدم/التطبيق الحالي، ومن اكتمال المهمة، ومن أن الطلب الأصلي كان draft=true، وتحقق مما إذا كانت الذاكرة المؤقتة لا تزال صالحة |

عند تقديم ملاحظات، وفّر task\_id وtrace\_id ووقت الطلب والمعلمات بعد إخفاء البيانات الحساسة، ولا ترسل API Token. لمزيد من الطرق، راجع [دليل تكامل Flux MCP](https://platform.acedata.cloud/documents/flux-mcp).


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