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

API Remesh

API Remesh membolehkan anda meng-remesh dan mengeksport model 3D sedia ada yang dijana oleh API Meshy lain (seperti Imej ke 3D atau Teks ke 3D) ke pelbagai format. Bahagian ini memberikan butiran tentang cara menggunakan API Remesh.

POST/openapi/v1/remesh

Create a Remesh Task

Endpoint ini mencipta tugas remesh yang baharu.

Tugas ini berjalan di latar belakang. Untuk tempoh masa yang biasanya diambil, lihat Processing Times.

Untuk penukaran format dan pengubahan saiz, gunakan Convert API dan Resize API yang khusus. Parameter lapuk di bawah akan terus berfungsi, tetapi kami mengesyorkan endpoint baharu untuk integrasi baharu.

Parameter

Hanya salah satu daripada input_task_id atau model_url yang diperlukan. Jika kedua-duanya disediakan, input_task_id diutamakan.

  • Name
    input_task_id
    Type
    string
    Diperlukan
    Description

    ID bagi tugas Imej ke 3D atau Teks ke 3D yang telah selesai yang anda ingin remesh. Tugas ini mestilah salah satu daripada tugas berikut: Text to 3D Preview, Text to 3D Refine, Image to 3D atau Retextur. Selain itu, ia mesti mempunyai status SUCCEEDED.

  • Name
    model_url
    Type
    string
    Diperlukan
    Description

    Sila sediakan model 3D untuk Meshy remesh melalui URL yang boleh diakses secara umum atau data URI. Format yang disokong: .glb, .gltf, .obj, .fbx, .stl.

    Untuk Data URI, gunakan MIME type: application/octet-stream.

    Saiz fail maksimum: 400 MB untuk URL http atau https, 100 MB untuk URI data:.

    Fail GLB, glTF, FBX atau OBJ yang melebihi 100 MB boleh mempunyai paling banyak 10,000,000 muka. Muka dikira sebagai segi tiga: segi empat dikira sebagai 2, dan jejaring yang dilukis lebih daripada sekali dikira sekali bagi setiap salinan. Melebihi 100 MB, fail FBX mestilah FBX binari 7.1 atau lebih baharu, dan fail GLB atau glTF tidak boleh menggunakan pemampatan Draco.

  • Name
    target_formats
    Type
    string[]
    lalai ["glb"]
    Description

    Senarai format sasaran untuk model yang di-remesh. Jika diabaikan, hanya GLB dijana.

    Nilai yang tersedia: glb, fbx, obj, usdz, blend, stl, 3mf.

  • Name
    topology
    Type
    string
    lalai triangle
    Description

    Nyatakan topology model yang dijana.

    Nilai yang tersedia:

    • quad: Jana jejaring yang didominasi segi empat.
    • triangle: Jana jejaring segi tiga yang didesimasi.
  • Name
    target_polycount
    Type
    integer
    lalai 30,000
    Description

    Nyatakan bilangan sasaran poligon dalam model yang dijana. Bilangan sebenar poligon mungkin berbeza daripada sasaran bergantung pada kerumitan geometri.

    Julat yang sah ialah 100 hingga 300,000 (termasuk).

  • Name
    decimation_mode
    Type
    integer
    Description

    Dayakan desimasi adaptif dengan menetapkan tahap bilangan poligon. Apabila ditetapkan, target_polycount diabaikan.

    Nilai yang tersedia:

    • 1: Adaptif — bilangan poligon ultra.
    • 2: Adaptif — bilangan poligon tinggi.
    • 3: Adaptif — bilangan poligon sederhana.
    • 4: Adaptif — bilangan poligon rendah.
  • Name
    resize_height
    Type
    number
    ⚠ lapuk
    lalai 0
    Description

    Ubah saiz model kepada ketinggian tertentu yang diukur dalam meter. Kami mengesyorkan menggunakan Resize API yang khusus sebagai gantinya.

    auto_size, resize_height, dan resize_longest_side saling eksklusif.

  • Name
    resize_longest_side
    Type
    number
    ⚠ lapuk
    lalai 0
    Description

    Ubah saiz model supaya dimensi kotak sempadan terpanjang bersamaan dengan nilai yang dinyatakan dalam meter. Kami mengesyorkan menggunakan Resize API yang khusus sebagai gantinya.

    auto_size, resize_height, dan resize_longest_side saling eksklusif.

  • Name
    auto_size
    Type
    boolean
    ⚠ lapuk
    lalai false
    Description

    Apabila ditetapkan kepada true, perkhidmatan menggunakan penglihatan AI untuk menganggarkan secara automatik ketinggian objek di dunia sebenar dan mengubah saiz model mengikutnya. Kami mengesyorkan menggunakan Resize API yang khusus sebagai gantinya.

    auto_size, resize_height, dan resize_longest_side saling eksklusif.

Hanya berlaku apabila auto_size = true
  • Name
    origin_at
    Type
    string
    ⚠ lapuk
    lalai bottom
    Description

    Kedudukan titik asal. Kami mengesyorkan menggunakan Resize API yang khusus sebagai gantinya.

    Nilai yang tersedia: bottom, center.

  • Name
    convert_format_only
    Type
    boolean
    ⚠ lapuk
    Description

    Jika true, perkhidmatan hanya akan menukar format fail model input, mengabaikan input lain seperti topology, resize_height, dan target_polycount. Kami mengesyorkan menggunakan Convert API yang khusus sebagai gantinya.

    target_formats mesti disediakan jika convert_format_only ditetapkan kepada true.

  • Name
    alpha_thumbnail
    Type
    boolean
    lalai false
    Description

    Apabila ditetapkan kepada true, tugas ini turut merender versi latar belakang lutsinar (RGBA) bagi pratonton dan mengembalikannya sebagai alpha_thumbnail_url pada respons GET. Medan thumbnail_url yang sedia ada tidak berubah.

Pulangan

Sifat result bagi respons mengandungi id bagi tugas remesh yang baharu dicipta.

Mod Kegagalan

  • Name
    400 - Bad Request
    Description

    Permintaan tidak boleh diterima. Punca biasa:

    • Parameter hilang: Sama ada model_url atau input_task_id mesti disediakan.
    • Tugas input tidak sah: input_task_id mesti merujuk kepada tugas yang berjaya daripada model yang disokong.
    • Format model tidak sah: model_url menunjuk kepada fail dengan sambungan yang tidak disokong.
    • URL tidak boleh dicapai: model_url tidak dapat dimuat turun.
    • Fail model terlalu besar: Fail model_url melebihi 400 MB (URL http atau https) atau 100 MB (URI data:).
    • Terlalu banyak muka: Fail model_url melebihi 100 MB dan mempunyai lebih daripada 10,000,000 muka. Kurangkan bilangan muka, kemudian hantar semula fail tersebut.
    • FBX ASCII melebihi 100 MB: Fail model_url ialah FBX ASCII yang melebihi 100 MB. Hantar sebagai FBX binari atau GLB.
    • Fail model tidak boleh dibaca: Fail model_url melebihi 100 MB dan pengepalanya tidak dapat dibaca, contohnya GLB atau glTF yang dimampatkan Draco, atau FBX binari yang lebih lama daripada 7.1.
    • Pengepala model terlalu kompleks: Fail model_url melebihi 100 MB dan pengepalanya mempunyai terlalu banyak jejaring, nod atau rekod untuk disemak. Kurangkan bilangan objek dalam fail, kemudian hantar semula.
    • Topology tidak sah: Parameter topology tidak sah.
    • Parameter saling eksklusif: auto_size dan resize_height tidak boleh ditetapkan serentak.
  • Name
    401 - Unauthorized
    Description

    Pengesahan gagal. Sila semak kunci API anda.

  • Name
    402 - Payment Required
    Description

    Kredit tidak mencukupi untuk melaksanakan tugas ini.

  • Name
    429 - Too Many Requests
    Description

    Anda telah melebihi had kadar anda.

Request

POST
/openapi/v1/remesh
# Basic remesh with custom formats and resize
curl https://api.meshy.ai/openapi/v1/remesh \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["glb", "fbx"],
    "topology": "quad",
    "target_polycount": 50000,
    "resize_height": 1.0,
    "origin_at": "bottom"
  }'

# Quad remesh with auto-size
curl https://api.meshy.ai/openapi/v1/remesh \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["glb", "fbx"],
    "topology": "quad",
    "target_polycount": 50000,
    "auto_size": true
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}
GET/openapi/v1/remesh/:id

Dapatkan Semula Tugas Remesh

Endpoint ini mendapatkan semula tugas remesh mengikut ID-nya.

Parameter

  • Name
    id
    Type
    path
    Description

    ID tugas remesh yang hendak didapatkan semula.

Pulangan

Objek Tugas Remesh.

Request

GET
/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f
curl https://api.meshy.ai/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "remesh",
  "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
      "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
},
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
}
DELETE/openapi/v1/remesh/:id

Padam Tugasan Remesh

Endpoint ini memadam tugasan remesh secara kekal, termasuk semua model dan data yang berkaitan. Tindakan ini tidak boleh diterbalikkan.

Parameter Laluan

  • Name
    id
    Type
    path
    Description

    ID bagi tugasan remesh yang hendak dipadam.

Status Tugasan

Tugasan yang masih PENDING akan dipadam dan kredit yang digunakan pada masa penciptaan akan dikembalikan.

Tugasan yang sudah IN_PROGRESS tidak boleh dipadam: permintaan akan ditolak dengan 409 Conflict dan tugasan tersebut terus berjalan. Kredit bagi tugasan yang telah dimulakan oleh worker tidak boleh dikembalikan, jadi memadamnya semasa ia sedang berjalan akan menyebabkan anda kehilangan kedua-dua kredit dan hasilnya. Tunggu sehingga ia mencapai SUCCEEDED, FAILED atau CANCELED, kemudian padamkannya.

Tugasan dalam keadaan terminal (SUCCEEDED, FAILED atau CANCELED) akan dipadam tanpa bayaran balik.

Returns

Mengembalikan 200 OK apabila berjaya, atau 409 Conflict apabila tugasan tersebut IN_PROGRESS.

Request

DELETE
/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS — the task is left running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}
GET/openapi/v1/remesh

Senaraikan Tugasan Remesh

Endpoint ini membolehkan anda mendapatkan senarai tugasan Remesh.

Parameter

  • Name
    page_num
    Type
    integer
    lalai 1
    Description

    Nombor halaman untuk penomboran halaman.

  • Name
    page_size
    Type
    integer
    lalai 10
    Description

    Had saiz halaman. Maksimum yang dibenarkan ialah 100 item.

  • Name
    sort_by
    Type
    string
    Description

    Medan untuk disusun mengikut.

    Nilai yang tersedia:

    • +created_at: Susun mengikut masa penciptaan secara menaik.
    • -created_at: Susun mengikut masa penciptaan secara menurun.

Pulangan

Mengembalikan senarai berhalaman bagi Objek Tugasan Remesh.

Request

GET
/openapi/v1/remesh
curl https://api.meshy.ai/openapi/v1/remesh?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "remesh",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
      "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null
  }
]
GET/openapi/v1/remesh/:id/stream

Alirkan Tugas Remesh

Endpoint ini mengalirkan kemas kini masa nyata untuk tugas Remesh menggunakan Server-Sent Events (SSE).

Parameter

  • Name
    id
    Type
    path
    Description

    Pengecam unik untuk tugas Remesh yang hendak dialirkan.

Pemulangan

Memulangkan aliran Objek Tugas Remesh sebagai Server-Sent Events.

Untuk tugas PENDING atau IN_PROGRESS, aliran respons hanya akan mengandungi medan progress dan status yang diperlukan.

Request

GET
/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream
curl -N https://api.meshy.ai/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "remesh",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
    "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
}

Objek Tugasan Remesh

Objek Tugasan Remesh mewakili unit kerja yang digunakan oleh Meshy untuk melakukan remesh dan mengeksport model 3D yang sedia ada ke dalam berbagai format. Objek ini mempunyai ciri-ciri berikut:

Ciri-ciri

  • Name
    id
    Type
    string
    Description

    Pengecam unik untuk tugasan. Walaupun kami menggunakan k-sortable UUID untuk id tugasan sebagai butiran pelaksanaan, anda tidak seharusnya membuat sebarang andaian tentang format id tersebut.

  • Name
    type
    Type
    string
    Description

    Jenis tugasan Remesh. Nilainya adalah remesh.

  • Name
    model_urls
    Type
    object
    Description

    URL yang boleh dimuat turun untuk fail model 3D bertekstur yang dijana oleh Meshy. Ciri untuk sesuatu format akan ditinggalkan jika format tersebut tidak dijana, dan bukan mengembalikan rentetan kosong.

    • Name
      glb
      Type
      string
      Description

      URL yang boleh dimuat turun untuk fail GLB.

    • Name
      fbx
      Type
      string
      Description

      URL yang boleh dimuat turun untuk fail FBX.

    • Name
      obj
      Type
      string
      Description

      URL yang boleh dimuat turun untuk fail OBJ.

    • Name
      usdz
      Type
      string
      Description

      URL yang boleh dimuat turun untuk fail USDZ.

    • Name
      blend
      Type
      string
      Description

      URL yang boleh dimuat turun untuk fail Blender.

    • Name
      stl
      Type
      string
      Description

      URL yang boleh dimuat turun untuk fail STL.

    • Name
      3mf
      Type
      string
      Description

      URL yang boleh dimuat turun untuk fail 3MF. Hanya wujud apabila 3mf diminta melalui target_formats.

  • Name
    thumbnail_url
    Type
    string
    Description

    URL yang boleh dimuat turun untuk imej pratonton yang dirender daripada model yang telah di-remesh.

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

    URL yang boleh dimuat turun untuk versi latar belakang lutsinar (RGBA) bagi thumbnail_url. Hanya wujud apabila tugasan dicipta dengan alpha_thumbnail: true dan pratonton lutsinar berjaya dirender; jika tidak, ciri ini ditinggalkan.

  • Name
    progress
    Type
    integer
    Description

    Progress tugasan. Jika tugasan belum dimulakan, ciri ini akan menjadi 0. Setelah tugasan berjaya, nilai ini akan menjadi 100.

  • Name
    status
    Type
    string
    Description

    Status tugasan. Nilai yang mungkin ialah salah satu daripada PENDING, IN_PROGRESS, SUCCEEDED, FAILED.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Bilangan tugasan yang mendahului.

    Nilai ciri ini hanya bermakna jika status tugasan adalah PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

    Cap masa bagi bila tugasan dicipta, dalam milisaat.

  • Name
    started_at
    Type
    timestamp
    Description

    Cap masa bagi bila tugasan dimulakan, dalam milisaat. Jika tugasan belum dimulakan, ciri ini akan menjadi 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Cap masa bagi bila tugasan selesai, dalam milisaat. Jika tugasan belum selesai, ciri ini akan menjadi 0.

  • Name
    task_error
    Type
    object
    Description

    Butiran ralat untuk tugasan yang gagal. Lihat Ralat untuk rujukan lengkap objek task_error.

  • Name
    consumed_credits
    Type
    integer
    Description

    Bilangan kredit yang digunakan oleh tugasan ini. Wujud apabila status tugasan adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk tugasan FAILED (kredit dikembalikan apabila gagal).

Example Remesh Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "remesh",
  "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
      "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5
}