API Remesh

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

POST/openapi/v1/remesh

Cipta Tugas Remesh

Endpoint ini mencipta tugas remesh baharu.

Untuk penukaran format dan ubah saiz, gunakan API Tukar dan API Ubah Saiz 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 disediakan, input_task_id diberi 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 mestilah salah satu daripada tugas berikut: Text to 3D Preview, Text to 3D Refine, Image to 3D atau Retexture. Selain itu, ia mestilah 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.

Name
target_formats
Type
string[]
lalai ["glb"]
Description
Senarai format sasaran untuk model yang telah di-remesh. Jika diabaikan, hanya GLB dijana.
Nilai yang tersedia: glb, fbx, obj, usdz, blend, stl, 3mf.
Name
topology
Type
string
lalai triangle
Description
Tentukan topology model yang dijana.
Nilai yang tersedia:
- quad: Jana jejaring yang didominasi quad.
- triangle: Jana jejaring segi tiga yang telah dinyahkan (decimated).
Name
target_polycount
Type
integer
lalai 30,000
Description
Tentukan bilangan sasaran poligon dalam model yang dijana. 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)
Name
decimation_mode
Type
integer
Description
Dayakan 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 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 bounding-box terpanjang bersamaan dengan nilai yang ditentukan dalam meter. Kami mengesyorkan menggunakan API Ubah Saiz 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 sebenar objek dan mengubah saiz model dengan sewajarnya. Kami mengesyorkan menggunakan API Ubah Saiz 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 API Ubah Saiz 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 API Tukar 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 tersebut 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.

Pemulangan

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

Mod Kegagalan

Name
400 - Bad Request
Description
Permintaan tidak boleh diterima. Punca biasa:
- Parameter tiada: 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 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 sekali.
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 berdasarkan 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 diundur.

Parameter Laluan

Name
id
Type
path
Description
ID bagi tugasan remesh yang hendak dipadam.

Pemulangan

Mengembalikan 200 OK apabila berjaya.

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

// Returns 200 Ok on success.

GET/openapi/v1/remesh

Senaraikan Tugas Remesh

Endpoint ini membolehkan anda mendapatkan semula 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 diisih mengikut.
Nilai yang tersedia:
- +created_at: Isih mengikut masa penciptaan secara menaik.
- -created_at: Isih mengikut masa penciptaan secara menurun.

Pulangan

Mengembalikan senarai berpenomboran halaman bagi Objek Tugas 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
Pengenal unik untuk tugas Remesh yang hendak dialirkan.

Pulangan

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

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

Sifat

Name
id
Type
string
Description
Pengecam unik untuk tugas ini. Walaupun kami menggunakan UUID yang boleh disusun-k (k-sortable) sebagai butiran pelaksanaan untuk id tugas, anda tidak sepatutnya membuat sebarang andaian tentang format id tersebut.
Name
type
Type
string
Description
Jenis tugas Remesh. Nilainya ialah remesh.
Name
model_urls
Type
object
Description
URL yang boleh dimuat turun untuk fail model 3D bertekstur yang dijana oleh Meshy. Sifat untuk sesuatu format akan ditiadakan jika format tersebut tidak dijana, 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 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 tugas dicipta dengan alpha_thumbnail: true dan pratonton lutsinar berjaya dirender; jika tidak, medan ini ditiadakan.
Name
progress
Type
integer
Description
Progress tugas ini. Jika tugas belum bermula, sifat ini akan bernilai 0. Setelah tugas berjaya, ia akan menjadi 100.
Name
status
Type
string
Description
Status tugas ini. Nilai yang mungkin ialah salah satu daripada PENDING, IN_PROGRESS, SUCCEEDED, FAILED.
Name
preceding_tasks
Type
integer
Description
Bilangan tugas terdahulu yang belum selesai.
Nilai medan ini hanya bermakna jika status tugas ialah PENDING.
Name
created_at
Type
timestamp
Description
Cap masa bila tugas ini dicipta, dalam milisaat.
Name
started_at
Type
timestamp
Description
Cap masa bila tugas ini bermula, dalam milisaat. Jika tugas belum bermula, sifat ini akan bernilai 0.
Name
finished_at
Type
timestamp
Description
Cap masa bila tugas ini selesai, dalam milisaat. Jika tugas belum selesai, sifat ini akan bernilai 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. Wujud apabila status tugas ialah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk tugas 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
}