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

UV Unwrap API

Hasilkan UV Unwrap untuk model 3D yang sudah ada. Jalankan ini sebelum Anda memberi tekstur pada model, atau ketika alat seperti Blender, Substance Painter, atau Unreal memerlukan tata letak UV yang bersih dan tidak tumpang tindih.

Hasilnya adalah model putih UV. Model ini memiliki bentuk yang sama dengan input, koordinat UV baru, dan tanpa tekstur yang sebenarnya. Model ini menyertakan material placeholder abu-abu 2×2 agar slot material glTF tetap valid, dan alat standar akan memperlakukannya sebagai tidak bertekstur.

UV Unwrap mendukung mesh hingga 40.000 wajah (face). Model yang lebih besar akan mengembalikan 400. Untuk mengurangi jumlah wajah, jalankan Remesh terlebih dahulu.

Meshy melakukan triangulasi pada mesh quad dan n-gon selama pembuatan UV, sehingga hasilnya selalu berupa mesh segitiga.

POST/openapi/v1/uv-unwrap

Membuat tugas UV Unwrap

Membuat tugas UV Unwrap.

Tugas berjalan di latar belakang. Untuk mengetahui berapa lama biasanya sebuah tugas berlangsung, lihat Waktu pemrosesan.

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

Parameter

  • Name
    input_task_id
    Type
    string
    Wajib
    Description

    Wajib diisi kecuali Anda mengirim model_url. ID dari tugas Meshy API yang output GLB-nya ingin Anda unwrap, misalnya tugas Gambar ke 3D, Teks ke 3D, atau Remesh. Tugas tersebut harus memiliki status SUCCEEDED dan telah menghasilkan file GLB.

    Mesh dapat memiliki paling banyak 40.000 face. Mesh dengan jumlah lebih banyak akan mengembalikan 400. Untuk mengurangi jumlah face, jalankan Remesh terlebih dahulu.

  • Name
    model_url
    Type
    string
    Wajib
    Description

    Wajib diisi kecuali Anda mengirim input_task_id. Model yang akan di-unwrap, berupa URL publik atau data URI. Jika Anda mengirim keduanya, Meshy menggunakan input_task_id.

    Model harus berupa file .glb. Untuk meng-unwrap format lain, konversikan terlebih dahulu ke GLB menggunakan Convert API.

    File dapat berukuran paling besar 400 MB jika berasal dari URL http atau https, atau 100 MB jika berupa data URI. Untuk data URI, gunakan MIME type application/octet-stream. GLB di atas 100 MB tidak boleh menggunakan kompresi Draco.

    Batas 40.000 face yang sama berlaku seperti pada input_task_id. Mesh dengan jumlah lebih banyak akan mengembalikan 400, jadi jalankan Remesh terlebih dahulu.

Hasil yang Dikembalikan

Field result pada respons berisi ID dari tugas UV Unwrap yang baru.

Mode kegagalan

  • Name
    400 - Bad Request
    Description

    Permintaan tidak dapat dijalankan. Pesan kesalahan menunjukkan masalah apa yang ditemukan. Contohnya:

    • Parameter hilang: Baik input_task_id maupun model_url tidak dikirim.
    • Tugas input tidak valid: input_task_id bukan tugas API yang berhasil dengan hasil GLB.
    • Jumlah face melebihi batas: Mesh memiliki jumlah face lebih banyak dari yang diizinkan UV Unwrap. Jalankan Remesh terlebih dahulu.
    • Format model tidak valid: File model_url memiliki ekstensi yang tidak didukung.
    • URL tidak dapat diakses: Meshy tidak dapat mengunduh file model_url.
    • File model terlalu besar: File model_url berukuran di atas 400 MB jika berasal dari URL http atau https, atau di atas 100 MB jika berupa data URI.
    • Terlalu banyak face: File model_url berukuran di atas 100 MB dan memiliki lebih dari 10.000.000 face. Kurangi jumlah face, lalu kirim ulang file tersebut.
    • File model tidak dapat dibaca: File model_url berukuran di atas 100 MB, dan Meshy tidak dapat membaca headernya. Misalnya, file tersebut adalah GLB terkompresi Draco.
    • Header model terlalu kompleks: File model_url berukuran di atas 100 MB, dan headernya memiliki terlalu banyak mesh, node, atau record untuk diperiksa. Kurangi jumlah objek dalam file tersebut, lalu kirim ulang.

    Perbaiki permintaan, lalu kirim ulang. Lihat Kesalahan.

  • Name
    401 - Unauthorized
    Description

    Kunci API tidak ada atau tidak valid. Periksa header Authorization.

  • Name
    402 - Payment Required
    Description

    Contohnya:

    • Kredit tidak cukup: Akun tidak memiliki cukup kredit untuk tugas ini, atau akun telah mencapai batas kredit. Tugas UV Unwrap memerlukan biaya 5 kredit. Periksa saldo kredit Anda, lalu coba lagi.
    • Paket gratis: Membuat tugas memerlukan paket berbayar. Tingkatkan paket Anda di pengaturan langganan, lalu coba lagi.
  • Name
    403 - Forbidden
    Description

    input_task_id adalah model bas-relief, yang tidak dapat di-unwrap oleh endpoint ini. Pesannya adalah This model type does not support this operation. Kirim model yang berbeda.

  • Name
    404 - Not Found
    Description

    input_task_id tidak cocok dengan tugas Anda yang mana pun. Periksa ID tugas, lalu kirim ulang permintaan.

  • Name
    429 - Too Many Requests
    Description

    Anda melebihi batas laju Anda. Tunggu, lalu coba lagi. Lihat Batas laju.

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

Dapatkan task UV Unwrap

Mengembalikan status terkini dari sebuah task UV Unwrap berdasarkan ID-nya.

Request

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

Untuk contoh respons, lihat contoh objek task UV Unwrap.

Returns

Objek task UV Unwrap.

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

Menghapus Tugas UV Unwrap

Menghapus secara permanen sebuah tugas UV Unwrap, termasuk hasilnya. Anda tidak dapat membatalkan penghapusan.

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

Status tugas

Menghapus tugas PENDING akan mengembalikan kredit yang digunakan saat Anda membuatnya.

Tugas IN_PROGRESS tidak dapat dihapus. Permintaan akan mengembalikan 409 Conflict, dan tugas tersebut tetap berjalan. Meshy tidak mengembalikan kredit untuk tugas yang sudah dimulai, jadi menghapusnya akan membuat Anda kehilangan kredit sekaligus hasilnya. Tunggu hingga tugas mencapai status SUCCEEDED, FAILED, atau CANCELED, baru kemudian hapus.

Menghapus tugas dengan status akhir (SUCCEEDED, FAILED, atau CANCELED) tidak akan mengembalikan kreditnya.

GET/openapi/v1/uv-unwrap

Mendapatkan Daftar Tugas UV Unwrap

Mengembalikan daftar bertahap (paginated) dari tugas-tugas UV Unwrap Anda, yang terbaru terlebih dahulu. Untuk menjelajahi daftar tersebut, gunakan page_num dan page_size.

Request

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

Men-streaming pembaruan tugas UV Unwrap sebagai Server-Sent Events (SSE). Setiap event message membawa sebuah objek tugas UV Unwrap. Stream akan ditutup ketika tugas mencapai status SUCCEEDED, FAILED, atau CANCELED.

Untuk mengetahui lebih cepat kapan tugas selesai, gunakan endpoint ini daripada melakukan polling pada GET /openapi/v1/uv-unwrap/:id.

Request

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

Objek tugas UV Unwrap menjelaskan satu proses UV unwrap dari sebuah model 3D. Objek ini menyimpan status, progress, dan file model saat tugas berhasil.

Example UV Unwrap Task Object

{
  "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
}
  • Name
    id
    Type
    string
    Description

    ID tugas. Perlakukan sebagai string buram, dan jangan bergantung pada formatnya.

  • Name
    type
    Type
    string
    Description

    Jenis tugas, selalu uv-unwrap.

  • Name
    model_urls
    Type
    object
    Description

    URL unduhan yang ditandatangani untuk model putih UV. UV Unwrap selalu mengembalikan satu kunci glb. Model ini mempertahankan geometri input, memiliki koordinat UV yang baru, dan menggunakan material abu-abu default alih-alih tekstur.

  • Name
    thumbnail_url
    Type
    string
    Description

    URL unduhan yang ditandatangani untuk gambar pratinjau PNG dari model putih UV.

  • Name
    progress
    Type
    integer
    Description

    Seberapa banyak tugas telah selesai, dalam bentuk persentase dari 0 hingga 100.

  • Name
    status
    Type
    string
    Description

    Status tugas, salah satu dari PENDING, IN_PROGRESS, SUCCEEDED, FAILED, atau CANCELED.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Jumlah tugas yang berada di depan tugas ini dalam antrean. Muncul selama tugas berstatus PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

    Waktu tugas dibuat, dalam milidetik Unix.

  • Name
    started_at
    Type
    timestamp
    Description

    Waktu tugas dimulai, dalam milidetik Unix. Nilainya 0 sampai tugas dimulai.

  • Name
    finished_at
    Type
    timestamp
    Description

    Waktu tugas selesai, dalam milidetik Unix. Nilainya 0 sampai tugas selesai.

  • Name
    expires_at
    Type
    timestamp
    Description

    Waktu URL unduhan yang ditandatangani kedaluwarsa, dalam milidetik Unix.

  • Name
    task_error
    Type
    object
    Description

    Detail kesalahan saat tugas gagal. Lihat Kesalahan.

  • Name
    consumed_credits
    Type
    integer
    Description

    Jumlah kredit yang digunakan oleh tugas ini. Tugas UV Unwrap yang berhasil membutuhkan 5 kredit. Nilainya 0 untuk tugas FAILED, karena Meshy mengembalikan kredit ketika tugas gagal.