TokenLab

Worlds

Tạo thế giới

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

POST
/v1/worlds/generations

Tạo các thế giới 3D có thể khám phá với World Labs Marble. Đây là một API bất đồng bộ: phản hồi tạo sẽ trả về định danh tác vụ. Thực hiện poll GET /v1/tasks/{id} với id của tác vụ để kiểm tra trạng thái.

Chọn một model Marble hiện khả dụng bằng cách sử dụng Models API.

Phần thân yêu cầu (Request Body)

modelstringmặc định: marble-1.0

Chọn một model Marble hiện khả dụng bằng cách sử dụng Models API.

promptstring

Prompt dạng văn bản để tạo chỉ từ văn bản, hoặc làm chỉ dẫn cho đầu vào hình ảnh và video. Tối đa 4000 ký tự. Gửi ít nhất một trong các trường world_prompt, prompt, image, image_url, images, hoặc video_url.

world_promptobject

Đố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 prompt được hỗ trợ là text, image, multi-image, và video. Một tham chiếu nội dung có thể trỏ tới tệp bạn đã tải lên bằng Chuẩn bị tải lên tài nguyên phương tiện: { "source": "media_asset", "media_asset_id": "..." }.

imagestring

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

image_urlstring

Prompt URL hình ảnh.

imagesarray

Nhiều prompt hình ảnh để tạo nhiều ảnh theo cách rút gọn. Cung cấp tối đa 4 hình ảnh, mỗi hình ảnh là một URL, chuỗi Base64 hoặc data URL, hoặc một đối tượng có uri, image_url, hoặc url và số azimuth tùy chọn. Đối với chế độ tái tạo gốc của World Labs, hãy truyền world_prompt.type="multi-image" với reconstruct_images: true và tối đa 8 hình ảnh.

video_urlstring

Prompt URL video.

is_panoboolean | string

Đối với đầu vào hình ảnh, đặt true cho ảnh toàn cảnh (panorama) hiện có, 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 thế giới được tạo, tối đa 64 ký tự.

tagsarray

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

permissionobject

Cài đặt quyền truy cập và hiển thị tùy chọn: public, allow_id_access, allowed_readers, và allowed_writers. public: true yêu cầu một thế giới hiển thị công khai.

Phản hồi

idstring

ID tác vụ công khai. Sử dụng nó để poll GET /v1/tasks/{id}.

task_idstring

Bí danh định danh tác vụ bất đồng bộ.

operation_idstring

ID thao tác World Labs.

poll_urlstring

URL trạng thái thế giới dưới /v1/worlds/generations/{id}. Đây là một endpoint tương thích. Thay vào đó, hãy poll GET /v1/tasks/{id} với id.

statusstring

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

world_marble_urlstring

URL cho thế giới Marble được tạo khi hoàn tất.

glb_urlstring

URL GLB của collider mesh khi khả dụng.

pano_urlstring

URL hình ảnh toàn cảnh (panorama) khi khả dụng.

Giá cả

Xem Pricing API để biết giá hiện tại. Số tiền thanh toán cuối cùng sẽ được hiển thị trong hồ sơ sử dụng của bạn.

Lỗi

  • 400 invalid_request: không có đầu vào prompt nào được gửi, hoặc một trường nằm ngoài phạm vi. param chỉ định tên trường.
  • 400 model_not_found hoặc unsupported_endpoint: model không phải là model Marble có thể gọi được.
  • 403 media_asset_not_owned hoặc 404 media_asset_not_found: media_asset_id trong world_prompt thuộc về một Workspace khác hoặc không tồn tại.
  • 402: số dư quá thấp để bắt đầu tác vụ.

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

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"
Idempotency-Key?string

Khóa tùy chọn giúp yêu cầu tạo trở nên an toàn khi thử lại. Hãy gửi một giá trị duy nhất mới, chẳng hạn như UUID, cho mỗi tác vụ. Thử lại với cùng khóa và cùng phần thân sẽ trả về kết quả của yêu cầu tạo ban đầu, thường là tác vụ gốc, và không tạo, điều phối hoặc tính phí tác vụ thứ hai. Phần thân khác với khóa đã được chấp nhận sẽ bị từ chối với 409. Khóa dài hơn 255 ký tự sẽ bị bỏ qua và yêu cầu đó sẽ không có bảo vệ idempotency. Xem Thử lại an toàn với khóa idempotency.

Độ dài1 <= length <= 255

Nội dung yêu cầu

application/json

Phản hồi

application/json

application/json

application/json

application/json

application/json