Worlds

إنشاء عالم

ينشئ مهمة توليد عالم World Labs Marble

POST
/v1/worlds/generations

قم بتوليد عوالم ثلاثية الأبعاد قابلة للاستكشاف باستخدام World Labs Marble. هذه واجهة API غير متزامنة: تُرجع استجابات الإنشاء معرّف المهمة. قم بالاستعلام الدوري لـ GET /v1/tasks/{id} باستخدام id الخاص بالمهمة لمعرفة الحالة.

اختر نموذج Marble متاحاً حالياً باستخدام Models API.

نص الطلب

modelstringالافتراضي: marble-1.0

اختر نموذج Marble متاحاً حالياً باستخدام Models API.

promptstring

الموجه النصي للتوليد المعتمد على النص فقط، أو التوجيه لمدخلات الصور والفيديو. حتى 4000 حرف. أرسل واحداً على الأقل من world_prompt، أو prompt، أو image، أو image_url، أو images، أو video_url.

world_promptobject

كائن world_prompt الأصلي لـ World Labs للمستخدمين المتقدمين. أنواع الموجهات المدعومة هي text وimage وmulti-image وvideo. يمكن لمرجع المحتوى أن يشير إلى ملف قمت برفعه باستخدام تجهيز رفع أصول الوسائط: { "source": "media_asset", "media_asset_id": "..." }.

imagestring

موجه صورة بصيغة Base64 أو data URL.

image_urlstring

موجه رابط صورة (Image URL).

imagesarray

موجهات صور متعددة للتوليد السريع متعدد الصور. قدّم ما يصل إلى 4 صور، كل منها إما رابط URL، أو سلسلة Base64 أو data URL، أو كائن يحتوي على uri أو image_url أو url مع رقم azimuth اختياري. بالنسبة لوضع إعادة البناء الأصلي لـ World Labs، مرر world_prompt.type="multi-image" مع reconstruct_images: true وما يصل إلى 8 صور.

video_urlstring

موجه رابط فيديو (Video URL).

is_panoboolean | string

بالنسبة لمدخلات الصور، حدد true لصورة بانورامية موجودة، أو false لصورة مفردة عادية، أو auto.

seedinteger

قيمة seed اختيارية من 0 حتى 4294967295.

display_namestring

اسم عرض اختياري للعالم المُنشأ، حتى 64 حرفاً.

tagsarray

وسوم World Labs اختيارية. قدّم ما يصل إلى 10 وسوم، كل منها حتى 32 حرفاً.

permissionobject

إعدادات الرؤية والوصول الاختيارية: public وallow_id_access وallowed_readers وallowed_writers. يطلب الخيار public: true عالماً مرئياً للعامة.

الاستجابة

idstring

معرّف المهمة العام. قم بالاستعلام الدوري لـ GET /v1/tasks/{id} باستخدامه.

task_idstring

اسم بديل لمعرّف المهمة غير المتزامنة.

operation_idstring

معرّف عملية World Labs.

poll_urlstring

رابط URL لحالة العالم تحت /v1/worlds/generations/{id}. هذه نقطة نهاية للتوافق. قم بالاستعلام الدوري لـ GET /v1/tasks/{id} باستخدام id بدلاً من ذلك.

statusstring

حالة المهمة: pending، أو processing، أو completed، أو failed.

world_marble_urlstring

رابط URL لعالم Marble المُنشأ عند اكتماله.

glb_urlstring

رابط GLB لشبكة التصادم (Collider mesh) عند توفره.

pano_urlstring

رابط صورة البانوراما عند توفرها.

التسعير

راجع 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
AuthorizationBearer <token>

مصادقة مفتاح API. قم بإنشاء أو إدارة مفاتيح API في Dashboard > API > API Keys.

الموضع: header

الترويسات

X-TokenLab-Delivery-Policy?string

سياسة التسليم لكل طلب. تتجاوز إعدادات API key و Workspace الافتراضية. يحاول النظام تلقائياً استخدام TokenLab Verified أولاً، وقد ينتقل مرة واحدة إلى Official فقط قبل المخرجات، أو قبول الطلب، أو إنشاء مورد دائم.

القيم المتاحة

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

مفتاح اختياري يجعل طلب الإنشاء آمناً لإعادة المحاولة. أرسل قيمة فريدة جديدة، مثل UUID، لكل مهمة. إعادة المحاولة بنفس المفتاح ونفس نص الطلب تُرجع نتيجة طلب الإنشاء الأصلي، وعادةً ما تكون المهمة الأصلية، ولا تقوم بإنشاء أو إرسال أو احتساب تكلفة مهمة ثانية. يتم رفض نص الطلب المختلف الذي يستخدم مفتاحاً تم قبوله مسبقاً بالرمز 409. يتم تجاهل المفتاح الذي يتجاوز 255 حرفاً، وعندها لا يتمتع الطلب بحماية idempotency. راجع إعادة المحاولة بأمان باستخدام مفتاح idempotency.

الطول1 <= length <= 255

جسم الطلب

application/json

الاستجابة

application/json

application/json

application/json

application/json

application/json