أدلة الوسائط

توليد ثلاثي الأبعاد (3D generation)

إنشاء نماذج ثلاثية الأبعاد قابلة للتنزيل من نصوص أو صور

توليد ثلاثي الأبعاد (3D generation) هو عملية غير متزامنة. يقوم POST /v1/3d/generations بإنشاء مهمة TokenLab؛ وتُرجع استجابات الحالة المكتملة أصول نماذج قابلة للتنزيل مثل model_url وعند توفرها، روابط (URLs) خاصة بتنسيقات معينة.

يتم الاحتفاظ بملفات النماذج ثلاثية الأبعاد القابلة للتنزيل كنسخ تلقائية لمدة 30 يوماً، وتعتبر روابطها (URLs) روابط وسائط خاصة بـ TokenLab. تتبع سجلات المهام والأصول المحفوظة بشكل منفصل دورة حياتها الخاصة. راجع الاحتفاظ بالبيانات.

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

الإدخالمطلوبحقول اختياريةملاحظات
Text-to-3Dmodel, promptformat, quality, style, seedالأفضل لإنشاء أصل جديد من وصف
Image-to-3Dmodel, image_url أو image؛ وأيضاً prompt عندما يدرجه النموذجformat, quality, style, seedيُستخدم فقط عندما يدعم النموذج المحدد إدخال الصور

operation هو حقل اختياري ويكون إما text-to-3d أو image-to-3d. إذا تركته فارغاً، يستخدم TokenLab image-to-3d عند إرسال image أو image_url، و text-to-3d في الحالات الأخرى. إذا قمت بإرساله، فيجب أن يتطابق مع المدخلات. النموذج الذي يدعم text-to-3d يقبل النصوص (prompts)؛ والنموذج الذي يدعم image-to-3d يقبل إدخال الصور.

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": "tripo-h3.1",
    "prompt": "A stylized low-poly robot mascot with clean topology"
  }'

بالنسبة لـ image-to-3D، استخدم رابط https عندما يمكن جلب المصدر من الإنترنت. استخدم image بصيغة base64 المضمنة فقط مع نموذج تدرج تفاصيله image؛ بعض النماذج تقبل image_url فقط.

تنسيقات الإخراج

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

الحصول على النموذج النهائي

قم باستدعاء GET /v1/tasks/{id} باستخدام id أو task_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 والنموذج والتنسيق المطلوب ومعرف سجل الأصل الخاص بك.
  • استأنف الاستطلاع (polling) بعد تحديث الصفحة بدلاً من إنشاء مهمة مكررة.
  • تحقق من حجم صورة المصدر وإمكانية الوصول إليها قبل إنشاء المهمة.
  • احتفظ بروابط الأصول التي تم إنشاؤها بعيداً عن الصفحات العامة ما لم يكن لدى المستخدم إذن بالوصول إلى الأصل.
  • سجل billing_transaction_id عند وجوده للمطابقة لاحقاً.

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

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

مرجع API

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

في هذه الصفحة