API Remesh

API Remesh membolehkan anda melakukan Remesh dan mengeksport 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 baharu.

Untuk penukaran format dan pengubahan 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 satu daripada input_task_id atau model_url diperlukan. Jika kedua-duanya diberikan, 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 ingin anda remesh. Tugas ini mestilah salah satu daripada tugas berikut: Pratonton Teks ke 3D, Perhalus Teks ke 3D, Imej ke 3D atau Retekstur. Selain itu, ia mesti mempunyai status SUCCEEDED.

Name
model_url
Type
string
Diperlukan
Description
Sila berikan model 3D untuk Meshy remesh melalui URL atau data URI yang boleh diakses secara awam. 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 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 dominan quad.
- triangle: Jana jejaring segi tiga yang dinyahpadatkan.
Name
target_polycount
Type
integer
lalai 30,000
Description
Tentukan bilangan poligon sasaran dalam model yang dijana. Bilangan poligon sebenar mungkin menyimpang daripada 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
Dayakan nyahpadat 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 sebaliknya.
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 bersamaan dengan nilai yang ditentukan dalam meter. Kami mengesyorkan menggunakan API Ubah saiz yang khusus sebaliknya.
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 penglihatan AI untuk menganggarkan ketinggian dunia sebenar objek secara automatik dan mengubah saiz model dengan sewajarnya. Kami mengesyorkan menggunakan API Ubah saiz yang khusus sebaliknya.
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 khusus sebaliknya.
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 sebaliknya.
target_formats mesti diberikan jika convert_format_only ditetapkan kepada true.

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

Pulangan

Sifat result bagi respons mengandungi id tugas remesh yang baru 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 diberikan.
- 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 kedua-duanya ditetapkan.
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 Tugasan Remesh

endpoint ini mendapatkan tugasan Remesh berdasarkan IDnya.

Parameter

Name
id
Type
path
Description
ID tugasan Remesh yang hendak didapatkan.

Mengembalikan

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

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

Parameter Laluan

Name
id
Type
path
Description
ID tugas remesh yang hendak dipadamkan.

Pulangan

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 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 50 item.
Name
sort_by
Type
string
Description
Medan untuk diisih mengikutnya.
Nilai yang tersedia:
- +created_at: Isih mengikut masa penciptaan dalam tertib menaik.
- -created_at: Isih mengikut masa penciptaan dalam tertib menurun.

Mengembalikan

Mengembalikan senarai bernombor halaman 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

Strimkan Tugas Remesh

endpoint ini menstrim 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 distrim.

Mengembalikan

Mengembalikan aliran Objek Tugas Remesh sebagai Server-Sent Events.

Untuk tugas PENDING atau IN_PROGRESS, aliran respons hanya akan menyertakan 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 dalam pelbagai format. Objek ini mempunyai sifat berikut:

Sifat

Name
id
Type
string
Description
Pengecam unik untuk tugasan. Walaupun kami menggunakan UUID k-sortable untuk id tugasan sebagai perincian pelaksanaan, anda tidak harus membuat sebarang andaian tentang format id.
Name
type
Type
string
Description
Jenis tugasan Remesh. Nilainya ialah remesh.
Name
model_urls
Type
object
Description
URL boleh dimuat turun untuk fail model 3D bertekstur yang dijana oleh Meshy. Sifat untuk sesuatu format akan ditinggalkan jika format tersebut tidak dijana, bukannya mengembalikan rentetan kosong.
- Name
  glb
  Type
  string
  Description
  URL boleh dimuat turun untuk fail GLB.
- Name
  fbx
  Type
  string
  Description
  URL boleh dimuat turun untuk fail FBX.
- Name
  obj
  Type
  string
  Description
  URL boleh dimuat turun untuk fail OBJ.
- Name
  usdz
  Type
  string
  Description
  URL boleh dimuat turun untuk fail USDZ.
- Name
  blend
  Type
  string
  Description
  URL boleh dimuat turun untuk fail Blender.
- Name
  stl
  Type
  string
  Description
  URL boleh dimuat turun untuk fail STL.
- Name
  3mf
  Type
  string
  Description
  URL boleh dimuat turun untuk fail 3MF. Hanya hadir apabila 3mf diminta melalui target_formats.
Name
thumbnail_url
Type
string
Description
URL boleh dimuat turun untuk imej pratonton yang dirender daripada model yang telah di-Remesh.
Name
alpha_thumbnail_url
Type
string
Description
URL boleh dimuat turun untuk versi berlatar belakang lutsinar (RGBA) bagi thumbnail_url. Hanya hadir apabila tugasan dicipta dengan alpha_thumbnail: true dan pratonton lutsinar berjaya dirender; jika tidak, medan ini ditinggalkan.
Name
progress
Type
integer
Description
Progress tugasan. Jika tugasan belum bermula, sifat ini akan menjadi 0. Setelah tugasan berjaya, 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
Kiraan tugasan terdahulu.
Nilai medan ini hanya bermakna jika status tugasan ialah PENDING.
Name
created_at
Type
timestamp
Description
Cap masa bila tugasan dicipta, dalam milisaat.
Name
started_at
Type
timestamp
Description
Cap masa bila tugasan dimulakan, dalam milisaat. Jika tugasan belum bermula, sifat ini akan menjadi 0.
Name
finished_at
Type
timestamp
Description
Cap masa bila tugasan selesai, dalam milisaat. Jika tugasan belum selesai, sifat ini akan menjadi 0.
Name
task_error
Type
object
Description
Butiran ralat untuk tugasan yang gagal. Lihat Ralat untuk rujukan objek task_error penuh.
Name
consumed_credits
Type
integer
Description
Bilangan kredit yang digunakan oleh tugasan ini. Hadir apabila status tugasan ialah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk tugasan FAILED (kredit dipulangkan semula 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
}