Panduan media

Generasi 3D

Buat model 3D yang dapat diunduh dari teks atau gambar

Generasi 3D bersifat asinkron. POST /v1/3d/generations membuat tugas TokenLab; respons status selesai akan mengembalikan aset model yang dapat diunduh seperti model_url dan, jika tersedia, URL khusus format.

File model 3D yang dapat diunduh disimpan sebagai salinan otomatis selama 30 hari, dan URL-nya adalah URL media-result TokenLab. Catatan tugas dan aset yang disimpan secara terpisah mengikuti siklus hidupnya masing-masing. Lihat Retensi data.

Pilih tipe input

InputWajibBidang opsionalCatatan
Text-to-3Dmodel, promptformat, quality, style, seedTerbaik untuk membuat aset baru dari deskripsi
Image-to-3Dmodel, image_url atau image; juga prompt jika model mencantumkannyaformat, quality, style, seedGunakan hanya jika model yang dipilih mendukung input gambar

operation bersifat opsional dan bernilai text-to-3d atau image-to-3d. Jika Anda mengosongkannya, TokenLab menggunakan image-to-3d saat Anda mengirim image atau image_url, dan text-to-3d jika tidak. Jika Anda mengirimkannya, nilainya harus sesuai dengan input. Model dengan text-to-3d menerima prompt; model dengan image-to-3d menerima input gambar.

curl "https://api.tokenlab.sh/v1/models?recommended_for=3d" \
  -H "Authorization: Bearer sk-your-api-key"

Jangan berasumsi bahwa setiap model 3D mendukung kedua tipe input atau setiap format output. Periksa detail model yang dipilih sebelum mengirim image, image_url, format, quality, style, atau seed.

Membuat tugas 3D

curl https://api.tokenlab.sh/v1/3d/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tripo-h3.1",
    "prompt": "A stylized low-poly robot mascot with clean topology"
  }'

Untuk image-to-3D, gunakan URL https jika sumber dapat diambil dari internet. Gunakan image base64 inline hanya pada model yang detailnya mencantumkan image; beberapa model hanya menerima image_url.

Format output

  • glb berfungsi dengan baik untuk pratinjau web.
  • fbx dan obj berguna untuk pipeline DCC jika model yang dipilih mendukungnya.
  • usdz berguna untuk alur kerja AR Apple jika disediakan oleh model.
  • Nilai quality yang lebih tinggi dapat meningkatkan waktu tunggu dan biaya. Tunjukkan pilihan tersebut kepada pengguna.
  • seed hanya memengaruhi pengulangan pada model yang mendukungnya.

Mendapatkan model yang sudah selesai

Panggil GET /v1/tasks/{id} dengan id atau task_id yang dikembalikan.

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

Tugas yang selesai akan mengembalikan model_url dan mungkin menyertakan glb_url, fbx_url, obj_url, atau usdz_url. Unduh atau cache aset yang dipilih di produk Anda sendiri jika pengguna memerlukan akses berulang, riwayat versi, atau unduhan jangka panjang.

Menjaga ketersediaan hasil

  • Simpan task_id, poll_url, model, format yang diminta, dan ID catatan aset Anda sendiri.
  • Lanjutkan polling setelah penyegaran halaman alih-alih membuat tugas duplikat.
  • Validasi ukuran dan keterjangkauan gambar sumber sebelum membuat tugas.
  • Jauhkan URL aset yang dihasilkan dari halaman publik kecuali pengguna memiliki izin untuk mengakses aset tersebut.
  • Catat billing_transaction_id jika ada untuk rekonsiliasi di kemudian hari.

Kesalahan Umum

GejalaKemungkinan penyebabPerbaikan
Respons pembuatan tidak memiliki URL asetGenerasi 3D bersifat asinkronLakukan polling hingga status terminal
Format yang diminta hilangModel tidak mengembalikan format tersebutKembali ke model_url atau pilih model yang mendukung format tersebut
Image-to-3D ditolakModel yang dipilih hanya teks atau URL gambar tidak dapat dijangkauPeriksa detail model dan validasi URL
Aset duplikatJalur percobaan ulang membuat ulang tugas setelah timeoutSimpan identitas tugas sebelum mencoba ulang

Referensi API

TopikReferensi
Buat 3DBuat 3D
Dapatkan Status 3DDapatkan Status 3D
Dapatkan Status TugasDapatkan Status Tugas
Daftar ModelDaftar Model
Penagihan & HargaPenagihan & Harga

Di halaman ini