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:
| Input | Field |
|---|---|
| Văn bản | prompt, tối đa 4.000 ký tự |
| Một hình ảnh | image_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 ảnh | images, tối đa 4 |
| Video | video_url |
| Nâng cao | world_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 World | Tạ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 Asset | Chuẩn bị tải lên tài nguyên phương tiện |
| Lấy Media Asset | Lấy Media Asset |
| Danh sách Worlds | Liệt kê Worlds |
| Lấy World | Lấy thông tin World |
| Xóa World | Xóa World |
| Async Jobs | Async Jobs |
| Hướng dẫn 3D Generation | 3D Generation Guide |