أدلة الوسائط
توليد ثلاثي الأبعاد (3D generation)
إنشاء نماذج ثلاثية الأبعاد قابلة للتنزيل من نصوص أو صور
توليد ثلاثي الأبعاد (3D generation) هو عملية غير متزامنة. يقوم POST /v1/3d/generations بإنشاء مهمة TokenLab؛ وتُرجع استجابات الحالة المكتملة أصول نماذج قابلة للتنزيل مثل model_url وعند توفرها، روابط (URLs) خاصة بتنسيقات معينة.
يتم الاحتفاظ بملفات النماذج ثلاثية الأبعاد القابلة للتنزيل كنسخ تلقائية لمدة 30 يوماً، وتعتبر روابطها (URLs) روابط وسائط خاصة بـ TokenLab. تتبع سجلات المهام والأصول المحفوظة بشكل منفصل دورة حياتها الخاصة. راجع الاحتفاظ بالبيانات.
اختيار نوع الإدخال
| الإدخال | مطلوب | حقول اختيارية | ملاحظات |
|---|---|---|---|
| Text-to-3D | model, prompt | format, quality, style, seed | الأفضل لإنشاء أصل جديد من وصف |
| Image-to-3D | model, 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
| الموضوع | المرجع |
|---|---|
| إنشاء ثلاثي الأبعاد | إنشاء ثلاثي الأبعاد |
| الحصول على حالة ثلاثي الأبعاد | الحصول على حالة ثلاثي الأبعاد |
| الحصول على حالة المهمة | الحصول على حالة المهمة |
| قائمة النماذج | قائمة النماذج |
| الفوترة والأسعار | الفوترة والأسعار |