Tạo World

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.

Chọn model Marble hiện có qua Models API.

Nội dung yêu cầu

modelstringmặc định: marble-1.0

Chọn model Marble hiện có qua Models API.

promptstring

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.

world_promptobject

Đố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.

imagestring

Prompt ảnh dạng Base64 hoặc data URL.

image_urlstring

Prompt URL ảnh.

imagesarray

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.

video_urlstring

Prompt URL video.

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

seedinteger

Seed tùy chọn từ 0 đến 4294967295.

display_namestring

Tên hiển thị tùy chọn cho world đã tạo, tối đa 64 ký tự.

tagsarray

Tag World Labs tùy chọn. Tối đa 10 tag, mỗi tag tối đa 32 ký tự.

permissionobject

Thiết lập hiển thị và truy cập tùy chọn: public, allow_id_access, allowed_readers, allowed_writers. public: true yêu cầu tạo world có thể xem công khai.

Phản hồi

idstring

ID tác vụ công khai để polling.

task_idstring

Alias của định danh tác vụ bất đồng bộ.

operation_idstring

ID thao tác của World Labs.

poll_urlstring

URL polling được khuyến nghị cho tác vụ này.

statusstring

Trạng thái tác vụ: pending, processing, completed hoặc failed.

world_marble_urlstring

URL world Marble đã sinh khi hoàn tất.

glb_urlstring

URL GLB của collider mesh nếu có.

pano_urlstring

URL ảnh panorama nếu có.

Giá

Xem Pricing API để biết giá hiện tại. Số tiền tính phí nằm trong bản ghi sử dụng; cost.total_credits được trả về là lượng sử dụng tạo world, không phải số tiền.

Yêu cầu

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"
  }'

{  "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",  "cost": {},  "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"    }  }}

Xác thực

BearerAuth

AuthorizationBearer <token>

Xác thực bằng Khóa API. Tạo hoặc quản lý khóa API trong Dashboard > API > API Keys.

Vị trí: header

Header

X-TokenLab-Delivery-Policy?string

Chính sách phân phối theo yêu cầu. Ghi đè các mặc định của API key và Workspace. Tự động thử TokenLab Verified trước và có thể chuyển đổi một lần sang Official chỉ trước khi xuất, chấp nhận yêu cầu hoặc tạo tài nguyên cố định.

Giá trị hợp lệ

"auto"
"verified"
"official"

Nội dung yêu cầu

application/json

model?string

Mô hình Marble để sử dụng. Mặc định là marble-1.0 để khớp với mặc định tương thích World Labs hiện tại khi mô hình bị bỏ qua.

mặc định"marble-1.0"

Giá trị hợp lệ

"marble-1.0"
"marble-1.1"
"marble-1.1-plus"

prompt?string

Lời nhắc văn bản được sử dụng cho việc tạo thế giới bằng văn bản hoặc hình ảnh/video có hướng dẫn.

display_name?string

Tên hiển thị tùy chọn cho thế giới được tạo, tối đa 64 ký tự.

Độ dàilength <= 64

world_prompt*

Đối tượng world_prompt gốc của World Labs dành cho người gọi nâng cao. Các loại lời nhắc được hỗ trợ là text, image, multi-image và video. Các tham chiếu nội dung có thể sử dụng source=media_asset với media_asset_id được chuẩn bị bởi /v1/worlds/media-assets/prepare-upload.

image?string

Lời nhắc hình ảnh Base64 hoặc URL dữ liệu.

image_url?string

Lời nhắc URL hình ảnh.

Định dạnguri

images?array<string|>

Lời nhắc đa hình ảnh rút gọn. Cung cấp tối đa 4 hình ảnh. Sử dụng world_prompt.reconstruct_images=true gốc cho tối đa 8 hình ảnh.

Phần tửitems <= 4

video_url?string

Lời nhắc URL video.

Định dạnguri

is_pano?|

Liệu lời nhắc hình ảnh có phải là ảnh toàn cảnh hiện có hay không. Sử dụng true cho đầu vào pano, false cho đầu vào hình ảnh đơn lẻ hoặc auto.

seed?integer

Seed tùy chọn từ 0 đến 4294967295.

Phạm vi0 <= value <= 4294967295

tags?array<>

Thẻ World Labs tùy chọn. Cung cấp tối đa 10 thẻ, mỗi thẻ tối đa 32 ký tự.

Phần tửitems <= 10

permission?

Đối tượng quyền World Labs tùy chọn.

user?string

Định danh người dùng cuối.

Tạo World

Nội dung yêu cầu

Phản hồi

Giá

Xác thực

Header

Nội dung yêu cầu

Phản hồi

`application/json`

`application/json`

`application/json`

Tạo World

Nội dung yêu cầuCopy Anchor Link

Phản hồiCopy Anchor Link

GiáCopy Anchor Link

Xác thựcCopy Anchor Link

HeaderCopy Anchor Link

Nội dung yêu cầuCopy Anchor Link

Phản hồiCopy Anchor Link

200application/json

401application/json

503application/json

Nội dung yêu cầu

Phản hồi

Giá

Xác thực

Header

Nội dung yêu cầu

Phản hồi

`application/json`

`application/json`

`application/json`