lowpoly akan dihentikan pada 30 Okt 2026. Tukar model sebelum tarikh-tarikh ini untuk mengelakkan ralat permintaan.

API UV Unwrap

API UV Unwrap secara automatik menjana UV unwrap berkualiti tinggi untuk model 3D sedia ada. Gunakannya sebagai langkah prasyarat sebelum tekstur — atau bila-bila masa anda memerlukan susun atur UV yang bersih dan tidak bertindih untuk alat hiliran (Blender, Substance Painter, Unreal).

Outputnya adalah "model putih UV" — bentuk yang sama seperti input tetapi dengan koordinat UV yang baru dan tiada tekstur sebenar (bahan pemegang tempat kelabu 2×2 disertakan untuk memastikan slot bahan glTF sah; alat standard menganggap ini sebagai tidak bertekstur).

Keterbatasan. Auto UV kini menyokong jejaring sehingga 40,000 muka — model yang lebih besar ditolak dengan 400; jalankan Remesh terlebih dahulu untuk mengurangkan bilangan poligon. Jejaring quad dan n-gon ditriangulasi semasa penjanaan UV, jadi outputnya sentiasa jejaring segitiga.

POST/openapi/v1/uv-unwrap

Create an UV Unwrap Task

Endpoint ini mencipta tugasan UV Unwrap yang baharu.

Tugasan ini berjalan di latar belakang. Untuk tempoh masa yang biasanya diambil, lihat Processing Times.

Parameter

Tepat satu daripada input_task_id atau model_url diperlukan. Jika kedua-duanya diberikan, input_task_id diutamakan.

  • Name
    input_task_id
    Type
    string
    Diperlukan
    Description

    ID bagi tugasan Meshy API yang telah selesai yang output GLB-nya ingin anda UV-unwrap (contohnya hasil Imej ke 3D, Teks ke 3D, atau Remesh). Tugasan sumber mestilah mempunyai status SUCCEEDED dan telah menghasilkan fail GLB.

    Jika jejaring sumber melebihi had siling 40,000 muka, permintaan akan ditolak dengan 400 dan anda perlu menjalankan Remesh terlebih dahulu untuk mengurangkan bilangan poligon.

  • Name
    model_url
    Type
    string
    Diperlukan
    Description

    Sediakan model 3D secara terus melalui URL yang boleh diakses secara awam atau Data URI. Hanya .glb disokong — API ini membaca glTF binary dan tidak menghurai format lain. Untuk melakukan UV-unwrap pada model dalam format lain (.fbx, .obj, .stl, .gltf), tukar ia kepada .glb terlebih dahulu melalui Convert API, kemudian hantar ID tugasan yang terhasil sebagai input_task_id atau URL output GLB-nya di sini.

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

    Saiz fail maksimum: 400 MB untuk URL http atau https, 100 MB untuk URI data:. GLB yang melebihi 100 MB tidak boleh menggunakan mampatan Draco.

    Had siling 40,000 muka yang sama terpakai seperti bagi input_task_id: jejaring yang terlalu besar akan ditolak dengan 400 — jalankan Remesh terlebih dahulu.

Nilai Pulangan

Sifat result dalam respons mengandungi id bagi tugasan UV Unwrap yang baharu dicipta.

Mod Kegagalan

  • Name
    400 - Bad Request
    Description

    Permintaan tidak dapat diterima. Punca biasa:

    • Parameter hilang: Sama ada input_task_id atau model_url mesti diberikan.
    • Tugasan input tidak sah: input_task_id mesti merujuk kepada tugasan yang berjaya dengan hasil GLB.
    • Bilangan muka melebihi had: Jejaring sumber mempunyai lebih banyak muka daripada had siling UV Unwrap. Jalankan Remesh terlebih dahulu.
    • Format model tidak sah: model_url menunjuk kepada fail dengan sambungan yang tidak disokong.
    • URL tidak dapat dicapai: model_url tidak dapat dimuat turun.
    • Fail model terlalu besar: Fail model_url melebihi 400 MB (URL http atau https) atau 100 MB (URI data:).
    • Terlalu banyak muka: Fail model_url melebihi 100 MB dan mempunyai lebih daripada 10,000,000 muka. Kurangkan bilangan muka, kemudian hantar semula fail tersebut.
    • Fail model tidak boleh dibaca: Fail model_url melebihi 100 MB dan pengepalanya tidak dapat dibaca, contohnya GLB yang dimampatkan dengan Draco.
    • Pengepala model terlalu kompleks: Fail model_url melebihi 100 MB dan pengepalanya mempunyai terlalu banyak jejaring, nod atau rekod untuk disemak. Kurangkan bilangan objek dalam fail, kemudian hantar semula.
  • Name
    401 - Unauthorized
    Description

    Pengesahan gagal. Sila semak kunci API anda.

  • Name
    402 - Payment Required
    Description

    Kredit tidak mencukupi untuk melaksanakan tugasan ini. UV Unwrap berharga 5 kredit setiap panggilan.

  • Name
    404 - Not Found
    Description

    Ciri ini tidak diaktifkan untuk akaun anda. UV Unwrap dikawal oleh bendera Statsig semasa pelancaran berperingkat — hubungi sokongan Meshy jika anda memerlukan akses.

  • Name
    429 - Too Many Requests
    Description

    Anda telah melebihi had kadar 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

Dapatkan Tugas UV Unwrap

Endpoint ini mendapatkan keadaan semasa tugas UV Unwrap melalui ID.

Mengembalikan

Mengembalikan 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.

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

Padam Tugasan UV Unwrap

Padamkan tugasan UV Unwrap secara kekal. Tugasan dan outputnya menjadi tidak boleh diakses.

Tugasan yang masih PENDING akan dipadam dan kredit yang digunakan pada masa penciptaan akan dikembalikan.

Tugasan yang sudah IN_PROGRESS tidak boleh dipadam: permintaan itu ditolak dengan 409 Conflict dan tugasan itu terus berjalan. Kredit untuk tugasan yang telah pun dimulakan oleh worker tidak boleh dikembalikan, jadi memadamkannya semasa ia sedang berjalan akan menyebabkan anda kehilangan kredit dan juga hasilnya. Tunggu sehingga ia mencapai SUCCEEDED, FAILED atau CANCELED, kemudian padamkannya.

Tugasan dalam keadaan terminal (SUCCEEDED, FAILED atau CANCELED) akan dipadam tanpa bayaran balik.

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

Senarai Tugas UV Unwrap

Mengembalikan senarai penomboran halaman tugas UV Unwrap pemanggil, yang terbaru dahulu. Penomboran halaman standard 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

Strimkan Tugas UV Unwrap

Langgan kemajuan tugas sebagai Server-Sent Events. Setiap acara message membawa objek Tugas UV Unwrap; strim akan ditutup apabila tugas mencapai SUCCEEDED, FAILED, atau CANCELED.

Gunakan ini sebagai ganti pengundian 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 ini.

  • Name
    type
    Type
    string
    Description

    Sentiasa uv-unwrap.

  • Name
    model_urls
    Type
    object
    Description

    URL muat turun pra-tandatangan untuk model putih UV yang dihasilkan. UV Unwrap sentiasa mengembalikan satu entri glb — output mengekalkan geometri input, menukar kepada koordinat UV baru, dan menggunakan bahan kelabu lalai menggantikan sebarang tekstur.

  • Name
    thumbnail_url
    Type
    string
    Description

    URL pra-tandatangan kepada pratonton PNG model putih UV.

  • Name
    progress
    Type
    integer
    Description

    Progress tugas, dari 0 hingga 100.

  • Name
    status
    Type
    string
    Description

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

  • Name
    preceding_tasks
    Type
    integer
    Description

    Bilangan tugas yang beratur sebelum tugas ini. Hadir semasa status adalah PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

    Cap masa penciptaan tugas, dalam milisaat.

  • Name
    started_at
    Type
    timestamp
    Description

    Cap masa apabila pemprosesan bermula, dalam milisaat. 0 sehingga bermula.

  • Name
    finished_at
    Type
    timestamp
    Description

    Cap masa penyelesaian, dalam milisaat. 0 sehingga selesai.

  • Name
    expires_at
    Type
    timestamp
    Description

    Cap masa selepas URL muat turun yang ditandatangani tamat tempoh, dalam milisaat.

  • Name
    task_error
    Type
    object
    Description

    Butiran ralat untuk tugas yang gagal. Lihat Ralat untuk rujukan penuh objek task_error.

  • Name
    consumed_credits
    Type
    integer
    Description

    Kredit yang digunakan oleh tugas ini. Mengembalikan 0 untuk tugas FAILED (kredit dikembalikan jika gagal). UV Unwrap mengenakan caj 5 kredit jika berjaya.

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
}