أدلة الوسائط

Worlds

إنشاء عوالم Marble قابلة للاستكشاف من النصوص أو الصور أو الفيديو

تُنشئ خدمة Worlds بيئة Marble يمكن للأشخاص فتحها واستكشافها. إذا كنت بحاجة إلى كائن قابل للتنزيل بدلاً من بيئة، فاستخدم 3D generation.

يتم الاحتفاظ بملفات World القابلة للتنزيل، مثل splats وmeshes وصور البانوراما، كنسخ تلقائية لمدة 30 يوماً مع روابط وسائط TokenLab. أما صفحة World التفاعلية وسجلات World فلا يتم الاحتفاظ بها. راجع الاحتفاظ بالبيانات.

المدخلات وأصول الوسائط

يمكن أن يبدأ العالم من نص، أو صورة واحدة أو أكثر، أو فيديو، اعتماداً على النموذج. ابحث عن نماذج Marble (marble-*) في GET /v1/models?recommended_for=3d؛ وعمليتها هي world-generation. أرسل مدخلاً واحداً على الأقل:

المدخلالحقل
نصprompt، بحد أقصى 4,000 حرف
صورة واحدةimage_url، أو image بصيغة Base64 أو رابط بيانات؛ يحدد is_pano ما إذا كانت الصورة بانورامية بالفعل
عدة صورimages، بحد أقصى 4 صور
فيديوvideo_url
متقدمworld_prompt، كائن نصي أصلي يمكنه الإشارة إلى أصل وسائط مرفوع

الحقول الاختيارية هي display_name (بحد أقصى 64 حرفاً)، وseed، وtags (بحد أقصى 10)، وpermission. يمكن رفع الوسائط القابلة لإعادة الاستخدام مرة واحدة والإشارة إليها بواسطة معرف الأصل (asset ID) الخاص بها.

يتم التحقق من الوصول إلى الوسائط وسجلات World مقابل المؤسسة التي تمتلك مفتاح API. راجع خيارات permission الخاصة بالنموذج المختار قبل مشاركة العالم؛ فقد يكون للأصل المرتجع أو رابط العارض قواعد وصول خاصة به.

الإنشاء والاستطلاع (Create And Poll)

يحتوي رد الإنشاء على معرف مهمة (task ID) وعادةً ما يحتوي على poll_url. احتفظ بالمعرف، ثم قم باستدعاء GET /v1/tasks/{id} باستخدامه حتى تصبح الحالة completed أو failed. يشير poll_url الخاص بـ Worlds إلى /v1/worlds/generations/{id}، وهو مسار توافقي. استخدم /v1/tasks/{id} بدلاً منه.

curl -X POST "https://api.tokenlab.sh/v1/worlds/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "marble-1.1",
    "prompt": "A quiet coastal town at sunset with narrow alleys and warm lights"
  }'

استطلع حالة المهمة باستخدام id من رد الإنشاء:

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"

إدارة العوالم المكتملة

استخدم POST /v1/worlds/list و GET /v1/worlds/{id} للعوالم المكتملة المتاحة في حسابك، و DELETE /v1/worlds/{id} لإزالة أحدها. استخدم GET /v1/tasks/{id} لمهام الإنشاء المعلقة أو الفاشلة. لا تقم بالحذف إلا عندما يقوم المستخدم بإزالة العالم الذي تم إنشاؤه من منتجك بشكل متعمد.

المخاطر الشائعة

  • لا تفترض أن كل نموذج عالم يدعم كل نوع من أنواع المدخلات.
  • حافظ على صلاحية روابط الصور أو الفيديو الموقعة لفترة كافية لإعادة محاولات جلب الخدمة.
  • قم بتخزين معرف المهمة المرتجع قبل إعادة المحاولة بعد انتهاء المهلة.
  • استخدم 3D generation لملفات النماذج القابلة للتنزيل بدلاً من العوالم القابلة للاستكشاف.

مرجع API

الموضوعالمرجع
إنشاء عالمإنشاء عالم
الحصول على حالة المهمةالحصول على حالة المهمة
الحصول على حالة العالم (توافقية)الحصول على حالة العالم
تحضير رفع أصل الوسائطإعداد رفع أصل الوسائط
الحصول على أصل الوسائطالحصول على أصل الوسائط
سرد العوالمعرض قائمة العوالم
الحصول على عالمالحصول على World
حذف عالمحذف العالم
الوظائف غير المتزامنةAsync Jobs
دليل إنشاء ثلاثي الأبعاد3D Generation Guide

في هذه الصفحة