Panduan media
Worlds
Buat dunia Marble yang dapat dijelajahi dari teks, gambar, atau video
Worlds membuat lingkungan Marble yang dapat dibuka dan dijelajahi oleh pengguna. Jika Anda memerlukan objek yang dapat diunduh alih-alih lingkungan, gunakan 3D generation.
File World yang dapat diunduh, seperti splat, mesh, dan gambar panorama, disimpan sebagai salinan otomatis selama 30 hari dengan URL media-result TokenLab. Halaman World interaktif dan catatan World tidak disimpan demikian. Lihat Retensi data.
Input Dan Aset Media
Sebuah world dapat dimulai dari teks, satu atau beberapa gambar, atau video, tergantung pada modelnya. Temukan model Marble (marble-*) di GET /v1/models?recommended_for=3d; operasinya adalah world-generation. Kirim setidaknya satu input:
| Input | Field |
|---|---|
| Teks | prompt, hingga 4.000 karakter |
| Satu gambar | image_url, atau image sebagai Base64 atau data URL; is_pano menentukan apakah gambar tersebut sudah berupa panorama |
| Beberapa gambar | images, hingga 4 |
| Video | video_url |
| Lanjutan | world_prompt, objek prompt native yang dapat mereferensikan aset media yang diunggah |
Field opsional meliputi display_name (hingga 64 karakter), seed, tags (hingga 10), dan permission. Media yang dapat digunakan kembali dapat diunggah sekali dan direferensikan berdasarkan ID asetnya.
Akses ke media dan catatan world diperiksa berdasarkan organisasi yang memiliki API key tersebut. Tinjau opsi permission pada model yang dipilih sebelum membagikan world; aset yang dikembalikan atau URL penampil mungkin memiliki aturan aksesnya sendiri.
Membuat Dan Melakukan Polling
Respons pembuatan berisi ID tugas dan biasanya poll_url. Simpan ID tersebut, lalu panggil GET /v1/tasks/{id} dengan ID tersebut hingga statusnya menjadi completed atau failed. poll_url untuk Worlds mengarah ke /v1/worlds/generations/{id}, sebuah jalur kompatibilitas. Gunakan /v1/tasks/{id} sebagai gantinya.
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"
}'Lakukan polling pada tugas dengan id dari respons pembuatan:
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer sk-your-api-key"Mengelola World Yang Selesai
Gunakan POST /v1/worlds/list dan GET /v1/worlds/{id} untuk world yang sudah selesai dan tersedia di akun Anda, serta DELETE /v1/worlds/{id} untuk menghapusnya. Gunakan GET /v1/tasks/{id} untuk tugas pembuatan yang tertunda atau gagal. Hapus hanya jika pengguna secara sengaja menghapus world yang dihasilkan dari produk Anda.
Kendala Umum
- Jangan berasumsi bahwa setiap model world mendukung setiap jenis input.
- Pastikan URL gambar atau video yang ditandatangani (signed URL) tetap valid cukup lama untuk percobaan pengambilan ulang oleh layanan.
- Simpan ID tugas yang dikembalikan sebelum mencoba lagi setelah timeout.
- Gunakan 3D generation untuk file model yang dapat diunduh, bukan untuk world yang dapat dijelajahi.
Referensi API
| Topik | Referensi |
|---|---|
| Create World | Buat World |
| Get Task Status | Mendapatkan Status Tugas |
| Get World Status (kompatibilitas) | Mendapatkan Status Dunia |
| Prepare Media Asset Upload | Menyiapkan Unggahan Aset Media |
| Get Media Asset | Dapatkan Aset Media |
| List Worlds | Daftar World |
| Get World | Dapatkan World |
| Delete World | Hapus World |
| Async Jobs | Async Jobs |
| 3D Generation Guide | 3D Generation Guide |