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

Cipta Tugasan Remesh

Endpoint ini mencipta tugasan remesh baharu.

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 diperlukan. Jika kedua-duanya diberikan, input_task_id diutamakan.

Name
input_task_id
Type
string
Diperlukan
Description
ID bagi tugasan Imej ke 3D atau Teks ke 3D yang telah selesai dan ingin anda remesh. Tugasan ini mestilah salah satu daripada tugasan berikut: Text to 3D Preview, Text to 3D Refine, Image to 3D atau Retexture. Selain itu, ia mesti mempunyai status SUCCEEDED.

Name
model_url
Type
string
Diperlukan
Description
Sila berikan model 3D untuk Meshy remesh melalui URL yang boleh diakses secara awam atau data URI. Format yang disokong: .glb, .gltf, .obj, .fbx, .stl.
Untuk Data URI, gunakan MIME type: application/octet-stream.

Name
target_formats
Type
string[]
lalai ["glb"]
Description
Senarai format sasaran untuk model yang telah di-remesh. Apabila ditinggalkan, hanya GLB akan dihasilkan.
Nilai yang tersedia: glb, fbx, obj, usdz, blend, stl, 3mf.
Name
topology
Type
string
lalai triangle
Description
Nyatakan topology bagi model yang dihasilkan.
Nilai yang tersedia:
- quad: Menghasilkan jejaring yang didominasi quad.
- triangle: Menghasilkan jejaring segi tiga yang telah dinyahkan (decimated).
Name
target_polycount
Type
integer
lalai 30,000
Description
Nyatakan sasaran bilangan poligon dalam model yang dihasilkan. Bilangan poligon sebenar mungkin berbeza daripada sasaran bergantung pada kerumitan geometri.
Julat nilai yang sah berbeza-beza bergantung pada peringkat pengguna:
- 100 hingga 300,000 (termasuk kedua-duanya)
Name
decimation_mode
Type
integer
Description
Aktifkan penyahnyaan (decimation) 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 penggunaan 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 sama dengan nilai yang dinyatakan dalam meter. Kami mengesyorkan penggunaan 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 ini menggunakan penglihatan AI untuk menganggarkan secara automatik ketinggian sebenar objek dan mengubah saiz model dengan sewajarnya. Kami mengesyorkan penggunaan 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 penggunaan 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 penggunaan Convert API yang khusus sebagai gantinya.
target_formats mesti diberikan jika convert_format_only ditetapkan kepada true.

Name
alpha_thumbnail
Type
boolean
lalai false
Description
Apabila ditetapkan kepada true, tugasan itu turut merender versi latar belakang telus (RGBA) bagi pratonton dan memulangkannya sebagai alpha_thumbnail_url pada respons GET. Medan thumbnail_url yang sedia ada tidak berubah.

Nilai Pulangan

Sifat result bagi respons mengandungi id bagi tugasan 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 diberikan.
- Tugasan input tidak sah: input_task_id mesti merujuk kepada tugasan berjaya daripada model yang disokong.
- Format model tidak sah: model_url menunjuk kepada fail dengan sambungan yang tidak disokong.
- URL tidak dapat dicapai: model_url tidak dapat dimuat turun.
- 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 tugasan 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.

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