UV Unwrap API

Ang UV Unwrap API ay awtomatikong bumubuo ng mataas na kalidad na UV unwrap para sa isang umiiral na 3D model. Gamitin ito bilang paunang hakbang bago ang pagte-texture — o anumang oras na kailangan mo ng malinis, hindi nag-o-overlap na UV layout para sa mga kasunod na tool (Blender, Substance Painter, Unreal).

Ang output ay isang "UV white model" — kaparehong hugis ng input ngunit may bagong UV coordinates at walang tunay na texture (isang 2×2 grey placeholder material ang kasama upang mapanatili ang glTF material slot na valid; itinuturing ito ng mga karaniwang tool bilang hindi naka-texture).

Mga Limitasyon. Ang Auto UV ay kasalukuyang sumusuporta sa mga mesh na hanggang 40,000 faces — ang mas malalaking modelo ay tinatanggihan na may 400; patakbuhin muna ang Remesh upang mabawasan ang polycount. Ang mga quad at n-gon mesh ay triangulated sa panahon ng UV generation, kaya't ang output ay palaging isang triangle mesh.

POST/openapi/v1/uv-unwrap

Create an UV Unwrap Task

Ang endpoint na ito ay gumagawa ng bagong UV Unwrap task.

Ang task ay tumatakbo sa background. Para malaman kung gaano karaming oras ito karaniwang tumatagal, tingnan ang Processing Times.

Mga Parameter

Kailangan ang eksaktong isa sa input_task_id o model_url. Kung parehong ibinigay, ang input_task_id ang mauuna.

Name
input_task_id
Type
string
Kinakailangan
Description
Ang ID ng isang nakumpletong Meshy API task na ang GLB output ay nais mong i-UV-unwrap (halimbawa, resulta ng Image to 3D, Text to 3D, o Remesh). Ang source task ay dapat may status na SUCCEEDED at nakagawa ng GLB file.
Kung lumampas ang source mesh sa face-count ceiling na 40,000 faces, tatanggihan ang request na may 400 at dapat mo munang patakbuhin ang Remesh para ibaba ang polycount.

Name
model_url
Type
string
Kinakailangan
Description
Magbigay ng 3D model nang direkta sa pamamagitan ng publicly accessible URL o data URI. .glb lamang ang suportado — binabasa ng API ang glTF binary at hindi pini-parse ang ibang format. Para i-UV-unwrap ang isang model sa ibang format (.fbx, .obj, .stl, .gltf), i-convert muna ito sa .glb sa pamamagitan ng Convert API, pagkatapos ipasa ang resultang task ID bilang input_task_id o ang GLB output URL nito dito.
Para sa Data URI, gamitin ang MIME type na application/octet-stream.
Pinakamalaking file size: 400 MB para sa http o https URL, 100 MB para sa data: URI. Ang GLB na mahigit 100 MB ay hindi dapat gumamit ng Draco compression.
Ang parehong 40,000-face ceiling ay naaangkop tulad ng sa input_task_id: ang sobrang laking mesh ay tatanggihan na may 400 — patakbuhin muna ang Remesh.

Mga Isinasauli

Ang property na result ng response ay naglalaman ng id ng bagong gawang UV Unwrap task.

Mga Mode ng Kabiguan

Name
400 - Bad Request
Description
Hindi katanggap-tanggap ang request. Karaniwang dahilan:
- Nawawalang parameter: Dapat ibigay ang alinman sa input_task_id o model_url.
- Hindi wastong input task: Ang input_task_id ay dapat tumukoy sa isang matagumpay na task na may resultang GLB.
- Lumampas ang face count: Ang source mesh ay may mas maraming faces kaysa sa UV Unwrap ceiling. Patakbuhin muna ang Remesh.
- Hindi wastong model format: Ang model_url ay tumuturo sa isang file na may hindi suportadong extension.
- Hindi maabot na URL: Hindi ma-download ang model_url.
- Sobrang laki ang model file: Ang model_url file ay lumampas sa 400 MB (http o https URL) o 100 MB (data: URI).
- Sobrang dami ng faces: Ang model_url file ay mahigit 100 MB at may mahigit 10,000,000 faces. Bawasan ang bilang ng faces, pagkatapos ipadala muli ang file.
- Hindi mabasang model file: Ang model_url file ay mahigit 100 MB at hindi mabasa ang header nito, halimbawa isang Draco-compressed GLB.
- Masyadong kumplikado ang model header: Ang model_url file ay mahigit 100 MB at ang header nito ay may napakaraming mesh, node, o record na sinusuri. Bawasan ang bilang ng mga object sa file, pagkatapos ipadala ito muli.
Name
401 - Unauthorized
Description
Nabigo ang authentication. Paki-check ang iyong API key.
Name
402 - Payment Required
Description
Hindi sapat ang credits para isagawa ang task na ito. Ang UV Unwrap ay nagkakahalaga ng 5 credits bawat tawag.
Name
404 - Not Found
Description
Hindi pinagagana ang feature na ito para sa iyong account. Ang UV Unwrap ay kontrolado ng isang Statsig flag habang ginagawa ang rollout — makipag-ugnayan sa suporta ng Meshy kung kailangan mo ng access.
Name
429 - Too Many Requests
Description
Nalampasan mo na ang iyong rate limit.

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

Kunin ang isang UV Unwrap Task

Ang endpoint na ito ay kumukuha ng kasalukuyang estado ng isang UV Unwrap task sa pamamagitan ng ID.

Ibinabalik

Ibinabalik ang isang UV Unwrap Task object.

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

Tingnan ang halimbawa ng task object sa ibaba.

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

Burahin ang isang UV Unwrap Task

Permanenteng burahin ang isang UV Unwrap task. Ang task at ang mga output nito ay magiging hindi na maa-access.

Ang isang task na PENDING pa ay bubura-hin at ang mga credits na ginamit noong oras ng paggawa nito ay isasauli.

Ang isang task na IN_PROGRESS na ay hindi maaaring burahin: ang request ay tatanggihan na may 409 Conflict at magpapatuloy pa rin ang pagtakbo ng task. Ang mga credits para sa isang task na sinimulan na ng worker ay hindi na maisasauli, kaya ang pagbura nito habang tumatakbo ay magiging sanhi ng pagkawala ng iyong credits at ng resulta. Hintayin munang umabot ito sa SUCCEEDED, FAILED, o CANCELED, bago ito burahin.

Ang isang task na nasa terminal state (SUCCEEDED, FAILED, o CANCELED) ay bubura-hin nang walang refund.

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

Listahan ng mga Gawain sa UV Unwrap

Nagbabalik ng isang listahan na may pagination ng mga gawain sa UV Unwrap ng tumatawag, pinakabago muna. Karaniwang pagination sa pamamagitan ng page_num at 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

I-stream ang isang UV Unwrap Task

Mag-subscribe sa progress ng task bilang Server-Sent Events. Ang bawat message event ay nagdadala ng isang UV Unwrap Task object; ang stream ay magsasara kapag ang task ay umabot sa SUCCEEDED, FAILED, o CANCELED.

Gamitin ito sa halip na mag-polling sa GET /openapi/v1/uv-unwrap/:id para sa mas mababang latency sa pagkumpleto.

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

Ang UV Unwrap Task Object

Name
id
Type
string
Description
Natatanging pagkakakilanlan para sa gawain.
Name
type
Type
string
Description
Palaging uv-unwrap.
Name
model_urls
Type
object
Description
Pre-signed download URLs para sa nabuong UV white model. Ang UV Unwrap ay palaging nagbabalik ng isang glb na entry — pinapanatili ng output ang input na heometriya, pinapalitan ng bagong UV coordinates, at gumagamit ng default na grey material kapalit ng anumang texture.
Name
thumbnail_url
Type
string
Description
Pre-signed URL sa isang PNG preview ng UV white model.
Name
progress
Type
integer
Description
Pag-unlad ng gawain, mula 0 hanggang 100.
Name
status
Type
string
Description
Isa sa PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
preceding_tasks
Type
integer
Description
Bilang ng mga gawain na nakapila bago ito. Kasalukuyan habang ang status ay PENDING.
Name
created_at
Type
timestamp
Description
Timestamp ng paglikha ng gawain, sa milliseconds.
Name
started_at
Type
timestamp
Description
Timestamp kung kailan nagsimula ang pagproseso, sa milliseconds. 0 hanggang magsimula.
Name
finished_at
Type
timestamp
Description
Timestamp ng pagkumpleto, sa milliseconds. 0 hanggang matapos.
Name
expires_at
Type
timestamp
Description
Timestamp pagkatapos kung saan mag-e-expire ang signed download URLs, sa milliseconds.
Name
task_error
Type
object
Description
Mga detalye ng error para sa mga nabigong gawain. Tingnan ang Errors para sa buong task_error object reference.
Name
consumed_credits
Type
integer
Description
Credits na nagamit ng gawain na ito. Nagbabalik ng 0 para sa mga FAILED na gawain (ang credits ay naibabalik kapag nabigo). Ang UV Unwrap ay naniningil ng 5 credits kapag matagumpay.

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
}