> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# إنشاء World

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

أنشئ عوالم ثلاثية الأبعاد قابلة للاستكشاف باستخدام World Labs Marble. هذا API غير متزامن: تعيد استجابة الإنشاء هوية المهمة و `poll_url` للتحقق من الحالة.

النماذج المدعومة هي `marble-1.0` و `marble-1.1` و `marble-1.1-plus`. توثق World Labs النموذج `marble-1.0-draft`، لكن TokenLab لا يتيح draft generation في هذا endpoint حالياً.

## جسم الطلب

<ParamField body="model" type="string" default="marble-1.0">
  نموذج Marble المطلوب استخدامه: `marble-1.0` أو `marble-1.1` أو `marble-1.1-plus`.
</ParamField>

<ParamField body="prompt" type="string">
  موجه نصي للتوليد النصي فقط أو كإرشاد مع مدخلات الصور/الفيديو.
</ParamField>

<ParamField body="world_prompt" type="object">
  كائن World Labs أصلي باسم `world_prompt` للمستخدمين المتقدمين. أنواع الموجهات المدعومة هي `text` و `image` و `multi-image` و `video`.
</ParamField>

<ParamField body="image" type="string">
  موجه صورة بصيغة Base64 أو data URL.
</ParamField>

<ParamField body="image_url" type="string">
  موجه عبر URL صورة.
</ParamField>

<ParamField body="images" type="array">
  عدة موجهات صور لاختصار multi-image generation. يمكن إرسال حتى 4 صور. لوضع reconstruction mode الأصلي في World Labs، أرسل `world_prompt.type="multi-image"` مع `reconstruct_images: true` وحتى 8 صور.
</ParamField>

<ParamField body="video_url" type="string">
  موجه عبر URL فيديو.
</ParamField>

<ParamField body="is_pano" type="boolean | string">
  لمدخلات الصور، استخدم `true` لصورة بانورامية موجودة، أو `false` لصورة واحدة عادية، أو `auto`.
</ParamField>

<ParamField body="seed" type="integer">
  Seed اختياري من 0 إلى 4294967295.
</ParamField>

<ParamField body="display_name" type="string">
  اسم عرض اختياري للعالم المُنشأ، حتى 64 حرفاً.
</ParamField>

<ParamField body="tags" type="array">
  وسوم World Labs اختيارية. حتى 10 وسوم، كل وسم حتى 32 حرفاً.
</ParamField>

<ParamField body="permission" type="object">
  كائن permission اختياري من World Labs.
</ParamField>

## الاستجابة

<ResponseField name="id" type="string">
  معرف مهمة عام لاستخدامه في polling.
</ResponseField>

<ResponseField name="task_id" type="string">
  اسم بديل لمعرف المهمة غير المتزامنة.
</ResponseField>

<ResponseField name="operation_id" type="string">
  معرّف العملية في World Labs.
</ResponseField>

<ResponseField name="poll_url" type="string">
  رابط polling المفضل لهذه المهمة.
</ResponseField>

<ResponseField name="status" type="string">
  حالة المهمة: `pending` أو `processing` أو `completed` أو `failed`.
</ResponseField>

<ResponseField name="world_marble_url" type="string">
  رابط عالم Marble الناتج عند الاكتمال.
</ResponseField>

<ResponseField name="glb_url" type="string">
  رابط GLB لشبكة collider عند توفره.
</ResponseField>

<ResponseField name="pano_url" type="string">
  رابط صورة بانورامية عند توفرها.
</ResponseField>

## التسعير

تحاسب World Labs باستخدام credits. يخصم TokenLab الحد الأقصى لنوع الطلب مسبقاً، ثم يسوي حسب `cost.total_credits` من operation المكتملة عند توفرها. طلبات Marble القياسية تصل إلى 1,600 credits. طلبات `marble-1.1-plus` تصل إلى 3,100 credits.

## النطاق

تغطي نقاط الإدارة هذه أصول الوسائط المملوكة لـ TokenLab والعوالم المكتملة. لا يتيح TokenLab بعد إنشاء `marble-1.0-draft` أو أدوات pano/depth المستقلة.

<RequestExample>
  ```bash cURL theme={null}
  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": "بلدة ساحلية هادئة عند الغروب مع أزقة ضيقة وأضواء دافئة"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.tokenlab.sh/v1/worlds/generations",
      headers={"Authorization": "Bearer sk-your-api-key"},
      json={
          "model": "marble-1.1",
          "prompt": "بلدة ساحلية هادئة عند الغروب مع أزقة ضيقة وأضواء دافئة",
      },
  )

  task = response.json()
  print(task["id"], task["poll_url"])
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.tokenlab.sh/v1/worlds/generations', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer sk-your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'marble-1.1',
      prompt: 'بلدة ساحلية هادئة عند الغروب مع أزقة ضيقة وأضواء دافئة'
    })
  });

  const task = await response.json();
  console.log(task.id, task.poll_url);
  ```
</RequestExample>