Worlds
إنشاء عالم
ينشئ مهمة توليد عالم World Labs Marble
قم بتوليد عوالم ثلاثية الأبعاد قابلة للاستكشاف باستخدام World Labs Marble. هذه واجهة API غير متزامنة: تُرجع استجابات الإنشاء معرّف المهمة. قم بالاستعلام الدوري لـ GET /v1/tasks/{id} باستخدام id الخاص بالمهمة لمعرفة الحالة.
اختر نموذج Marble متاحاً حالياً باستخدام Models API.
نص الطلب
marble-1.0اختر نموذج Marble متاحاً حالياً باستخدام Models API.
الموجه النصي للتوليد المعتمد على النص فقط، أو التوجيه لمدخلات الصور والفيديو. حتى 4000 حرف. أرسل واحداً على الأقل من world_prompt، أو prompt، أو image، أو image_url، أو images، أو video_url.
كائن world_prompt الأصلي لـ World Labs للمستخدمين المتقدمين. أنواع الموجهات المدعومة هي text وimage وmulti-image وvideo. يمكن لمرجع المحتوى أن يشير إلى ملف قمت برفعه باستخدام تجهيز رفع أصول الوسائط: { "source": "media_asset", "media_asset_id": "..." }.
موجه صورة بصيغة Base64 أو data URL.
موجه رابط صورة (Image URL).
موجهات صور متعددة للتوليد السريع متعدد الصور. قدّم ما يصل إلى 4 صور، كل منها إما رابط URL، أو سلسلة Base64 أو data URL، أو كائن يحتوي على uri أو image_url أو url مع رقم azimuth اختياري. بالنسبة لوضع إعادة البناء الأصلي لـ World Labs، مرر world_prompt.type="multi-image" مع reconstruct_images: true وما يصل إلى 8 صور.
موجه رابط فيديو (Video URL).
بالنسبة لمدخلات الصور، حدد true لصورة بانورامية موجودة، أو false لصورة مفردة عادية، أو auto.
قيمة seed اختيارية من 0 حتى 4294967295.
اسم عرض اختياري للعالم المُنشأ، حتى 64 حرفاً.
وسوم World Labs اختيارية. قدّم ما يصل إلى 10 وسوم، كل منها حتى 32 حرفاً.
إعدادات الرؤية والوصول الاختيارية: public وallow_id_access وallowed_readers وallowed_writers. يطلب الخيار public: true عالماً مرئياً للعامة.
الاستجابة
معرّف المهمة العام. قم بالاستعلام الدوري لـ GET /v1/tasks/{id} باستخدامه.
اسم بديل لمعرّف المهمة غير المتزامنة.
معرّف عملية World Labs.
رابط URL لحالة العالم تحت /v1/worlds/generations/{id}. هذه نقطة نهاية للتوافق. قم بالاستعلام الدوري لـ GET /v1/tasks/{id} باستخدام id بدلاً من ذلك.
حالة المهمة: pending، أو processing، أو completed، أو failed.
رابط URL لعالم Marble المُنشأ عند اكتماله.
رابط GLB لشبكة التصادم (Collider mesh) عند توفره.
رابط صورة البانوراما عند توفرها.
التسعير
راجع Pricing API لمعرفة الأسعار الحالية. يظهر المبلغ النهائي المفوتر في سجلات الاستخدام الخاصة بك.
الأخطاء
400 invalid_request: لم يتم إرسال أي مدخل موجه، أو أن أحد الحقول خارج النطاق. يحددparamاسم الحقل.400 model_not_foundأوunsupported_endpoint: النموذج ليس نموذج Marble صالحاً للاستدعاء.403 media_asset_not_ownedأو404 media_asset_not_found: قيمةmedia_asset_idفيworld_promptتنتمي إلى Workspace آخر أو غير موجودة.402: الرصيد منخفض جداً لبدء المهمة.
الطلب
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": "string", "task_id": "string", "operation_id": "string", "status": "pending", "poll_url": "string", "world_id": "string", "world_marble_url": "string", "model_url": "string", "glb_url": "string", "pano_url": "string", "thumbnail_url": "string", "caption": "string", "error": "string", "error_details": { "projection_version": 0, "status": 400, "message": "string", "type": "string", "code": "string", "param": "string", "retryable": true, "upstream": { "source": "string", "code": "string", "message": "string", "param": "string" } }}التفويض
BearerAuth مصادقة مفتاح API. قم بإنشاء أو إدارة مفاتيح API في Dashboard > API > API Keys.
الموضع: header
الترويسات
سياسة التسليم لكل طلب. تتجاوز إعدادات API key و Workspace الافتراضية. يحاول النظام تلقائياً استخدام TokenLab Verified أولاً، وقد ينتقل مرة واحدة إلى Official فقط قبل المخرجات، أو قبول الطلب، أو إنشاء مورد دائم.
القيم المتاحة
- "auto"
- "verified"
- "official"
مفتاح اختياري يجعل طلب الإنشاء آمناً لإعادة المحاولة. أرسل قيمة فريدة جديدة، مثل UUID، لكل مهمة. إعادة المحاولة بنفس المفتاح ونفس نص الطلب تُرجع نتيجة طلب الإنشاء الأصلي، وعادةً ما تكون المهمة الأصلية، ولا تقوم بإنشاء أو إرسال أو احتساب تكلفة مهمة ثانية. يتم رفض نص الطلب المختلف الذي يستخدم مفتاحاً تم قبوله مسبقاً بالرمز 409. يتم تجاهل المفتاح الذي يتجاوز 255 حرفاً، وعندها لا يتمتع الطلب بحماية idempotency. راجع إعادة المحاولة بأمان باستخدام مفتاح idempotency.
1 <= length <= 255جسم الطلب
application/json
الاستجابة
application/json
application/json
application/json
application/json
application/json