UV Unwrap API

Awtomatikong bumubuo ang UV Unwrap API ng mataas na kalidad na UV unwrap para sa isang umiiral na 3D model. Gamitin ito bilang paunang hakbang bago maglagay ng texture — o anumang oras na kailangan mo ng malinis at hindi nagsasapawang UV layout para sa mga downstream tool (Blender, Substance Painter, Unreal).

Ang output ay isang "UV white model" — kapareho ng hugis ng input ngunit may ganap na bagong UV coordinates at walang tunay na texture (may kasamang 2×2 na grey placeholder material upang manatiling valid ang glTF material slot; itinuturing ito ng mga standard na tool bilang walang texture).

Mga Limitasyon. Kasalukuyang sinusuportahan ng Auto UV ang mga mesh na hanggang 40,000 face — tinatanggihan ang mas malalaking model gamit ang 400; patakbuhin muna ang Remesh upang bawasan ang polycount. Ang mga quad at n-gon mesh ay ginagawang triangulated habang ginagawa ang UV, kaya ang output ay palaging triangle mesh.

POST/openapi/v1/uv-unwrap

Gumawa ng UV Unwrap Task

Gumagawa ang endpoint na ito ng bagong UV Unwrap task.

Mga Parameter

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

  • Name
    input_task_id
    Type
    string
    Kinakailangan
    Description

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

    Kung lumampas ang source mesh sa limitasyong 40,000 faces, tatanggihan ang request na may 400 at dapat mong patakbuhin muna ang Remesh para mapababa ang polycount.

  • Name
    model_url
    Type
    string
    Kinakailangan
    Description

    Magbigay ng 3D model nang direkta sa pamamagitan ng publicly accessible URL o data URI. Tanging .glb lang ang sinusuportahan — binabasa ng API ang glTF binary at hindi nito pina-parse ang ibang format. Para i-UV-unwrap ang model sa ibang format (.fbx, .obj, .stl, .gltf), i-convert muna ito sa .glb sa pamamagitan ng I-convert API, pagkatapos ay ipasa rito ang resultang task ID bilang input_task_id o ang GLB output URL nito.

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

    Nalalapat din ang parehong limitasyong 40,000-face tulad ng para sa input_task_id: ang sobrang laking mga mesh ay tatanggihan na may 400 — patakbuhin muna ang Remesh.

Mga Ibinabalik

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

Mga Failure Mode

  • Name
    400 - Bad Request
    Description

    Hindi katanggap-tanggap ang request. Mga karaniwang sanhi:

    • Nawawalang parameter: Dapat ibigay ang alinman sa input_task_id o model_url.
    • Invalid na input task: Dapat tumukoy ang input_task_id sa isang matagumpay na task na may GLB result.
    • Lumampas sa face count: Mas marami ang faces ng source mesh kaysa sa limitasyon ng UV Unwrap. Patakbuhin muna ang Remesh.
    • Invalid na model format: Tumuturo ang model_url sa isang file na may hindi sinusuportahang extension.
    • Hindi maabot na URL: Hindi ma-download ang model_url.
  • Name
    401 - Unauthorized
    Description

    Nabigo ang authentication. Pakisuri 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 call.

  • Name
    404 - Not Found
    Description

    Hindi naka-enable ang feature para sa iyong account. Ang UV Unwrap ay nililimitahan ng Statsig flag habang 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

Kinukuha ng endpoint na ito ang kasalukuyang estado ng isang UV Unwrap task ayon sa 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 halimbawang task object sa ibaba.

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

I-delete ang UV Unwrap Task

Permanenteng i-delete ang isang UV Unwrap task. Ang task at mga output nito ay magiging 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

Ilista ang mga UV Unwrap Task

Nagbabalik ng naka-pagination na listahan ng mga UV Unwrap task ng caller, 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 gawain bilang Server-Sent Events. Bawat event na message ay nagdadala ng isang object ng UV Unwrap Task; magsasara ang stream kapag naabot ng gawain ang SUCCEEDED, FAILED, o CANCELED.

Gamitin ito sa halip na paulit-ulit na pag-poll 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 Object ng Gawain ng UV Unwrap

  • Name
    id
    Type
    string
    Description

    Natatanging identifier para sa gawain.

  • Name
    type
    Type
    string
    Description

    Palaging uv-unwrap.

  • Name
    model_urls
    Type
    object
    Description

    Mga paunang nalagdaang download URL para sa nabuong UV white model. Palaging nagbabalik ang UV Unwrap ng iisang glb entry — pinapanatili ng output ang input heometriya, pinapalitan ng mga bagong UV coordinates, at gumagamit ng default na gray na material kapalit ng anumang texture.

  • Name
    thumbnail_url
    Type
    string
    Description

    Paunang nalagdaang URL sa isang PNG preview ng UV white model.

  • Name
    progress
    Type
    integer
    Description

    Progress 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 gawaing nakapila bago ang isang ito. Naroroon habang ang status ay PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

    Timestamp ng paggawa 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 nito mag-e-expire ang mga nalagdaang download URL, sa milliseconds.

  • Name
    task_error
    Type
    object
    Description

    Mga detalye ng error para sa mga nabigong gawain. Tingnan ang Errors para sa buong sanggunian ng object na task_error.

  • Name
    consumed_credits
    Type
    integer
    Description

    credits na nakonsumo ng gawaing ito. Nagbabalik ng 0 para sa mga gawaing FAILED (ibinabalik ang credits kapag nabigo). Naniningil ang UV Unwrap 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
}