TokenLab

Hướng dẫn media

Worlds

Tạo các thế giới Marble có thể khám phá từ văn bản, hình ảnh hoặc video

Worlds tạo ra một môi trường Marble mà mọi người có thể mở và khám phá. Nếu bạn cần một đối tượng có thể tải xuống thay vì một môi trường, hãy sử dụng 3D generation.

Các tệp World có thể tải xuống, chẳng hạn như splats, meshes và hình ảnh panorama, được lưu giữ dưới dạng bản sao tự động trong 30 ngày với các URL media-result của TokenLab. Trang World tương tác và các bản ghi World thì không. Xem Lưu giữ dữ liệu.

Inputs And Media Assets

Một world có thể bắt đầu từ văn bản, một hoặc nhiều hình ảnh, hoặc video, tùy thuộc vào model. Tìm các model Marble (marble-*) trong GET /v1/models?recommended_for=3d; thao tác của chúng là world-generation. Gửi ít nhất một input:

InputField
Văn bảnprompt, tối đa 4.000 ký tự
Một hình ảnhimage_url, hoặc image dưới dạng Base64 hoặc data URL; is_pano cho biết liệu đó đã là panorama hay chưa
Nhiều hình ảnhimages, tối đa 4
Videovideo_url
Nâng caoworld_prompt, một đối tượng prompt gốc có thể tham chiếu đến một media asset đã tải lên

Các trường tùy chọn bao gồm display_name (tối đa 64 ký tự), seed, tags (tối đa 10) và permission. Media có thể tái sử dụng có thể được tải lên một lần và tham chiếu bằng ID asset của nó.

Quyền truy cập vào media và các bản ghi world được kiểm tra dựa trên tổ chức sở hữu API key. Hãy xem xét các tùy chọn permission của model đã chọn trước khi chia sẻ một world; một asset được trả về hoặc URL trình xem có thể có các quy tắc truy cập riêng.

Create And Poll

Phản hồi tạo (create response) chứa một task ID và thường là một poll_url. Hãy giữ lại ID đó, sau đó gọi GET /v1/tasks/{id} với ID đó cho đến khi trạng thái là completed hoặc failed. poll_url của Worlds trỏ đến /v1/worlds/generations/{id}, một đường dẫn tương thích. Hãy sử dụng /v1/tasks/{id} thay thế.

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

Poll task với id từ phản hồi tạo:

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"

Manage Completed Worlds

Sử dụng POST /v1/worlds/list và GET /v1/worlds/{id} cho các world đã hoàn thành có sẵn trong tài khoản của bạn, và DELETE /v1/worlds/{id} để xóa một world. Sử dụng GET /v1/tasks/{id} cho các tác vụ tạo đang chờ xử lý hoặc đã thất bại. Chỉ xóa khi người dùng cố ý xóa world đã tạo khỏi sản phẩm của bạn.

Common Pitfalls

  • Đừng giả định rằng mọi world model đều hỗ trợ mọi loại input.
  • Giữ cho các URL hình ảnh hoặc video đã ký có hiệu lực đủ lâu để dịch vụ thực hiện thử lại (retry).
  • Lưu trữ task ID được trả về trước khi thử lại sau khi hết thời gian chờ (timeout).
  • Sử dụng 3D generation cho các tệp model có thể tải xuống thay vì các world có thể khám phá.

API Reference

Chủ đềTham chiếu
Tạo WorldTạo thế giới
Lấy trạng thái tác vụLấy trạng thái tác vụ
Lấy trạng thái World (tương thích)Lấy Trạng thái Thế giới
Chuẩn bị tải lên Media AssetChuẩn bị tải lên tài nguyên phương tiện
Lấy Media AssetLấy Media Asset
Danh sách WorldsLiệt kê Worlds
Lấy WorldLấy thông tin World
Xóa WorldXóa World
Async JobsAsync Jobs
Hướng dẫn 3D Generation3D Generation Guide

Trên trang này