API UV Unwrap

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

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

Batasan. UV Otomatis saat ini mendukung mesh hingga 40.000 face — 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 output selalu berupa mesh segitiga.

POST/openapi/v1/uv-unwrap

Buat Tugas UV Unwrap

Endpoint ini membuat tugas UV Unwrap baru.

Parameter

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

  • Name
    input_task_id
    Type
    string
    Wajib
    Description

    ID dari tugas Meshy API yang telah selesai yang 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 jumlah face 40.000 face, 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 publik atau Data URI. Hanya .glb yang didukung — API membaca biner glTF dan tidak mengurai format lain. Untuk melakukan UV-unwrap model dalam format lain (.fbx, .obj, .stl, .gltf), konversikan ke .glb terlebih dahulu melalui API Konversi, lalu teruskan ID tugas yang dihasilkan sebagai input_task_id atau URL output GLB-nya di sini.

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

    Batas 40.000 face yang sama berlaku seperti untuk input_task_id: mesh yang terlalu besar ditolak dengan 400 — jalankan Remesh terlebih dahulu.

Mengembalikan

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

Mode Kegagalan

  • Name
    400 - Bad Request
    Description

    Permintaan tidak dapat diterima. Penyebab umum:

    • Parameter tidak ada: Salah satu dari input_task_id atau model_url harus diberikan.
    • Tugas input tidak valid: input_task_id harus merujuk ke tugas yang berhasil dengan hasil GLB.
    • Jumlah face terlampaui: Mesh sumber memiliki lebih banyak face daripada batas UV Unwrap. Jalankan Remesh terlebih dahulu.
    • Format model tidak valid: model_url mengarah ke file dengan ekstensi yang tidak didukung.
    • URL tidak dapat dijangkau: model_url tidak dapat diunduh.
  • Name
    401 - Unauthorized
    Description

    Autentikasi gagal. Harap periksa kunci API Anda.

  • Name
    402 - Payment Required
    Description

    Kredit tidak mencukupi untuk melakukan tugas ini. UV Unwrap membutuhkan 5 kredit per panggilan.

  • Name
    404 - Not Found
    Description

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

  • Name
    429 - Too Many Requests
    Description

    Anda telah melebihi 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 objek Tugas UV Unwrap.

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

Lihat contoh objek tugas di bawah ini.

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

Hapus Tugas UV Unwrap

Hapus tugas UV Unwrap secara permanen. Tugas dan output-nya menjadi tidak dapat diakses.

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 tugas UV Unwrap milik pemanggil yang dipaginasi, yang terbaru terlebih dahulu. Paginasi standar melalui 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

Berlangganan ke progress tugas sebagai Server-Sent Events. Setiap event message membawa objek Tugas UV Unwrap; stream ditutup setelah tugas mencapai SUCCEEDED, FAILED, atau CANCELED.

Gunakan ini alih-alih melakukan polling GET /openapi/v1/uv-unwrap/:id untuk latensi yang lebih rendah saat penyelesaian.

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

  • Name
    id
    Type
    string
    Description

    Pengidentifikasi unik untuk tugas.

  • Name
    type
    Type
    string
    Description

    Selalu uv-unwrap.

  • Name
    model_urls
    Type
    object
    Description

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

  • Name
    thumbnail_url
    Type
    string
    Description

    URL bertanda tangan 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 mengantre di depan 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 bertanda tangan kedaluwarsa, dalam milidetik.

  • Name
    task_error
    Type
    object
    Description

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

  • Name
    consumed_credits
    Type
    integer
    Description

    Kredit yang dikonsumsi oleh tugas ini. Mengembalikan 0 untuk tugas FAILED (kredit dikembalikan saat terjadi kegagalan). UV Unwrap mengenakan 5 kredit saat 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
}