API UV Unwrap

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

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

Keterbatasan. Auto UV kini menyokong jejaring sehingga 40,000 muka — model yang lebih besar ditolak dengan 400; jalankan Remesh terlebih dahulu untuk mengurangkan bilangan poligon. Jejaring quad dan n-gon ditriangulasi semasa penjanaan UV, jadi outputnya sentiasa jejaring segitiga.

POST/openapi/v1/uv-unwrap

Cipta Tugas UV Unwrap

Endpoint ini mencipta tugas UV Unwrap yang baru.

Parameter

Tepat satu daripada input_task_id atau model_url diperlukan. Jika kedua-duanya disediakan, input_task_id mengambil keutamaan.

  • Name
    input_task_id
    Type
    string
    Diperlukan
    Description

    ID bagi tugas Meshy API yang telah diselesaikan yang output GLB-nya anda ingin 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 bilangan muka sebanyak 40,000 muka, permintaan akan ditolak dengan 400 dan anda harus menjalankan Remesh terlebih dahulu untuk mengurangkan 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 glTF binari dan tidak memproses format lain. Untuk UV-unwrap model dalam format lain (.fbx, .obj, .stl, .gltf), tukar kepada .glb terlebih dahulu melalui Convert API, kemudian masukkan ID tugas yang terhasil sebagai input_task_id atau URL output GLB 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 akan ditolak dengan 400 — jalankan Remesh terlebih dahulu.

Pulangan

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

Mod Kegagalan

  • Name
    400 - Bad Request
    Description

    Permintaan tidak dapat diterima. Punca biasa:

    • Parameter hilang: Sama ada input_task_id atau model_url mesti disediakan.
    • Tugas input tidak sah: input_task_id mesti merujuk kepada tugas yang berjaya dengan hasil GLB.
    • Bilangan muka melebihi: Jejaring sumber mempunyai lebih banyak muka daripada had UV Unwrap. Jalankan Remesh terlebih dahulu.
    • Format model tidak sah: model_url menunjuk kepada fail dengan sambungan yang tidak disokong.
    • URL tidak dapat 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 memerlukan 5 kredit setiap panggilan.

  • Name
    404 - Not Found
    Description

    Ciri ini tidak diaktifkan untuk akaun anda. UV Unwrap dikawal oleh bendera Statsig semasa pelancaran — 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 Tugas UV Unwrap

Endpoint ini mendapatkan keadaan semasa tugas UV Unwrap melalui ID.

Mengembalikan

Mengembalikan objek Tugas UV Unwrap.

Permintaan

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

Padam secara kekal tugas UV Unwrap. Tugas dan hasilnya menjadi tidak boleh diakses.

Permintaan

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

Senarai Tugas UV Unwrap

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

Strimkan Tugas UV Unwrap

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

Gunakan ini sebagai ganti pengundian GET /openapi/v1/uv-unwrap/:id untuk latensi yang lebih rendah pada penyelesaian.

Permintaan

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

  • Name
    id
    Type
    string
    Description

    Pengenal unik untuk tugas ini.

  • Name
    type
    Type
    string
    Description

    Sentiasa uv-unwrap.

  • Name
    model_urls
    Type
    object
    Description

    URL muat turun pra-tandatangan untuk model putih UV yang dihasilkan. UV Unwrap sentiasa mengembalikan satu entri glb — output mengekalkan geometri input, menukar kepada koordinat UV baru, dan menggunakan bahan kelabu lalai menggantikan sebarang tekstur.

  • Name
    thumbnail_url
    Type
    string
    Description

    URL pra-tandatangan kepada pratonton PNG model putih UV.

  • Name
    progress
    Type
    integer
    Description

    Progress tugas, dari 0 hingga 100.

  • Name
    status
    Type
    string
    Description

    Salah satu daripada PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Bilangan tugas yang beratur sebelum tugas ini. Hadir semasa status adalah PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

    Cap masa penciptaan tugas, 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 URL muat turun yang ditandatangani tamat tempoh, dalam milisaat.

  • Name
    task_error
    Type
    object
    Description

    Butiran ralat untuk tugas yang gagal. Lihat Ralat untuk rujukan penuh objek task_error.

  • Name
    consumed_credits
    Type
    integer
    Description

    Kredit yang digunakan oleh tugas ini. Mengembalikan 0 untuk tugas FAILED (kredit dikembalikan jika gagal). UV Unwrap mengenakan caj 5 kredit jika berjaya.

Contoh Objek Tugas UV Unwrap

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