API Remesh

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

POST/openapi/v1/remesh

Cipta Tugas Remesh

Endpoint ini mencipta tugas remesh baru.

Untuk penukaran format dan pengubahan saiz, gunakan API Tukar dan API Ubah Saiz yang dikhaskan. Parameter lapuk di bawah akan terus berfungsi, tetapi kami mengesyorkan endpoint baru untuk integrasi baru.

Parameter

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

Name
input_task_id
Type
string
Diperlukan
Description
ID tugas Imej ke 3D atau Teks ke 3D yang telah selesai yang anda ingin remesh. Tugas ini mesti salah satu daripada tugas berikut: Pratonton Teks ke 3D, Penapisan Teks ke 3D, Imej ke 3D atau Retekstur. 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 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 tidak dinyatakan, hanya GLB yang dihasilkan.
Nilai yang tersedia: glb, fbx, obj, usdz, blend, stl, 3mf.
Name
topology
Type
string
lalai triangle
Description
Nyatakan topology model yang dihasilkan.
Nilai yang tersedia:
- quad: Hasilkan jejaring dominan quad.
- triangle: Hasilkan jejaring segitiga yang di-decimate.
Name
target_polycount
Type
integer
lalai 30,000
Description
Nyatakan bilangan poligon sasaran dalam model yang dihasilkan. Bilangan poligon sebenar mungkin menyimpang dari sasaran bergantung pada kerumitan geometri.
Julat nilai yang sah berbeza bergantung pada peringkat pengguna:
- 100 hingga 300,000 (termasuk)
Name
decimation_mode
Type
integer
Description
Aktifkan 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 menggunakan API Ubah Saiz yang dikhaskan.
auto_size, resize_height, dan resize_longest_side adalah 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 menggunakan API Ubah Saiz yang dikhaskan.
auto_size, resize_height, dan resize_longest_side adalah saling eksklusif.
Name
auto_size
Type
boolean
⚠ lapuk
lalai false
Description
Apabila ditetapkan kepada true, perkhidmatan menggunakan visi AI untuk secara automatik menganggarkan ketinggian sebenar objek dan mengubah saiz model dengan sewajarnya. Kami mengesyorkan menggunakan API Ubah Saiz yang dikhaskan.
auto_size, resize_height, dan resize_longest_side adalah saling eksklusif.

Hanya berlaku apabila auto_size = true

Name
origin_at
Type
string
⚠ lapuk
lalai bottom
Description
Kedudukan titik asal. Kami mengesyorkan menggunakan API Ubah Saiz yang dikhaskan.
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 API Tukar yang dikhaskan.
target_formats mesti disediakan jika convert_format_only ditetapkan kepada true.

Name
alpha_thumbnail
Type
boolean
lalai false
Description
Apabila ditetapkan kepada true, tugas juga akan menghasilkan versi pratonton dengan latar belakang telus (RGBA) dan mengembalikannya sebagai alpha_thumbnail_url pada respons GET. Medan thumbnail_url yang sedia ada tidak berubah.

Pemulangan

Properti result dalam respons mengandungi id tugas remesh yang baru dicipta.

Mod Kegagalan

Name
400 - Bad Request
Description
Permintaan tidak dapat 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 dari 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 kedua-duanya.
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.

Permintaan

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

Respons

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

GET/openapi/v1/remesh/:id

Dapatkan Tugas Remesh

Endpoint ini mendapatkan tugas remesh berdasarkan ID-nya.

Parameter

Name
id
Type
path
Description
ID tugas remesh yang ingin didapatkan.

Pulangan

Objek Tugas Remesh.

Permintaan

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

Respons

{
  "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 Tugas Remesh

Endpoint ini memadamkan tugas remesh secara kekal, termasuk semua model dan data yang berkaitan. Tindakan ini tidak boleh dipulihkan.

Parameter Laluan

Name
id
Type
path
Description
ID tugas remesh untuk dipadamkan.

Pulangan

Mengembalikan 200 OK jika berjaya.

Permintaan

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

Respons

// Returns 200 Ok on success.

GET/openapi/v1/remesh

Senarai Tugas Remesh

Endpoint ini membolehkan anda mendapatkan senarai tugas 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 50 item.
Name
sort_by
Type
string
Description
Medan untuk disusun.
Nilai yang tersedia:
- +created_at: Susun mengikut masa penciptaan dalam susunan menaik.
- -created_at: Susun mengikut masa penciptaan dalam susunan menurun.

Pulangan

Mengembalikan senarai berpenomboran Objek Tugas Remesh.

Permintaan

GET

/openapi/v1/remesh

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

Respons

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

Strim Tugas Remesh

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

Parameter

Name
id
Type
path
Description
Pengenal pasti unik untuk tugas Remesh yang hendak distrim.

Pulangan

Mengembalikan strim Objek Tugas Remesh sebagai Server-Sent Events.

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

Permintaan

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

Strim Respons

// 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 Tugas Remesh

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

Sifat-sifat

Name
id
Type
string
Description
Pengenal pasti unik untuk tugas ini. Walaupun kami menggunakan UUID yang boleh disusun k untuk id tugas sebagai butiran pelaksanaan, anda tidak seharusnya membuat sebarang andaian tentang format id tersebut.
Name
type
Type
string
Description
Jenis tugas Remesh. Nilainya adalah remesh.
Name
model_urls
Type
object
Description
URL yang boleh dimuat turun untuk fail model 3D bertekstur yang dihasilkan oleh Meshy. Sifat untuk format akan diabaikan jika format tersebut tidak dihasilkan, bukannya 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 ada apabila 3mf diminta melalui target_formats.
Name
thumbnail_url
Type
string
Description
URL yang boleh dimuat turun untuk imej pratonton yang dirender dari model yang telah di-remesh.
Name
alpha_thumbnail_url
Type
string
Description
URL yang boleh dimuat turun untuk versi latar belakang telus (RGBA) dari thumbnail_url. Hanya ada apabila tugas dicipta dengan alpha_thumbnail: true dan pratonton telus berjaya dirender; jika tidak, medan ini akan diabaikan.
Name
progress
Type
integer
Description
Kemajuan tugas. Jika tugas belum dimulakan, sifat ini akan menjadi 0. Setelah tugas berjaya, ini akan menjadi 100.
Name
status
Type
string
Description
Status tugas. Nilai yang mungkin adalah salah satu dari PENDING, IN_PROGRESS, SUCCEEDED, FAILED.
Name
preceding_tasks
Type
integer
Description
Bilangan tugas terdahulu.
Nilai medan ini hanya bermakna jika status tugas adalah PENDING.
Name
created_at
Type
timestamp
Description
Cap masa ketika tugas dicipta, dalam milisaat.
Name
started_at
Type
timestamp
Description
Cap masa ketika tugas dimulakan, dalam milisaat. Jika tugas belum dimulakan, sifat ini akan menjadi 0.
Name
finished_at
Type
timestamp
Description
Cap masa ketika tugas selesai, dalam milisaat. Jika tugas belum selesai, sifat ini akan menjadi 0.
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
Bilangan kredit yang digunakan oleh tugas ini. Ada apabila status tugas adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk tugas FAILED (kredit akan dikembalikan jika gagal).

Contoh Objek Tugas Remesh

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