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

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

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

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

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

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

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

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

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

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

الموضوع	المرجع
إنشاء ثلاثي الأبعاد	إنشاء ثلاثي الأبعاد
الحصول على حالة ثلاثي الأبعاد	الحصول على حالة ثلاثي الأبعاد
الحصول على حالة المهمة	الحصول على حالة المهمة
قائمة النماذج	قائمة النماذج
الفوترة والتسعير	الفوترة والتسعير

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

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

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

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

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

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

​مرجع API