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

Membuat Tugas UV Unwrap

Endpoint ini membuat tugas UV Unwrap baru.

Parameter

Tepat satu dari input_task_id atau model_url diperlukan. Jika keduanya disediakan, input_task_id memiliki 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 wajah 40.000 wajah, permintaan akan ditolak dengan 400 dan Anda harus menjalankan Remesh terlebih dahulu untuk mengurangi jumlah poligon.

  • Name
    model_url
    Type
    string
    Wajib
    Description

    Sediakan model 3D secara langsung melalui URL yang dapat diakses publik atau Data URI. Hanya .glb yang didukung — API membaca glTF biner dan tidak memproses format lain. Untuk UV-unwrap model dalam format lain (.fbx, .obj, .stl, .gltf), konversikan terlebih dahulu ke .glb melalui Convert API, kemudian berikan 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 wajah yang sama berlaku seperti untuk input_task_id: mesh yang terlalu besar akan ditolak dengan 400 — jalankan Remesh terlebih dahulu.

Pengembalian

Properti result dari 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 disediakan.
    • Tugas input tidak valid: input_task_id harus merujuk pada tugas yang berhasil dengan hasil GLB.
    • Jumlah wajah terlampaui: Mesh sumber memiliki lebih banyak wajah 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. Silakan periksa kunci API Anda.

  • Name
    402 - Payment Required
    Description

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

  • Name
    404 - Not Found
    Description

    Fitur 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 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 secara permanen tugas UV Unwrap. Tugas dan hasilnya menjadi tidak dapat diakses.

Permintaan

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
}