Remesh API

Remesh API memungkinkan Anda melakukan Remesh dan mengekspor model 3D yang ada yang dihasilkan oleh API Meshy lainnya (seperti Gambar ke 3D atau Teks ke 3D) ke dalam berbagai format. Bagian ini memberikan detail tentang cara menggunakan Remesh API.

POST/openapi/v1/remesh

Buat Tugas Remesh

endpoint ini membuat tugas remesh baru.

Untuk konversi format dan pengubahan ukuran, gunakan API Konversi dan API Ubah ukuran khusus. parameter usang di bawah akan tetap berfungsi, tetapi kami merekomendasikan endpoint baru untuk integrasi baru.

Parameter

Hanya salah satu dari input_task_id atau model_url yang diperlukan. Jika keduanya diberikan, input_task_id mendapatkan prioritas.

Name
input_task_id
Type
string
Wajib
Description
ID dari tugas Gambar ke 3D atau Teks ke 3D yang telah selesai dan ingin Anda Remesh. Tugas ini harus berupa salah satu dari tugas berikut: Teks ke 3D Preview, Teks ke 3D Refine, Gambar ke 3D, atau Retexture. Selain itu, tugas tersebut harus memiliki status SUCCEEDED.

Name
model_url
Type
string
Wajib
Description
Harap berikan model 3D untuk di-Remesh oleh Meshy melalui URL yang dapat diakses publik atau Data URI. Format yang didukung: .glb, .gltf, .obj, .fbx, .stl.
Untuk Data URI, gunakan MIME type: application/octet-stream.

Name
target_formats
Type
string[]
default ["glb"]
Description
Daftar format target untuk model hasil Remesh. Jika dihilangkan, hanya GLB yang dibuat.
Nilai yang tersedia: glb, fbx, obj, usdz, blend, stl, 3mf.
Name
topology
Type
string
default triangle
Description
Tentukan topology model yang dibuat.
Nilai yang tersedia:
- quad: Buat mesh yang didominasi quad.
- triangle: Buat mesh segitiga yang disederhanakan.
Name
target_polycount
Type
integer
default 30,000
Description
Tentukan target jumlah poligon dalam model yang dibuat. Jumlah poligon aktual dapat menyimpang dari target tergantung pada kompleksitas geometri.
Rentang nilai yang valid bervariasi tergantung tingkat pengguna:
- 100 hingga 300.000 (inklusif)
Name
decimation_mode
Type
integer
Description
Aktifkan decimation adaptif dengan menetapkan tingkat jumlah poligon. Jika ditetapkan, target_polycount diabaikan.
Nilai yang tersedia:
- 1: Adaptif — jumlah poligon ultra.
- 2: Adaptif — jumlah poligon tinggi.
- 3: Adaptif — jumlah poligon sedang.
- 4: Adaptif — jumlah poligon rendah.
Name
resize_height
Type
number
⚠ usang
default 0
Description
Ubah ukuran model ke tinggi tertentu yang diukur dalam meter. Kami merekomendasikan penggunaan API Ubah ukuran khusus sebagai gantinya.
auto_size, resize_height, dan resize_longest_side saling eksklusif.
Name
resize_longest_side
Type
number
⚠ usang
default 0
Description
Ubah ukuran model sehingga dimensi bounding-box terpanjang sama dengan nilai yang ditentukan dalam meter. Kami merekomendasikan penggunaan API Ubah ukuran khusus sebagai gantinya.
auto_size, resize_height, dan resize_longest_side saling eksklusif.
Name
auto_size
Type
boolean
⚠ usang
default false
Description
Jika ditetapkan ke true, layanan menggunakan AI vision untuk memperkirakan tinggi objek di dunia nyata secara otomatis dan mengubah ukuran model sesuai dengan itu. Kami merekomendasikan penggunaan API Ubah ukuran khusus sebagai gantinya.
auto_size, resize_height, dan resize_longest_side saling eksklusif.

Hanya berlaku ketika auto_size = true

Name
origin_at
Type
string
⚠ usang
default bottom
Description
Posisi titik asal. Kami merekomendasikan penggunaan API Ubah ukuran khusus sebagai gantinya.
Nilai yang tersedia: bottom, center.

Name
convert_format_only
Type
boolean
⚠ usang
Description
Jika true, layanan hanya akan mengubah format file model input, mengabaikan input lain seperti topology, resize_height, dan target_polycount. Kami merekomendasikan penggunaan API Konversi khusus sebagai gantinya.
target_formats harus diberikan jika convert_format_only ditetapkan ke true.

Name
alpha_thumbnail
Type
boolean
default false
Description
Jika ditetapkan ke true, tugas juga merender versi pratinjau dengan latar belakang transparan (RGBA) dan mengembalikannya sebagai alpha_thumbnail_url pada respons GET. Bidang thumbnail_url yang ada tidak berubah.

Mengembalikan

Properti result dari respons berisi id tugas remesh yang baru dibuat.

Mode Kegagalan

Name
400 - Bad Request
Description
Permintaan tidak dapat diterima. Penyebab umum:
- Parameter hilang: model_url atau input_task_id harus diberikan.
- Tugas input tidak valid: input_task_id harus merujuk ke tugas yang berhasil dari model yang didukung.
- Format model tidak valid: model_url mengarah ke file dengan ekstensi yang tidak didukung.
- URL tidak dapat dijangkau: model_url tidak dapat diunduh.
- Topology tidak valid: Parameter topology tidak valid.
- Parameter saling eksklusif: auto_size dan resize_height tidak dapat ditetapkan bersamaan.
Name
401 - Unauthorized
Description
Autentikasi gagal. Harap periksa kunci API Anda.
Name
402 - Payment Required
Description
Kredit tidak mencukupi untuk melakukan tugas ini.
Name
429 - Too Many Requests
Description
Anda telah melampaui batas laju 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

Ambil Tugas Remesh

endpoint ini mengambil tugas Remesh berdasarkan ID-nya.

Parameter

Name
id
Type
path
Description
ID tugas Remesh yang akan diambil.

Mengembalikan

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

Hapus Tugas Remesh

Endpoint ini menghapus tugas remesh secara permanen, termasuk semua model dan data terkait. Tindakan ini tidak dapat dibatalkan.

Parameter Path

Name
id
Type
path
Description
ID tugas remesh yang akan dihapus.

Mengembalikan

Mengembalikan 200 OK jika berhasil.

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

Daftar Tugas Remesh

Endpoint ini memungkinkan Anda mengambil daftar tugas Remesh.

Parameter

Name
page_num
Type
integer
default 1
Description
Nomor halaman untuk paginasi.
Name
page_size
Type
integer
default 10
Description
Batas ukuran halaman. Maksimum yang diizinkan adalah 50 item.
Name
sort_by
Type
string
Description
Bidang untuk diurutkan berdasarkan.
Nilai yang tersedia:
- +created_at: Urutkan berdasarkan waktu pembuatan secara menaik.
- -created_at: Urutkan berdasarkan waktu pembuatan secara menurun.

Mengembalikan

Mengembalikan daftar terpaginasi dari 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

Streaming Tugas Remesh

endpoint ini melakukan streaming pembaruan real-time untuk tugas Remesh menggunakan Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Pengidentifikasi unik untuk tugas Remesh yang akan di-streaming.

Pengembalian

Mengembalikan stream Objek Tugas Remesh sebagai Server-Sent Events.

Untuk tugas PENDING atau IN_PROGRESS, stream respons hanya akan menyertakan kolom 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 merepresentasikan unit kerja yang digunakan Meshy untuk melakukan Remesh dan mengekspor model 3D yang sudah ada ke berbagai format. Objek ini memiliki properti berikut:

Properti

Name
id
Type
string
Description
Pengidentifikasi unik untuk tugas. Meskipun kami menggunakan UUID yang dapat diurutkan secara k untuk id tugas sebagai detail implementasi, Anda tidak boleh membuat asumsi apa pun tentang format id.
Name
type
Type
string
Description
Jenis tugas Remesh. Nilainya adalah remesh.
Name
model_urls
Type
object
Description
URL yang dapat diunduh untuk file model 3D bertekstur yang dihasilkan oleh Meshy. Properti untuk suatu format akan dihilangkan jika format tersebut tidak dihasilkan, alih-alih mengembalikan string kosong.
- Name
  glb
  Type
  string
  Description
  URL yang dapat diunduh untuk file GLB.
- Name
  fbx
  Type
  string
  Description
  URL yang dapat diunduh untuk file FBX.
- Name
  obj
  Type
  string
  Description
  URL yang dapat diunduh untuk file OBJ.
- Name
  usdz
  Type
  string
  Description
  URL yang dapat diunduh untuk file USDZ.
- Name
  blend
  Type
  string
  Description
  URL yang dapat diunduh untuk file Blender.
- Name
  stl
  Type
  string
  Description
  URL yang dapat diunduh untuk file STL.
- Name
  3mf
  Type
  string
  Description
  URL yang dapat diunduh untuk file 3MF. Hanya ada ketika 3mf diminta melalui target_formats.
Name
thumbnail_url
Type
string
Description
URL yang dapat diunduh untuk gambar pratinjau yang dirender dari model yang telah di-remesh.
Name
alpha_thumbnail_url
Type
string
Description
URL yang dapat diunduh untuk versi berlatar belakang transparan (RGBA) dari thumbnail_url. Hanya ada ketika tugas dibuat dengan alpha_thumbnail: true dan pratinjau transparan berhasil dirender; jika tidak, bidang ini dihilangkan.
Name
progress
Type
integer
Description
Progress tugas. Jika tugas belum dimulai, properti ini akan bernilai 0. Setelah tugas berhasil, nilainya 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
Jumlah tugas yang mendahului.
Nilai bidang ini hanya bermakna jika status tugas adalah PENDING.
Name
created_at
Type
timestamp
Description
Stempel waktu saat tugas dibuat, dalam milidetik.
Name
started_at
Type
timestamp
Description
Stempel waktu saat tugas dimulai, dalam milidetik. Jika tugas belum dimulai, properti ini akan bernilai 0.
Name
finished_at
Type
timestamp
Description
Stempel waktu saat tugas selesai, dalam milidetik. Jika tugas belum selesai, properti ini akan bernilai 0.
Name
task_error
Type
object
Description
Detail kesalahan untuk tugas yang gagal. Lihat Kesalahan untuk referensi lengkap objek task_error.
Name
consumed_credits
Type
integer
Description
Jumlah kredit yang dikonsumsi oleh tugas ini. Ada ketika status tugas adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk tugas FAILED (kredit dikembalikan jika 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
}