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

UV Unwrap API

Jana UV Unwrap untuk model 3D yang sedia ada. Jalankannya sebelum anda memberi tekstur pada model, atau apabila alat seperti Blender, Substance Painter, atau Unreal memerlukan susun atur UV yang bersih dan tidak bertindih.

Outputnya ialah model putih UV. Ia mempunyai bentuk yang sama seperti input, koordinat UV yang baharu, dan tiada tekstur sebenar. Ia disertakan bahan placeholder kelabu 2×2 supaya slot bahan glTF kekal sah, dan alat standard menganggapnya sebagai tidak bertekstur.

UV Unwrap menyokong jejaring sehingga 40,000 permukaan (faces). Model yang lebih besar akan mengembalikan 400. Untuk mengurangkan bilangan permukaan, jalankan Remesh terlebih dahulu.

Meshy mentriangulasikan jejaring quad dan n-gon semasa penjanaan UV, jadi outputnya sentiasa merupakan jejaring segi tiga.

POST/openapi/v1/uv-unwrap

Cipta tugas UV Unwrap

Mencipta tugas UV Unwrap.

Tugas ini berjalan di latar belakang. Untuk tempoh masa yang biasanya diambil oleh sesuatu tugas, lihat Masa pemprosesan.

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

Parameter

  • Name
    input_task_id
    Type
    string
    Diperlukan
    Description

    Diperlukan kecuali anda menghantar model_url. ID tugas Meshy API yang output GLB-nya ingin anda unwrap, contohnya tugas Imej ke 3D, Teks ke 3D, atau Remesh. Tugas tersebut mesti mempunyai status SUCCEEDED dan telah menghasilkan fail GLB.

    Jejaring boleh mempunyai paling banyak 40,000 muka. Jejaring dengan lebih daripada itu akan mengembalikan 400. Untuk mengurangkan bilangan muka, jalankan Remesh terlebih dahulu.

  • Name
    model_url
    Type
    string
    Diperlukan
    Description

    Diperlukan kecuali anda menghantar input_task_id. Model untuk di-unwrap, sebagai URL awam atau Data URI. Jika anda menghantar kedua-duanya, Meshy menggunakan input_task_id.

    Model mestilah fail .glb. Untuk unwrap format lain, tukarkannya kepada GLB menggunakan Convert API terlebih dahulu.

    Fail boleh berukuran paling banyak 400 MB daripada URL http atau https, atau 100 MB sebagai Data URI. Untuk Data URI, gunakan MIME type application/octet-stream. GLB yang melebihi 100 MB tidak boleh menggunakan pemampatan Draco.

    Had 40,000 muka yang sama terpakai seperti untuk input_task_id. Jejaring dengan lebih daripada itu akan mengembalikan 400, jadi jalankan Remesh terlebih dahulu.

Pulangan

Medan result dalam respons mengandungi ID tugas UV Unwrap yang baharu.

Mod kegagalan

  • Name
    400 - Bad Request
    Description

    Permintaan tidak dapat dijalankan. Mesej ralat menyatakan masalah yang ditemui. Contohnya:

    • Parameter tiada: Tiada input_task_id mahupun model_url dihantar.
    • Tugas input tidak sah: input_task_id bukan tugas API yang berjaya dengan hasil GLB.
    • Bilangan muka melebihi had: Jejaring mempunyai lebih banyak muka daripada yang dibenarkan oleh UV Unwrap. Jalankan Remesh terlebih dahulu.
    • Format model tidak sah: Fail model_url mempunyai sambungan yang tidak disokong.
    • URL tidak dapat dicapai: Meshy tidak dapat memuat turun fail model_url.
    • Fail model terlalu besar: Fail model_url melebihi 400 MB daripada URL http atau https, atau melebihi 100 MB sebagai Data URI.
    • Terlalu banyak muka: Fail model_url melebihi 100 MB dan mempunyai lebih daripada 10,000,000 muka. Kurangkan bilangan muka, kemudian hantar fail itu semula.
    • Fail model tidak dapat dibaca: Fail model_url melebihi 100 MB, dan Meshy tidak dapat membaca headernya. Contohnya, ia adalah GLB yang dimampatkan dengan Draco.
    • Header model terlalu kompleks: Fail model_url melebihi 100 MB, dan headernya mempunyai terlalu banyak jejaring, nod, atau rekod untuk disemak. Kurangkan bilangan objek dalam fail, kemudian hantar semula.

    Betulkan permintaan, kemudian hantar semula. Lihat Ralat.

  • Name
    401 - Unauthorized
    Description

    Kunci API tiada atau tidak sah. Semak header Authorization.

  • Name
    402 - Payment Required
    Description

    Contohnya:

    • Kredit tidak mencukupi: Akaun tidak mempunyai kredit yang cukup untuk tugas ini, atau akaun telah mencapai had kredit. Tugas UV Unwrap memerlukan 5 kredit. Semak baki kredit anda, kemudian cuba semula.
    • Pelan percuma: Mencipta tugas memerlukan pelan berbayar. Naik taraf pelan anda dalam tetapan langganan anda, kemudian cuba semula.
  • Name
    403 - Forbidden
    Description

    input_task_id ialah model bas-relief, yang tidak dapat di-unwrap oleh endpoint ini. Mesejnya ialah This model type does not support this operation. Hantar model yang berbeza.

  • Name
    404 - Not Found
    Description

    input_task_id tidak sepadan dengan mana-mana tugas anda. Semak ID tugas, kemudian hantar permintaan semula.

  • Name
    429 - Too Many Requests
    Description

    Anda telah melebihi had kadar anda. Tunggu, kemudian cuba semula. Lihat Had kadar.

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

Dapatkan tugas UV Unwrap

Mengembalikan status semasa tugas UV Unwrap berdasarkan ID-nya.

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

Untuk contoh respons, lihat contoh objek tugas UV Unwrap.

Mengembalikan

Objek tugas UV Unwrap.

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

Padam tugas UV Unwrap

Memadam tugas UV Unwrap secara kekal, termasuk outputnya. Anda tidak boleh membatalkan tindakan padam ini.

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

Status tugas

Memadam tugas PENDING akan memulangkan semula kredit yang digunakan semasa anda mencipta tugas tersebut.

Tugas IN_PROGRESS tidak boleh dipadam. Permintaan akan mengembalikan 409 Conflict, dan tugas tersebut terus berjalan. Meshy tidak memulangkan semula kredit untuk tugas yang telah bermula, jadi memadamnya akan menyebabkan anda kehilangan kedua-dua kredit dan hasilnya. Tunggu sehingga ia mencapai status SUCCEEDED, FAILED, atau CANCELED, kemudian padamkannya.

Memadam tugas yang berada dalam status akhir (SUCCEEDED, FAILED, atau CANCELED) tidak memulangkan semula kreditnya.

GET/openapi/v1/uv-unwrap

Senaraikan tugas UV Unwrap

Mengembalikan senarai tugas UV Unwrap anda secara berhalaman, yang terbaru dahulu. Untuk menyemak imbas senarai tersebut, gunakan 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

Alirkan tugas UV Unwrap

Mengalirkan kemas kini tugas UV Unwrap sebagai Server-Sent Events (SSE). Setiap acara message membawa satu objek tugas UV Unwrap. Aliran akan ditutup apabila tugas mencapai status SUCCEEDED, FAILED, atau CANCELED.

Untuk mengetahui dengan lebih awal bahawa tugas telah selesai, gunakan endpoint ini berbanding melakukan polling pada GET /openapi/v1/uv-unwrap/:id.

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 tugas UV Unwrap

Objek tugas UV Unwrap menerangkan satu UV unwrap bagi model 3D. Ia menyimpan status, progress, dan fail model apabila tugas 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
}
  • Name
    id
    Type
    string
    Description

    ID tugas. Anggap ia sebagai rentetan legap, dan jangan bergantung pada formatnya.

  • Name
    type
    Type
    string
    Description

    Jenis tugas, sentiasa uv-unwrap.

  • Name
    model_urls
    Type
    object
    Description

    URL muat turun bertandatangan untuk model putih UV. UV Unwrap sentiasa mengembalikan satu kunci glb. Model ini mengekalkan geometri input, mempunyai koordinat UV yang baharu, dan menggunakan bahan kelabu lalai sebagai ganti tekstur.

  • Name
    thumbnail_url
    Type
    string
    Description

    URL muat turun bertandatangan untuk imej pratonton PNG bagi model putih UV.

  • Name
    progress
    Type
    integer
    Description

    Sejauh mana tugas telah selesai, sebagai peratusan dari 0 hingga 100.

  • Name
    status
    Type
    string
    Description

    Status tugas, salah satu daripada PENDING, IN_PROGRESS, SUCCEEDED, FAILED, atau CANCELED.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Bilangan tugas yang mendahului tugas ini dalam baris gilir. Hadir semasa tugas berstatus PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

    Masa tugas dicipta, dalam milisaat Unix.

  • Name
    started_at
    Type
    timestamp
    Description

    Masa tugas bermula, dalam milisaat Unix. Nilainya 0 sehingga tugas bermula.

  • Name
    finished_at
    Type
    timestamp
    Description

    Masa tugas selesai, dalam milisaat Unix. Nilainya 0 sehingga tugas selesai.

  • Name
    expires_at
    Type
    timestamp
    Description

    Masa URL muat turun bertandatangan tamat tempoh, dalam milisaat Unix.

  • Name
    task_error
    Type
    object
    Description

    Butiran ralat apabila tugas gagal. Lihat Ralat.

  • Name
    consumed_credits
    Type
    integer
    Description

    Bilangan kredit yang digunakan oleh tugas. Tugas UV Unwrap yang berjaya berkos 5 kredit. Nilainya 0 untuk tugas FAILED, kerana Meshy memulangkan semula kredit apabila tugas gagal.