> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Generasi 3D

> Buat tugas teks-ke-3D atau gambar-ke-3D, polling untuk aset yang selesai, dan tangani file model yang dapat diunduh.

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

## Pilih Jenis Input

| Alur Kerja   | Input yang Diperlukan                       | Bidang Opsional                      | Catatan                                                        |
| ------------ | ------------------------------------------- | ------------------------------------ | -------------------------------------------------------------- |
| Teks-ke-3D   | `model`, `prompt`                           | `format`, `quality`, `style`, `seed` | Terbaik untuk menghasilkan aset baru dari deskripsi            |
| Gambar-ke-3D | `model`, `prompt`, `image` atau `image_url` | `format`, `quality`, `style`, `seed` | Gunakan hanya ketika model yang dipilih mendukung input gambar |

Kueri katalog model sebelum memutuskan opsi mana yang akan diekspos:

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

Jangan menganggap setiap model 3D mendukung kedua jenis input atau setiap format output. Periksa kontrak model yang dipilih sebelum mengirim `image`, `image_url`, `format`, `quality`, `style`, atau `seed`.

## Buat Tugas 3D

```bash theme={null}
curl https://api.tokenlab.sh/v1/3d/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tripo3d-v2.5",
    "prompt": "Sebuah maskot robot low-poly bergaya dengan topologi yang bersih",
    "format": "glb",
    "quality": "standard"
  }'
```

Untuk gambar-ke-3D, gunakan `image_url` publik jika memungkinkan. Gunakan `image` inline/base64 hanya ketika klien Anda sengaja mengirim media pribadi dan backend Anda siap untuk tubuh permintaan yang lebih besar.

## Pilihan Format Output

* `glb` biasanya adalah default yang paling aman untuk pratinjau web.
* `fbx` dan `obj` berguna untuk alur kerja DCC ketika model yang dipilih mendukungnya.
* `usdz` berguna untuk alur kerja AR Apple ketika diekspos oleh model.
* Nilai `quality` yang lebih tinggi dapat meningkatkan latensi dan biaya. Ekspos sebagai pilihan pengguna yang eksplisit, bukan default tersembunyi.
* `seed` berguna untuk reproduktifitas hanya ketika model menghormatinya.

## Polling dan Simpan Aset

Gunakan `poll_url` yang dikembalikan terlebih dahulu. Jika klien Anda memerlukan rute tetap, gunakan `GET /v1/tasks/{id}`.

```bash theme={null}
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"
```

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

## Daftar Periksa Produksi

* Simpan `task_id`, `poll_url`, model, format yang diminta, dan ID catatan aset Anda sendiri.
* Lanjutkan polling setelah penyegaran halaman daripada membuat tugas duplikat.
* Validasi ukuran dan keterjangkauan gambar sumber sebelum membuat tugas.
* Jaga agar URL aset yang dihasilkan tidak muncul di halaman publik kecuali pengguna memiliki izin untuk mengakses aset tersebut.
* Catat `billing_transaction_id` ketika ada untuk rekonsiliasi di kemudian hari.

## Kesalahan Umum

| Gejala                                    | Penyebab yang Mungkin                                               | Perbaikan                                                              |
| ----------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Respons pembuatan tidak memiliki URL aset | Generasi 3D bersifat asinkron                                       | Polling hingga status terminal                                         |
| Format yang diminta hilang                | Model tidak mengembalikan format tersebut                           | Kembali ke `model_url` atau pilih model yang mendukung format tersebut |
| Gambar-ke-3D ditolak                      | Model yang dipilih hanya teks atau URL gambar tidak dapat dijangkau | Periksa kontrak model dan validasi URL                                 |
| Aset duplikat                             | Jalur coba ulang membuat tugas setelah waktu habis                  | Simpan identitas tugas sebelum mencoba ulang                           |

## Referensi API

| Topik                 | Referensi                                                        |
| --------------------- | ---------------------------------------------------------------- |
| Buat 3D               | [Buat 3D](/id/api-reference/3d/create-3d)                        |
| Dapatkan Status 3D    | [Dapatkan Status 3D](/id/api-reference/3d/get-3d-status)         |
| Dapatkan Status Tugas | [Dapatkan Status Tugas](/id/api-reference/tasks/get-task-status) |
| Daftar Model          | [Daftar Model](/id/api-reference/models/list-models)             |
| Penagihan & Harga     | [Penagihan & Harga](/id/guides/billing)                          |