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
| Input | Wajib | Bidang opsional | Catatan |
|---|---|---|---|
| Text-to-3D | model, prompt | format, quality, style, seed | Terbaik untuk membuat aset baru dari deskripsi |
| Image-to-3D | model, image_url atau image; juga prompt jika model mencantumkannya | format, quality, style, seed | Gunakan 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
glbberfungsi dengan baik untuk pratinjau web.fbxdanobjberguna untuk pipeline DCC jika model yang dipilih mendukungnya.usdzberguna untuk alur kerja AR Apple jika disediakan oleh model.- Nilai
qualityyang lebih tinggi dapat meningkatkan waktu tunggu dan biaya. Tunjukkan pilihan tersebut kepada pengguna. seedhanya 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_idjika ada untuk rekonsiliasi di kemudian hari.
Kesalahan Umum
| Gejala | Kemungkinan penyebab | Perbaikan |
|---|---|---|
| Respons pembuatan tidak memiliki URL aset | Generasi 3D bersifat asinkron | Lakukan polling hingga status terminal |
| Format yang diminta hilang | Model tidak mengembalikan format tersebut | Kembali ke model_url atau pilih model yang mendukung format tersebut |
| Image-to-3D ditolak | Model yang dipilih hanya teks atau URL gambar tidak dapat dijangkau | Periksa detail model dan validasi URL |
| Aset duplikat | Jalur percobaan ulang membuat ulang tugas setelah timeout | Simpan identitas tugas sebelum mencoba ulang |
Referensi API
| Topik | Referensi |
|---|---|
| Buat 3D | Buat 3D |
| Dapatkan Status 3D | Dapatkan Status 3D |
| Dapatkan Status Tugas | Dapatkan Status Tugas |
| Daftar Model | Daftar Model |
| Penagihan & Harga | Penagihan & Harga |