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

# توليد ثلاثي الأبعاد

> إنشاء مهام من نص إلى ثلاثي الأبعاد أو من صورة إلى ثلاثي الأبعاد، الاستعلام عن الأصول المكتملة، والتعامل مع ملفات النماذج القابلة للتنزيل.

توليد ثلاثي الأبعاد غير متزامن. `POST /v1/3d/generations` ينشئ مهمة TokenLab؛ ردود الحالة المكتملة تعيد أصول النماذج القابلة للتنزيل مثل `model_url` وعند توفرها، روابط محددة للصيغة.

## اختر نوع الإدخال

| سير العمل              | الإدخال المطلوب                           | الحقول الاختيارية                    | ملاحظات                                           |
| ---------------------- | ----------------------------------------- | ------------------------------------ | ------------------------------------------------- |
| نص إلى ثلاثي الأبعاد   | `model`, `prompt`                         | `format`, `quality`, `style`, `seed` | الأفضل لإنشاء أصل جديد من وصف                     |
| صورة إلى ثلاثي الأبعاد | `model`, `prompt`, `image` أو `image_url` | `format`, `quality`, `style`, `seed` | استخدم فقط عندما يدعم النموذج المحدد إدخال الصورة |

استعلم عن كتالوج النماذج قبل اتخاذ قرار بشأن الخيارات التي يجب عرضها:

```bash theme={null}
curl "https://api.tokenlab.sh/v1/models?recommended_for=3d" \
  -H "Authorization: Bearer sk-your-api-key"
```

لا تفترض أن كل نموذج ثلاثي الأبعاد يدعم كلا نوعي الإدخال أو كل صيغة إخراج. تحقق من عقد النموذج المحدد قبل إرسال `image`, `image_url`, `format`, `quality`, `style`, أو `seed`.

## إنشاء مهمة ثلاثية الأبعاد

```bash theme={null}
curl https://api.tokenlab.sh/v1/3d/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tripo3d-v2.5",
    "prompt": "تميمة روبوت منخفضة البولي مع طوبولوجيا نظيفة",
    "format": "glb",
    "quality": "standard"
  }'
```

بالنسبة للصورة إلى ثلاثي الأبعاد، استخدم `image_url` العامة عند الإمكان. استخدم `image` بتنسيق inline/base64 فقط عندما يرسل عميلك وسائط خاصة عمدًا ويكون خادمك مستعدًا لأحجام طلبات أكبر.

## خيارات صيغة الإخراج

* `glb` هو عادة الخيار الافتراضي الأكثر أمانًا لمعاينات الويب.
* `fbx` و `obj` مفيدان لخطوط أنابيب DCC عندما يدعم النموذج المحدد ذلك.
* `usdz` مفيد لعمليات Apple AR عندما يتم عرضه بواسطة النموذج.
* يمكن أن تزيد قيم `quality` الأعلى من زمن الاستجابة والتكلفة. اعرضها كخيارات واضحة للمستخدمين، وليس كخيارات مخفية.
* `seed` مفيد للتكرار فقط عندما يحترم النموذج ذلك.

## استعلام وتخزين الأصول

استخدم `poll_url` المعاد أولاً. إذا كان عميلك يحتاج إلى مسار ثابت، استخدم `GET /v1/tasks/{id}`.

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

تعود المهام المكتملة بـ `model_url` وقد تتضمن `glb_url`, `fbx_url`, `obj_url`, أو `usdz_url`. قم بتنزيل أو تخزين الأصل المحدد في منتجك الخاص إذا كان المستخدمون يحتاجون إلى الوصول المتكرر، تاريخ الإصدارات، أو التنزيلات طويلة الأمد.

## قائمة التحقق للإنتاج

* احتفظ بـ `task_id`, `poll_url`, النموذج، الصيغة المطلوبة، ومعرف سجل الأصل الخاص بك.
* استأنف الاستعلام بعد تحديث الصفحة بدلاً من إنشاء مهمة مكررة.
* تحقق من حجم الصورة المصدر وقابلية الوصول قبل إنشاء المهمة.
* احتفظ بروابط الأصول المولدة بعيدًا عن الصفحات العامة ما لم يكن لدى المستخدم إذن للوصول إلى الأصل.
* سجل `billing_transaction_id` عند وجوده للمصالحة لاحقًا.

## الأخطاء الشائعة

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

## مرجع API

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