Remesh API

Ang Remesh API ay nagbibigay-daan sa iyo na i-remesh at i-export ang mga umiiral na 3D model na ginawa ng ibang Meshy API (tulad ng Image to 3D o Text to 3D) sa iba't ibang format. Ang seksyong ito ay nagbibigay ng mga detalye kung paano gamitin ang Remesh API.

POST/openapi/v1/remesh

Create a Remesh Task

Ang endpoint na ito ay gumagawa ng bagong remesh task.

Para sa pag-convert ng format at pag-resize, gamitin ang dedikadong Convert API at Resize API. Ang mga deprecated na parameter sa ibaba ay patuloy na gagana, ngunit inirerekomenda namin ang mga bagong endpoint para sa mga bagong integrasyon.

Mga Parameter

Isa lamang sa input_task_id o model_url ang kinakailangan. Kung parehong ibinigay, ang input_task_id ang mauuna.

Name
input_task_id
Type
string
Kinakailangan
Description
Ang ID ng nakumpletong Image to 3D o Text to 3D task na nais mong i-remesh. Ang task na ito ay dapat isa sa mga sumusunod na task: Text to 3D Preview, Text to 3D Refine, Image to 3D o Retexture. Bukod dito, dapat itong may status na SUCCEEDED.

Name
model_url
Type
string
Kinakailangan
Description
Mangyaring magbigay ng 3D model para i-remesh ni Meshy sa pamamagitan ng isang publicly accessible URL o data URI. Mga sinusuportahang format: .glb, .gltf, .obj, .fbx, .stl.
Para sa mga Data URI, gamitin ang MIME type: application/octet-stream.

Name
target_formats
Type
string[]
default ["glb"]
Description
Isang listahan ng mga target na format para sa na-remesh na model. Kapag hindi ibinigay, GLB lamang ang bubuuin.
Mga available na value: glb, fbx, obj, usdz, blend, stl, 3mf.
Name
topology
Type
string
default triangle
Description
Tukuyin ang topology ng nabuong model.
Mga available na value:
- quad: Bumuo ng quad-dominant na mesh.
- triangle: Bumuo ng decimated triangle mesh.
Name
target_polycount
Type
integer
default 30,000
Description
Tukuyin ang target na bilang ng polygon sa nabuong model. Ang aktwal na bilang ng polygon ay maaaring lumihis mula sa target depende sa complexity ng heometriya.
Ang valid na hanay ng value ay nag-iiba depende sa user tier:
- 100 hanggang 300,000 (kasama)
Name
decimation_mode
Type
integer
Description
Paganahin ang adaptive decimation sa pamamagitan ng pagtatakda ng polycount level. Kapag naitakda, ang target_polycount ay hindi papansinin.
Mga available na value:
- 1: Adaptive — ultra polycount.
- 2: Adaptive — mataas na polycount.
- 3: Adaptive — katamtamang polycount.
- 4: Adaptive — mababang polycount.
Name
resize_height
Type
number
⚠ lipas na
default 0
Description
I-resize ang model sa isang tiyak na taas na sinusukat sa metro. Inirerekomenda naming gamitin na lang ang dedikadong Resize API.
Ang auto_size, resize_height, at resize_longest_side ay magkakaiba at hindi maaaring sabayang gamitin.
Name
resize_longest_side
Type
number
⚠ lipas na
default 0
Description
I-resize ang model upang ang pinakamahabang bounding-box dimension ay katumbas ng tinukoy na value sa metro. Inirerekomenda naming gamitin na lang ang dedikadong Resize API.
Ang auto_size, resize_height, at resize_longest_side ay magkakaiba at hindi maaaring sabayang gamitin.
Name
auto_size
Type
boolean
⚠ lipas na
default false
Description
Kapag naitakda sa true, gagamit ang serbisyo ng AI vision upang awtomatikong tantiyahin ang real-world na taas ng object at i-resize ang model ayon dito. Inirerekomenda naming gamitin na lang ang dedikadong Resize API.
Ang auto_size, resize_height, at resize_longest_side ay magkakaiba at hindi maaaring sabayang gamitin.

Naaangkop lamang kapag auto_size = true

Name
origin_at
Type
string
⚠ lipas na
default bottom
Description
Posisyon ng origin. Inirerekomenda naming gamitin na lang ang dedikadong Resize API.
Mga available na value: bottom, center.

Name
convert_format_only
Type
boolean
⚠ lipas na
Description
Kung true, babaguhin lamang ng serbisyo ang format ng input model file, na hindi papansinin ang ibang input tulad ng topology, resize_height, at target_polycount. Inirerekomenda naming gamitin na lang ang dedikadong Convert API.
Ang target_formats ay dapat ibigay kung ang convert_format_only ay naitakda sa true.

Name
alpha_thumbnail
Type
boolean
default false
Description
Kapag naitakda sa true, ang task ay karagdagang mag-render ng transparent-background (RGBA) na bersyon ng preview at ibabalik ito bilang alpha_thumbnail_url sa GET response. Ang umiiral na field na thumbnail_url ay hindi nagbabago.

Mga Ibinabalik

Ang result property ng response ay naglalaman ng id ng bagong likhang remesh task.

Mga Mode ng Kabiguan

Name
400 - Bad Request
Description
Ang request ay hindi katanggap-tanggap. Karaniwang mga dahilan:
- Kulang na parameter: Alinman sa model_url o input_task_id ang dapat ibigay.
- Di-wastong input task: Ang input_task_id ay dapat tumutukoy sa isang matagumpay na task mula sa isang suportadong modelo.
- Di-wastong format ng modelo: Ang model_url ay tumutukoy sa isang file na may hindi suportadong extension.
- Hindi maabot na URL: Hindi ma-download ang model_url.
- Di-wastong topology: Ang topology parameter ay hindi valid.
- Magkakaibang parameter: Ang auto_size at resize_height ay hindi maaaring parehong itakda.
Name
401 - Unauthorized
Description
Nabigo ang authentication. Pakisuri ang iyong API key.
Name
402 - Payment Required
Description
Hindi sapat na credits para isagawa ang task na ito.
Name
429 - Too Many Requests
Description
Nalagpasan mo na ang iyong rate limit.

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

Kunin ang Detalye ng Remesh Task

Ang endpoint na ito ay kumukuha ng remesh task gamit ang ID nito.

Mga Parameter

Name
id
Type
path
Description
Ang ID ng remesh task na kukunin.

Ibabalik

Ang Remesh Task object.

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

I-delete ang Remesh Task

Ang endpoint na ito ay permanenteng nagde-delete ng remesh task, kasama ang lahat ng kaugnay na modelo at data. Hindi na maaaring bawiin ang aksyong ito.

Path Parameters

Name
id
Type
path
Description
Ang ID ng remesh task na ide-delete.

Katayuan ng Task

Ang task na PENDING pa ay dine-delete at ang mga credits na nagamit noong itong task ay ginawa ay ire-refund.

Ang task na IN_PROGRESS na ay hindi maaaring i-delete: ang kahilingan ay tatanggihan na may 409 Conflict at ang task ay patuloy na tatakbo. Ang mga credits para sa task na nasimulan na ng worker ay hindi na maaaring i-refund, kaya kung ide-delete ito habang tumatakbo, mawawala sa iyo ang credits at ang resulta. Hintayin muna itong umabot sa SUCCEEDED, FAILED, o CANCELED, bago ito i-delete.

Ang task na nasa terminal state (SUCCEEDED, FAILED, o CANCELED) ay dine-delete nang walang refund.

Ibinabalik

Nagbabalik ng 200 OK kapag matagumpay, o 409 Conflict kapag ang task ay 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

List Remesh Tasks

Ang endpoint na ito ay nagbibigay-daan sa iyong kunin ang isang listahan ng mga Remesh na gawain.

Mga Parameter

Name
page_num
Type
integer
default 1
Description
Numero ng pahina para sa pagination.
Name
page_size
Type
integer
default 10
Description
Limitasyon sa laki ng pahina. Ang pinakamataas na pinapayagan ay 100 item.
Name
sort_by
Type
string
Description
Field na gagamitin sa pag-sort.
Mga available na value:
- +created_at: Isaayos ayon sa oras ng paglikha nang pataas (ascending order).
- -created_at: Isaayos ayon sa oras ng paglikha nang pababa (descending order).

Mga Ibinabalik na Resulta

Nagbabalik ng isang pinaged na listahan ng Mga Remesh Task Object.

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

I-stream ang Remesh Task

Ang endpoint na ito ay nag-stream ng real-time na mga update para sa isang Remesh task gamit ang Server-Sent Events (SSE).

Mga Parameter

Name
id
Type
path
Description
Natatanging identifier para sa Remesh task na i-stream.

Ibinabalik

Nagbabalik ng stream ng The Remesh Task Objects bilang Server-Sent Events.

Para sa mga task na PENDING o IN_PROGRESS, isasama lamang ng response stream ang kinakailangang mga field na progress at status.

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

Ang Remesh Task Object

Ang Remesh Task object ay kumakatawan sa isang yunit ng trabaho na ginagamit ng Meshy para i-remesh at i-export ang isang umiiral nang 3D model sa iba't ibang format. Ang object ay may mga sumusunod na properties:

Mga Property

Name
id
Type
string
Description
Natatanging identifier para sa task. Bagama't gumagamit kami ng k-sortable UUID para sa mga task id bilang detalye ng implementasyon, hindi ka dapat gumawa ng anumang palagay tungkol sa format ng id.
Name
type
Type
string
Description
Uri ng Remesh task. Ang value ay remesh.
Name
model_urls
Type
object
Description
Downloadable URL patungo sa naka-texture na 3D model file na ginawa ng Meshy. Ang property para sa isang format ay hindi isasama kung hindi ito ginawa, sa halip na magbalik ng walang laman na string.
- Name
  glb
  Type
  string
  Description
  Downloadable URL patungo sa GLB file.
- Name
  fbx
  Type
  string
  Description
  Downloadable URL patungo sa FBX file.
- Name
  obj
  Type
  string
  Description
  Downloadable URL patungo sa OBJ file.
- Name
  usdz
  Type
  string
  Description
  Downloadable URL patungo sa USDZ file.
- Name
  blend
  Type
  string
  Description
  Downloadable URL patungo sa Blender file.
- Name
  stl
  Type
  string
  Description
  Downloadable URL patungo sa STL file.
- Name
  3mf
  Type
  string
  Description
  Downloadable URL patungo sa 3MF file. Naroroon lamang kapag hiniling ang 3mf sa pamamagitan ng target_formats.
Name
thumbnail_url
Type
string
Description
Downloadable URL patungo sa preview image na na-render mula sa na-remesh na modelo.
Name
alpha_thumbnail_url
Type
string
Description
Downloadable URL patungo sa bersyong may transparent na background (RGBA) ng thumbnail_url. Naroroon lamang kapag nilikha ang task na may alpha_thumbnail: true at matagumpay na na-render ang transparent na preview; kung hindi, aalisin ang field na ito.
Name
progress
Type
integer
Description
Progress ng task. Kung hindi pa nasisimulan ang task, ang property na ito ay magiging 0. Kapag nagtagumpay na ang task, ito ay magiging 100.
Name
status
Type
string
Description
Status ng task. Ang mga posibleng value ay isa sa PENDING, IN_PROGRESS, SUCCEEDED, FAILED.
Name
preceding_tasks
Type
integer
Description
Ang bilang ng mga naunang task.
Makabuluhan lamang ang value ng field na ito kung ang status ng task ay PENDING.
Name
created_at
Type
timestamp
Description
Timestamp kung kailan nilikha ang task, sa milliseconds.
Name
started_at
Type
timestamp
Description
Timestamp kung kailan sinimulan ang task, sa milliseconds. Kung hindi pa nasisimulan ang task, ang property na ito ay magiging 0.
Name
finished_at
Type
timestamp
Description
Timestamp kung kailan natapos ang task, sa milliseconds. Kung hindi pa natatapos ang task, ang property na ito ay magiging 0.
Name
task_error
Type
object
Description
Mga detalye ng error para sa mga nabigong task. Tingnan ang Errors para sa buong reference ng task_error object.
Name
consumed_credits
Type
integer
Description
Ang bilang ng credits na nagamit ng task na ito. Naroroon kapag ang status ng task ay PENDING, IN_PROGRESS, o SUCCEEDED. Nagbabalik ng 0 para sa mga FAILED na task (ang credits ay ire-refund kapag nabigo).

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
}