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

# وظائف غير متزامنة واستطلاع

> إنشاء وظائف وسائط غير متزامنة، استطلاع حالة مهام TokenLab العامة، وتسوية النتائج النهائية دون معرفات محددة لمزود الخدمة.

العديد من نقاط النهاية للوسائط غير متزامنة. تبدأ طلبات الإنشاء العمل وتعيد هوية مهمة عامة من TokenLab؛ يقوم تطبيقك بالاستطلاع حتى تصل تلك المهمة إلى حالة نهائية. لا تبني سير عمل العملاء حول عناوين URL لمهام المصدر، أو معرفات التوجيه، أو سلوك ردود مزود الخدمة.

## عقد المهمة العامة

يمكن أن تتضمن استجابات الإنشاء:

| الحقل      | المعنى                                             | ماذا تفعل                           |
| ---------- | -------------------------------------------------- | ----------------------------------- |
| `id`       | معرف مهمة TokenLab العامة                          | خزنه مع سجل وظيفتك الخاص            |
| `task_id`  | اسم مستعار للتوافق لنفس هوية المهمة العامة         | اعتبره معادلاً لـ `id`              |
| `status`   | الحالة الحالية للمهمة العامة                       | ابدأ الاستطلاع عندما لا تكون نهائية |
| `poll_url` | عنوان URL المفضل للحالة                            | استخدم هذا أولاً عند وجوده          |
| `model`    | النموذج المطلوب أو الذي تم حله بواسطة نقطة النهاية | خزنه للدعم وتسوية الفواتير          |

`/v1/tasks/{id}` هو نقطة النهاية الثابتة القياسية لحالة وظائف الوسائط العامة غير المتزامنة. قد توجد مسارات حالة محددة للوسائط للتوافق، ولكن يجب أن تفضل التكاملات الجديدة `poll_url` أو `/v1/tasks/{id}`.

## التدفق الموصى به

1. تحقق من طلب المستخدم وأرسل مكالمة الإنشاء مع `model` صريح.
2. احتفظ بـ `id` / `task_id`، `poll_url`، نقطة النهاية، النموذج، معرف المستخدم، ومعرف وظيفتك الخاص قبل إعادة التحكم إلى واجهة المستخدم.
3. استطلع كل `5-10s` للمهام الطويلة الأمد.
4. توقف فقط عندما تكون المهمة `مكتملة` أو `فشلت`.
5. عند `الاكتمل`، اقرأ حقول النتائج الخاصة بالوسائط وخزن عناوين URL النهائية أو البيانات الوصفية.
6. عند `الفشل`، خزّن الخطأ العام وقدم إعادة المحاولة فقط كوظيفة جديدة مرئية للمستخدم.

```json theme={null}
{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "model": "veo3.1"
}
```

## مثال على الاستطلاع

```bash theme={null}
curl "https://api.tokenlab.sh/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
  -H "Authorization: Bearer sk-your-api-key"
```

الحالات العامة المتوقعة هي `pending`، `processing`، `completed`، و `failed`. يتم تمثيل المهام الملغاة كـ `failed` مع `cancelled: true` و `cancellation_status: "cancelled"` بحيث تستمر معالجة الحالة القديمة في العمل.

## قواعد إعادة المحاولة للعميل

تعتبر مهلات الشبكة المصدر الأكثر شيوعًا للوظائف المكررة. استخدم هذه القاعدة:

| أين تحدث المهلة                     | سلوك أكثر أمانًا                                                                |
| ----------------------------------- | ------------------------------------------------------------------------------- |
| قبل أن يستقبل خادمك استجابة الإنشاء | تحقق من سجلات الخادم لـ `request_id`؛ أعد المحاولة فقط إذا لم يتم إنشاء أي مهمة |
| بعد تخزين استجابة الإنشاء           | استأنف الاستطلاع لـ `task_id` المخزنة                                           |
| أثناء الاستطلاع                     | أعد المحاولة لطلب الحالة مع التراجع                                             |
| بعد الحالة النهائية                 | لا تستطلع مرة أخرى إلا إذا قام المستخدم بتحديث السجل بشكل صريح                  |

لا ترسل طلب إنشاء ثانٍ لمجرد أن المتصفح تم تحديثه أو فشل استطلاع الحالة.

## الفوترة والتسوية

يمكن أن تحتفظ الوظائف غير المتزامنة بمبلغ تقديري عندما يتم قبول طلب الإنشاء. تحدث التسوية النهائية بعد الحالة النهائية. عندما تكون متاحة، يمكن أن تكشف استجابات حالة المهمة عن `billing_transaction_id` ورأس `X-Billing-Transaction-ID`.

للتسوية، انضم إلى هذه المعرفات في سجلاتك:

* `request_id` من طلب الإنشاء.
* `task_id` / `id` من المهمة.
* `billing_transaction_id` عند وجوده.
* معرف المستخدم الخاص بك، معرف المشروع، أو معرف الوظيفة.

## الإلغاء

`DELETE /v1/tasks/{id}` ضيق عن عمد. يدعم حاليًا مهام فيديو Volcengine Seedance المعلقة مثل `seedance-1.5-pro`، `seedance-2.0`، و `seedance-2.0-fast`.

تعود المهام غير المدعومة بـ `400 unsupported_task_cancel`. المهام التي تعمل بالفعل أو النهائية تعود بـ `409 task_not_cancellable`. قم ببناء واجهة إلغاء كـ "طلب الإلغاء" بدلاً من زر توقف مضمون.

## استكشاف الأخطاء وإصلاحها

| العرض                                | السبب المحتمل                                                                                | ماذا تتحقق                                                                  |
| ------------------------------------ | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `async_task_not_found`               | المهمة غير معروفة، منتهية، غير قابلة للوصول إلى مفتاح API هذا، أو ليست مهمة غير متزامنة عامة | تأكد من ملكية مفتاح API و `task_id` العامة المخزنة                          |
| المهمة لا تظهر أبدًا على أنها مكتملة | يستمر العميل في استطلاع عنوان URL الخطأ أو توقف قبل الحالة النهائية                          | استخدم `poll_url` أو `/v1/tasks/{id}` وتفقد الحالة الأخيرة                  |
| عنوان URL النهائي للوسائط مفقود      | المهمة لم تكتمل، أو أكمل العمل العلوي بدون مخرجات قابلة للاستخدام                            | استمر في الاستطلاع حتى النهاية، ثم تعامل مع المخرجات المفقودة على أنها فشلت |
| المستخدم يرى مكررات                  | أنشأ مسار إعادة المحاولة مهمة جديدة بعد المهلة أو التحديث                                    | قم بإزالة التكرار بواسطة معرف وظيفتك الخاص و `task_id` المخزنة              |
| عدم تطابق الفوترة                    | التسوية غير متزامنة أو العميل يقارن معرفات المزود                                            | قارن `request_id`، `task_id`، و `billing_transaction_id`                    |

## حزمة الدعم

عند الاتصال بالدعم، قم بتضمين `request_id`، `task_id`، `billing_transaction_id` عند وجوده، نقطة النهاية، النموذج، الطابع الزمني، وشكل الطلب المنقح. لا تتضمن مفاتيح API، الوسائط الخاصة، عناوين URL الموقعة، أو المطالبات الكاملة ما لم يطلب الدعم عينة منقحة.

## مرجع API

| الموضوع                | المرجع                                                            |
| ---------------------- | ----------------------------------------------------------------- |
| الحصول على حالة المهمة | [الحصول على حالة المهمة](/ar/api-reference/tasks/get-task-status) |
| إلغاء المهمة           | [إلغاء المهمة](/ar/api-reference/tasks/cancel-task)               |
| إنشاء الصور            | [إنشاء الصور](/ar/guides/image-generation)                        |
| إنشاء الفيديو          | [إنشاء الفيديو](/ar/guides/video-generation)                      |
| إنشاء الموسيقى         | [إنشاء الموسيقى](/ar/guides/music-generation)                     |
| إنشاء ثلاثي الأبعاد    | [إنشاء ثلاثي الأبعاد](/ar/guides/3d-generation)                   |
| الفوترة والتسعير       | [الفوترة والتسعير](/ar/guides/billing)                            |