lowpoly dihentikan pada 30 Okt 2026. Ganti model sebelum tanggal-tanggal ini agar permintaan tidak error.

API UV Unwrap

API UV Unwrap secara otomatis menghasilkan UV unwrap berkualitas tinggi untuk model 3D yang ada. Gunakan ini sebagai langkah prasyarat sebelum tekstur — atau kapan pun Anda memerlukan tata letak UV yang bersih dan tidak tumpang tindih untuk alat hilir (Blender, Substance Painter, Unreal).

Outputnya adalah "model putih UV" — bentuk yang sama dengan input tetapi dengan koordinat UV baru dan tanpa tekstur nyata (material placeholder abu-abu 2×2 disertakan untuk menjaga slot material glTF tetap valid; alat standar memperlakukan ini sebagai tidak bertekstur).

Batasan. Auto UV saat ini mendukung mesh hingga 40.000 wajah — model yang lebih besar ditolak dengan 400; jalankan Remesh terlebih dahulu untuk mengurangi jumlah poligon. Mesh quad dan n-gon ditriangulasi selama pembuatan UV, sehingga outputnya selalu berupa mesh segitiga.

POST/openapi/v1/uv-unwrap

Create an UV Unwrap Task

Endpoint ini membuat tugas UV Unwrap baru.

Tugas ini berjalan di latar belakang. Untuk mengetahui perkiraan durasinya, lihat Processing Times.

Parameter

Tepat salah satu dari input_task_id atau model_url wajib diisi. Jika keduanya diberikan, input_task_id memiliki prioritas.

  • Name
    input_task_id
    Type
    string
    Wajib
    Description

    ID dari tugas Meshy API yang telah selesai dan output GLB-nya ingin Anda UV-unwrap (misalnya hasil Gambar ke 3D, Teks ke 3D, atau Remesh). Tugas sumber harus memiliki status SUCCEEDED dan telah menghasilkan file GLB.

    Jika mesh sumber melebihi batas atas jumlah wajah sebesar 40.000 wajah, permintaan akan ditolak dengan 400 dan Anda harus menjalankan Remesh terlebih dahulu untuk menurunkan jumlah poligon.

  • Name
    model_url
    Type
    string
    Wajib
    Description

    Berikan model 3D secara langsung melalui URL yang dapat diakses secara publik atau data URI. Hanya .glb yang didukung — API ini membaca glTF binary dan tidak mengurai format lain. Untuk melakukan UV-unwrap pada model dalam format lain (.fbx, .obj, .stl, .gltf), konversikan terlebih dahulu ke .glb melalui Convert API, lalu berikan ID tugas hasilnya sebagai input_task_id atau URL output GLB-nya di sini.

    Untuk Data URI, gunakan MIME type application/octet-stream.

    Ukuran file maksimum: 400 MB untuk URL http atau https, 100 MB untuk URI data:. GLB yang berukuran lebih dari 100 MB tidak boleh menggunakan kompresi Draco.

    Batas atas 40.000 wajah yang sama berlaku seperti pada input_task_id: mesh yang berukuran berlebihan akan ditolak dengan 400 — jalankan Remesh terlebih dahulu.

Returns

Properti result pada respons berisi id dari tugas UV Unwrap yang baru dibuat.

Mode Kegagalan

  • Name
    400 - Bad Request
    Description

    Permintaan tidak dapat diterima. Penyebab umum:

    • Parameter hilang: Salah satu dari input_task_id atau model_url harus diberikan.
    • Tugas input tidak valid: input_task_id harus merujuk pada tugas yang berhasil dengan hasil GLB.
    • Jumlah wajah melebihi batas: Mesh sumber memiliki jumlah wajah lebih besar dari batas atas UV Unwrap. Jalankan Remesh terlebih dahulu.
    • Format model tidak valid: model_url menunjuk ke file dengan ekstensi yang tidak didukung.
    • URL tidak dapat dijangkau: File model_url tidak dapat diunduh.
    • File model terlalu besar: File model_url melebihi 400 MB (URL http atau https) atau 100 MB (URI data:).
    • Terlalu banyak wajah: File model_url berukuran lebih dari 100 MB dan memiliki lebih dari 10.000.000 wajah. Kurangi jumlah wajah, lalu kirim ulang file tersebut.
    • File model tidak dapat dibaca: File model_url berukuran lebih dari 100 MB dan headernya tidak dapat dibaca, misalnya GLB yang terkompresi Draco.
    • Header model terlalu kompleks: File model_url berukuran lebih dari 100 MB dan headernya memiliki terlalu banyak mesh, node, atau record untuk diperiksa. Kurangi jumlah objek dalam file tersebut, lalu kirim ulang.
  • Name
    401 - Unauthorized
    Description

    Autentikasi gagal. Silakan periksa kunci API Anda.

  • Name
    402 - Payment Required
    Description

    Kredit tidak cukup untuk menjalankan tugas ini. UV Unwrap membutuhkan biaya 5 kredit per panggilan.

  • Name
    404 - Not Found
    Description

    Fitur ini tidak diaktifkan untuk akun Anda. UV Unwrap dibatasi oleh flag Statsig selama masa peluncuran — hubungi dukungan Meshy jika Anda memerlukan akses.

  • Name
    429 - Too Many Requests
    Description

    Anda telah melampaui batas laju Anda.

Request

POST
/openapi/v1/uv-unwrap
# Chain from an existing Meshy task
curl https://api.meshy.ai/openapi/v1/uv-unwrap \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
      "input_task_id": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
    }'

# Or from a publicly accessible model URL
curl https://api.meshy.ai/openapi/v1/uv-unwrap \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
      "model_url": "https://example.com/path/to/model.glb"
    }'

Response

{
  "result": "019361c6-9b34-7b23-bef2-d0107c4d92e2"
}
GET/openapi/v1/uv-unwrap/:id

Mengambil Tugas UV Unwrap

Endpoint ini mengambil status saat ini dari tugas UV Unwrap berdasarkan ID.

Mengembalikan

Mengembalikan sebuah objek Tugas UV Unwrap.

Permintaan

GET
/openapi/v1/uv-unwrap/:id
curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Lihat contoh objek tugas di bawah ini.

DELETE/openapi/v1/uv-unwrap/:id

Menghapus Tugas UV Unwrap

Menghapus tugas UV Unwrap secara permanen. Tugas dan hasil keluarannya menjadi tidak dapat diakses lagi.

Tugas yang masih berstatus PENDING akan dihapus dan kredit yang terpakai saat pembuatan akan dikembalikan.

Tugas yang sudah berstatus IN_PROGRESS tidak dapat dihapus: permintaan akan ditolak dengan 409 Conflict dan tugas tetap berjalan. Kredit untuk tugas yang sudah mulai dikerjakan oleh worker tidak dapat dikembalikan, sehingga menghapusnya di tengah proses akan membuat Anda kehilangan kredit sekaligus hasilnya. Tunggu hingga mencapai status SUCCEEDED, FAILED, atau CANCELED, baru kemudian hapus tugas tersebut.

Tugas dengan status akhir (SUCCEEDED, FAILED, atau CANCELED) akan dihapus tanpa pengembalian kredit.

Request

DELETE
/openapi/v1/uv-unwrap/:id
curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-X DELETE \
-H "Authorization: Bearer ${YOUR_API_KEY}"
GET/openapi/v1/uv-unwrap

Daftar Tugas UV Unwrap

Mengembalikan daftar paginasi dari tugas UV Unwrap pemanggil, terbaru terlebih dahulu. Paginasi standar melalui page_num dan page_size.

Permintaan

GET
/openapi/v1/uv-unwrap
curl "https://api.meshy.ai/openapi/v1/uv-unwrap?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"
GET/openapi/v1/uv-unwrap/:id/stream

Streaming Tugas UV Unwrap

Berlangganan untuk progress tugas sebagai Server-Sent Events. Setiap acara message membawa sebuah objek Tugas UV Unwrap; aliran akan ditutup setelah tugas mencapai SUCCEEDED, FAILED, atau CANCELED.

Gunakan ini sebagai pengganti polling GET /openapi/v1/uv-unwrap/:id untuk latensi yang lebih rendah pada penyelesaian.

Permintaan

GET
/openapi/v1/uv-unwrap/:id/stream
curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-N

Objek Tugas UV Unwrap

  • Name
    id
    Type
    string
    Description

    Pengenal unik untuk tugas.

  • Name
    type
    Type
    string
    Description

    Selalu uv-unwrap.

  • Name
    model_urls
    Type
    object
    Description

    URL unduhan yang telah ditandatangani sebelumnya untuk model putih UV yang dihasilkan. UV Unwrap selalu mengembalikan satu entri glb — keluaran mempertahankan geometri input, mengganti dengan koordinat UV baru, dan menggunakan material abu-abu default sebagai pengganti tekstur.

  • Name
    thumbnail_url
    Type
    string
    Description

    URL yang telah ditandatangani sebelumnya ke pratinjau PNG dari model putih UV.

  • Name
    progress
    Type
    integer
    Description

    Progress tugas, dari 0 hingga 100.

  • Name
    status
    Type
    string
    Description

    Salah satu dari PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Jumlah tugas yang antre sebelum tugas ini. Ada saat status adalah PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

    Stempel waktu pembuatan tugas, dalam milidetik.

  • Name
    started_at
    Type
    timestamp
    Description

    Stempel waktu saat pemrosesan dimulai, dalam milidetik. 0 hingga dimulai.

  • Name
    finished_at
    Type
    timestamp
    Description

    Stempel waktu penyelesaian, dalam milidetik. 0 hingga selesai.

  • Name
    expires_at
    Type
    timestamp
    Description

    Stempel waktu setelah URL unduhan yang ditandatangani kedaluwarsa, dalam milidetik.

  • Name
    task_error
    Type
    object
    Description

    Detail kesalahan untuk tugas yang gagal. Lihat Kesalahan untuk referensi lengkap objek task_error.

  • Name
    consumed_credits
    Type
    integer
    Description

    Kredit yang dikonsumsi oleh tugas ini. Mengembalikan 0 untuk tugas FAILED (kredit dikembalikan pada kegagalan). UV Unwrap mengenakan biaya 5 kredit pada keberhasilan.

Contoh Objek Tugas UV Unwrap

{
  "id": "019361c6-9b34-7b23-bef2-d0107c4d92e2",
  "type": "uv-unwrap",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019361c6-9b34-7b23-bef2-d0107c4d92e2/output/model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019361c6-9b34-7b23-bef2-d0107c4d92e2/output/preview.png?Expires=***",
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1716579120000,
  "started_at": 1716579122000,
  "finished_at": 1716579180000,
  "expires_at": 1716665580000,
  "task_error": {
    "message": ""
  },
  "consumed_credits": 5
}