Worlds

Buat World

Membuat tugas pembuatan world World Labs Marble

POST
/v1/worlds/generations

Hasilkan world 3D yang dapat dijelajahi dengan World Labs Marble. Ini adalah API asinkron: respons pembuatan mengembalikan identitas tugas. Lakukan polling GET /v1/tasks/{id} dengan id tugas untuk memeriksa status.

Pilih model Marble yang saat ini tersedia menggunakan Models API.

Body Permintaan

modelstringbawaan: marble-1.0

Pilih model Marble yang saat ini tersedia menggunakan Models API.

promptstring

Prompt teks untuk pembuatan khusus teks, atau panduan untuk input gambar dan video. Hingga 4000 karakter. Kirimkan setidaknya salah satu dari world_prompt, prompt, image, image_url, images, atau video_url.

world_promptobject

Objek world_prompt bawaan World Labs untuk pemanggil tingkat lanjut. Jenis prompt yang didukung adalah text, image, multi-image, dan video. Referensi konten dapat mengarah ke file yang Anda unggah dengan Menyiapkan Unggahan Aset Media: { "source": "media_asset", "media_asset_id": "..." }.

imagestring

Prompt gambar Base64 atau data URL.

image_urlstring

Prompt URL gambar.

imagesarray

Beberapa prompt gambar untuk pintasan pembuatan multi-gambar. Sediakan hingga 4 gambar, masing-masing berupa URL, string Base64 atau data URL, atau objek dengan uri, image_url, atau url dan angka azimuth opsional. Untuk mode rekonstruksi bawaan World Labs, teruskan world_prompt.type="multi-image" dengan reconstruct_images: true dan hingga 8 gambar.

video_urlstring

Prompt URL video.

is_panoboolean | string

Untuk input gambar, tetapkan true untuk panorama yang ada, false untuk gambar tunggal normal, atau auto.

seedinteger

Seed opsional dari 0 hingga 4294967295.

display_namestring

Nama tampilan opsional untuk world yang dibuat, hingga 64 karakter.

tagsarray

Tag World Labs opsional. Sediakan hingga 10 tag, masing-masing hingga 32 karakter.

permissionobject

Pengaturan visibilitas dan akses opsional: public, allow_id_access, allowed_readers, dan allowed_writers. public: true meminta world yang terlihat secara publik.

Respons

idstring

ID tugas publik. Lakukan polling GET /v1/tasks/{id} menggunakannya.

task_idstring

Alias pengenal tugas asinkron.

operation_idstring

ID operasi World Labs.

poll_urlstring

URL status world di bawah /v1/worlds/generations/{id}. Ini adalah endpoint kompatibilitas. Lakukan polling GET /v1/tasks/{id} dengan id sebagai gantinya.

statusstring

Status tugas: pending, processing, completed, atau failed.

world_marble_urlstring

URL untuk world Marble yang dibuat saat selesai.

glb_urlstring

URL GLB collider mesh saat tersedia.

pano_urlstring

URL gambar panorama saat tersedia.

Pricing

Lihat Pricing API untuk tarif saat ini. Jumlah tagihan akhir ditampilkan dalam catatan penggunaan Anda.

Errors

  • 400 invalid_request: tidak ada input prompt yang dikirim, atau field berada di luar rentang. param menyebutkan nama field tersebut.
  • 400 model_not_found atau unsupported_endpoint: model tersebut bukan model Marble yang dapat dipanggil.
  • 403 media_asset_not_owned atau 404 media_asset_not_found: media_asset_id dalam world_prompt milik Workspace lain atau tidak ada.
  • 402: saldo terlalu rendah untuk memulai tugas.

Permintaan

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

Otorisasi

BearerAuth
AuthorizationBearer <token>

Autentikasi API Key. Buat atau kelola API key di Dashboard > API > API Keys.

Lokasi: header

Header

X-TokenLab-Delivery-Policy?string

Kebijakan Pengiriman per-permintaan. Menggantikan default API key dan Workspace. Secara otomatis mencoba TokenLab Verified terlebih dahulu dan dapat beralih satu kali ke Official saja sebelum output, penerimaan permintaan, atau pembuatan sumber daya persisten.

Nilai yang tersedia

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

Kunci opsional yang membuat permintaan pembuatan aman untuk dicoba ulang. Kirim nilai unik baru, seperti UUID, untuk setiap tugas. Percobaan ulang dengan kunci dan body yang sama akan mengembalikan hasil dari permintaan pembuatan asli, biasanya berupa tugas asli, dan tidak akan membuat, mengirim, atau mengenakan biaya untuk tugas kedua. Body yang berbeda dengan kunci yang sudah diterima akan ditolak dengan 409. Kunci yang lebih panjang dari 255 karakter akan diabaikan, dan permintaan tersebut tidak akan memiliki perlindungan idempotensi. Lihat Retry safely with an idempotency key.

Panjang1 <= length <= 255

Body permintaan

application/json

Respons

application/json

application/json

application/json

application/json

application/json