API UV Unwrap

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

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

Batasan. UV automatik kini menyokong jejaring sehingga 40,000 muka — model yang lebih besar ditolak dengan 400; jalankan Remesh dahulu untuk mengurangkan bilangan poligon. Jejaring (mesh) quad dan n-gon ditriangulasikan semasa penjanaan UV, jadi output sentiasa merupakan jejaring segi tiga.

POST/openapi/v1/uv-unwrap

Cipta Tugas UV Unwrap

Endpoint ini mencipta tugas UV Unwrap baharu.

Parameter

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

Name
input_task_id
Type
string
Diperlukan
Description
ID bagi tugas Meshy API yang telah selesai yang output GLBnya ingin anda UV Unwrap (contohnya hasil Imej ke 3D, Teks ke 3D, atau Remesh). Tugas sumber mesti mempunyai status SUCCEEDED dan telah menghasilkan fail GLB.
Jika jejaring sumber melebihi had kiraan muka sebanyak 40,000 muka, permintaan akan ditolak dengan 400 dan anda harus menjalankan Remesh dahulu untuk menurunkan bilangan poligon.

Name
model_url
Type
string
Diperlukan
Description
Sediakan model 3D secara langsung melalui URL yang boleh diakses secara umum atau Data URI. Hanya .glb disokong — API membaca binari glTF dan tidak menghuraikan format lain. Untuk UV Unwrap model dalam format lain (.fbx, .obj, .stl, .gltf), tukarkannya kepada .glb dahulu melalui Convert API, kemudian hantar ID tugas yang terhasil sebagai input_task_id atau URL output GLBnya di sini.
Untuk Data URI, gunakan MIME type application/octet-stream.
Had 40,000 muka yang sama terpakai seperti untuk input_task_id: jejaring yang terlalu besar ditolak dengan 400 — jalankan Remesh dahulu.

Mengembalikan

Sifat result dalam respons mengandungi id bagi tugas UV Unwrap yang baru dicipta.

Mod Kegagalan

Name
400 - Bad Request
Description
Permintaan tidak boleh diterima. Punca lazim:
- Parameter hilang: Sama ada input_task_id atau model_url mesti diberikan.
- Tugas input tidak sah: input_task_id mesti merujuk kepada tugas yang berjaya dengan hasil GLB.
- Kiraan muka melebihi had: Jejaring (mesh) sumber mempunyai lebih banyak muka daripada had UV Unwrap. Jalankan Remesh dahulu.
- Format model tidak sah: model_url menunjuk kepada fail dengan sambungan yang tidak disokong.
- URL tidak boleh dicapai: model_url tidak dapat dimuat turun.
Name
401 - Unauthorized
Description
Pengesahan gagal. Sila semak kunci API anda.
Name
402 - Payment Required
Description
Kredit tidak mencukupi untuk melaksanakan tugas ini. UV Unwrap berharga 5 kredit bagi setiap panggilan.
Name
404 - Not Found
Description
Ciri ini tidak didayakan 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 Semula Tugas UV Unwrap

Endpoint ini mendapatkan semula keadaan semasa bagi tugas UV Unwrap mengikut 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.

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

Padam Tugas UV Unwrap

Padamkan tugas UV Unwrap secara kekal. Tugas dan outputnya menjadi tidak boleh 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

Senaraikan Tugas UV Unwrap

Mengembalikan senarai tugas UV Unwrap pemanggil yang berpenomboran halaman, yang terbaharu 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

Strim Tugas UV Unwrap

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

Gunakan ini dan bukannya melakukan polling GET /openapi/v1/uv-unwrap/:id untuk kependaman yang lebih rendah semasa 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 Tugasan UV Unwrap

Name
id
Type
string
Description
Pengecam unik untuk tugasan.
Name
type
Type
string
Description
Sentiasa uv-unwrap.
Name
model_urls
Type
object
Description
URL muat turun pratangani untuk model putih UV yang dijana. UV Unwrap sentiasa mengembalikan satu entri glb — output mengekalkan geometri input, menggantikan dengan koordinat UV baharu, dan menggunakan bahan kelabu lalai sebagai ganti sebarang tekstur.
Name
thumbnail_url
Type
string
Description
URL pratangani kepada pratonton PNG bagi model putih UV.
Name
progress
Type
integer
Description
progress tugasan, daripada 0 hingga 100.
Name
status
Type
string
Description
Salah satu daripada PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
preceding_tasks
Type
integer
Description
Bilangan tugasan yang beratur di hadapan tugasan ini. Hadir semasa status ialah PENDING.
Name
created_at
Type
timestamp
Description
Cap masa penciptaan tugasan, 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 itu URL muat turun yang ditandatangani tamat tempoh, dalam milisaat.
Name
task_error
Type
object
Description
Butiran ralat untuk tugasan yang gagal. Lihat Ralat untuk rujukan penuh objek task_error.
Name
consumed_credits
Type
integer
Description
Kredit yang digunakan oleh tugasan ini. Mengembalikan 0 untuk tugasan FAILED (kredit dipulangkan apabila gagal). UV Unwrap mengenakan caj 5 kredit apabila berjaya.

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
}