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

Gumawa ng UV Unwrap Task

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

Mga Parameter

Eksaktong isa sa input_task_id o model_url ang kinakailangan. Kung parehong ibinigay, ang input_task_id ang may prayoridad.

  • Name
    input_task_id
    Type
    string
    Kinakailangan
    Description

    Ang ID ng isang natapos na Meshy API task na ang GLB output ay nais mong UV-unwrap (halimbawa, isang Image to 3D, Text to 3D, o Remesh na resulta). Ang source task ay dapat may status na SUCCEEDED at nakagawa ng GLB file.

    Kung ang source mesh ay lumampas sa face-count ceiling na 40,000 faces, ang request ay tatanggihan gamit ang 400 at dapat mong patakbuhin ang Remesh muna upang pababain ang polycount.

  • Name
    model_url
    Type
    string
    Kinakailangan
    Description

    Magbigay ng 3D model direkta sa pamamagitan ng isang pampublikong accessible na URL o data URI. Tanging .glb lamang ang sinusuportahan — ang API ay nagbabasa ng glTF binary at hindi nagpa-parse ng ibang mga format. Upang UV-unwrap ang isang model sa ibang format (.fbx, .obj, .stl, .gltf), i-convert ito sa .glb muna sa pamamagitan ng Convert API, pagkatapos ay ipasa ang nagresultang task ID bilang input_task_id o ang GLB output URL nito dito.

    Para sa Data URIs, gamitin ang MIME type na application/octet-stream.

    Ang parehong 40,000-face ceiling ay nalalapat tulad ng sa input_task_id: ang mga oversized na meshes ay tinatanggihan gamit ang 400 — patakbuhin muna ang Remesh.

Mga Ibinabalik

Ang result na property ng tugon ay naglalaman ng id ng bagong likhang UV Unwrap task.

Mga Mode ng Pagkabigo

  • Name
    400 - Bad Request
    Description

    Ang request ay hindi katanggap-tanggap. Karaniwang mga sanhi:

    • Nawawalang parameter: Dapat ibigay 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 GLB na resulta.
    • Lumampas sa bilang ng mukha: Ang source mesh ay may higit pang mga mukha kaysa sa UV Unwrap ceiling. Patakbuhin muna ang Remesh.
    • Hindi wastong format ng model: Ang model_url ay tumutukoy sa isang file na may hindi suportadong extension.
    • Hindi maabot na URL: Ang model_url ay hindi ma-download.
  • Name
    401 - Unauthorized
    Description

    Nabigo ang authentication. Pakisuri ang iyong API key.

  • Name
    402 - Payment Required
    Description

    Hindi sapat ang credits upang isagawa ang task na ito. Ang UV Unwrap ay nagkakahalaga ng 5 credits bawat tawag.

  • Name
    404 - Not Found
    Description

    Ang tampok ay hindi pinagana para sa iyong account. Ang UV Unwrap ay pinapagana ng isang Statsig flag sa panahon ng rollout — makipag-ugnayan sa Meshy support kung kailangan mo ng access.

  • Name
    429 - Too Many Requests
    Description

    Lumampas ka sa 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 na Tungkulin

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

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
}