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:

InputField
Teksprompt, hingga 4.000 karakter
Satu gambarimage_url, atau image sebagai Base64 atau data URL; is_pano menentukan apakah gambar tersebut sudah berupa panorama
Beberapa gambarimages, hingga 4
Videovideo_url
Lanjutanworld_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

TopikReferensi
Create WorldBuat World
Get Task StatusMendapatkan Status Tugas
Get World Status (kompatibilitas)Mendapatkan Status Dunia
Prepare Media Asset UploadMenyiapkan Unggahan Aset Media
Get Media AssetDapatkan Aset Media
List WorldsDaftar World
Get WorldDapatkan World
Delete WorldHapus World
Async JobsAsync Jobs
3D Generation Guide3D Generation Guide

Di halaman ini