> ## 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.

# Tạo World

> Tạo tác vụ sinh thế giới World Labs Marble

Tạo thế giới 3D có thể khám phá bằng World Labs Marble. Đây là API bất đồng bộ: phản hồi tạo trả về định danh tác vụ và `poll_url` để kiểm tra trạng thái.

Các model được hỗ trợ là `marble-1.0`, `marble-1.1` và `marble-1.1-plus`. World Labs có tài liệu cho `marble-1.0-draft`, nhưng TokenLab hiện chưa mở draft generation trong endpoint này.

## Nội dung yêu cầu

<ParamField body="model" type="string" default="marble-1.0">
  Model Marble cần dùng: `marble-1.0`, `marble-1.1` hoặc `marble-1.1-plus`.
</ParamField>

<ParamField body="prompt" type="string">
  Prompt văn bản cho sinh từ text-only hoặc làm hướng dẫn khi có đầu vào ảnh/video.
</ParamField>

<ParamField body="world_prompt" type="object">
  Đối tượng World Labs native `world_prompt` cho caller nâng cao. Các loại prompt được hỗ trợ là `text`, `image`, `multi-image` và `video`.
</ParamField>

<ParamField body="image" type="string">
  Prompt ảnh dạng Base64 hoặc data URL.
</ParamField>

<ParamField body="image_url" type="string">
  Prompt URL ảnh.
</ParamField>

<ParamField body="images" type="array">
  Nhiều prompt ảnh cho shortcut multi-image generation. Cung cấp tối đa 4 ảnh. Với chế độ reconstruction native của World Labs, truyền `world_prompt.type="multi-image"` cùng `reconstruct_images: true` và tối đa 8 ảnh.
</ParamField>

<ParamField body="video_url" type="string">
  Prompt URL video.
</ParamField>

<ParamField body="is_pano" type="boolean | string">
  Với đầu vào ảnh, đặt `true` cho panorama có sẵn, `false` cho ảnh đơn thông thường, hoặc `auto`.
</ParamField>

<ParamField body="seed" type="integer">
  Seed tùy chọn từ 0 đến 4294967295.
</ParamField>

<ParamField body="display_name" type="string">
  Tên hiển thị tùy chọn cho world đã tạo, tối đa 64 ký tự.
</ParamField>

<ParamField body="tags" type="array">
  Tag World Labs tùy chọn. Tối đa 10 tag, mỗi tag tối đa 32 ký tự.
</ParamField>

<ParamField body="permission" type="object">
  Đối tượng permission World Labs tùy chọn.
</ParamField>

## Phản hồi

<ResponseField name="id" type="string">
  ID tác vụ công khai để polling.
</ResponseField>

<ResponseField name="task_id" type="string">
  Alias của định danh tác vụ bất đồng bộ.
</ResponseField>

<ResponseField name="operation_id" type="string">
  ID thao tác của World Labs.
</ResponseField>

<ResponseField name="poll_url" type="string">
  URL polling được khuyến nghị cho tác vụ này.
</ResponseField>

<ResponseField name="status" type="string">
  Trạng thái tác vụ: `pending`, `processing`, `completed` hoặc `failed`.
</ResponseField>

<ResponseField name="world_marble_url" type="string">
  URL world Marble đã sinh khi hoàn tất.
</ResponseField>

<ResponseField name="glb_url" type="string">
  URL GLB của collider mesh nếu có.
</ResponseField>

<ResponseField name="pano_url" type="string">
  URL ảnh panorama nếu có.
</ResponseField>

## Giá

World Labs tính phí bằng credits. TokenLab trừ trước mức tối đa theo loại request và quyết toán theo `cost.total_credits` của operation đã hoàn tất khi có. Request Marble tiêu chuẩn tối đa 1.600 credits. `marble-1.1-plus` tối đa 3.100 credits.

## Phạm vi

Các endpoint quản lý này bao phủ media asset thuộc TokenLab và world đã tạo xong. TokenLab vẫn chưa mở tạo `marble-1.0-draft` hoặc công cụ pano/depth độc lập.

<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": "Một thị trấn ven biển yên tĩnh lúc hoàng hôn với ngõ hẹp và ánh đèn ấm"
    }'
  ```

  ```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": "Một thị trấn ven biển yên tĩnh lúc hoàng hôn với ngõ hẹp và ánh đèn ấm",
      },
  )

  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: 'Một thị trấn ven biển yên tĩnh lúc hoàng hôn với ngõ hẹp và ánh đèn ấm'
    })
  });

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