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

Gumawa ng Remesh Task

Ang endpoint na ito ay gumagawa ng bagong remesh task.

Tumatakbo ang task sa background. Para malaman kung gaano karaming oras karaniwang aabutin, tingnan ang Processing Times.

Para sa pag-convert ng format at pag-resize, gamitin ang dedikadong Convert API at Resize API. Patuloy na gagana ang mga deprecated na parameter sa ibaba, 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. Dapat isa ito 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 publicly accessible na URL o data URI. Mga suportadong format: .glb, .gltf, .obj, .fbx, .stl.
Para sa Data URI, gamitin ang MIME type: application/octet-stream.
Maximum na sukat ng file: 400 MB para sa isang http o https URL, 100 MB para sa isang data: URI.
Ang isang GLB, glTF, FBX, o OBJ file na higit sa 100 MB ay maaaring magkaroon ng pinakamarami na 10,000,000 faces. Ang mga faces ay binibilang bilang triangles: ang isang quad ay binibilang bilang 2, at ang isang mesh na iginuhit nang higit sa isang beses ay binibilang nang isang beses kada kopya. Kapag higit sa 100 MB, ang isang FBX file ay dapat binary FBX 7.1 o mas bago, at ang isang GLB o glTF file ay hindi dapat gumamit ng Draco compression.

Name
target_formats
Type
string[]
default ["glb"]
Description
Isang listahan ng mga target na format para sa na-remesh na model. Kapag naiwan, GLB lamang ang nabubuo.
Mga magagamit na halaga: glb, fbx, obj, usdz, blend, stl, 3mf.
Name
topology
Type
string
default triangle
Description
Tukuyin ang topology ng nabuong model.
Mga magagamit na halaga:
- quad: Bumuo ng quad-dominant na mesh.
- triangle: Bumuo ng decimated na triangle mesh.
Name
target_polycount
Type
integer
default 30,000
Description
Tukuyin ang target na bilang ng mga polygon sa nabuong model. Ang aktwal na bilang ng mga polygon ay maaaring lumihis sa target depende sa pagiging komplikado ng heometriya.
Ang valid na saklaw ay 100 hanggang 300,000 (kasama).
Name
decimation_mode
Type
integer
Description
I-enable ang adaptive decimation sa pamamagitan ng pagtakda ng antas ng polycount. Kapag naitakda, hindi pinapansin ang target_polycount.
Mga magagamit na halaga:
- 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 ang dedikadong Resize API sa halip.
Ang auto_size, resize_height, at resize_longest_side ay mutually exclusive.
Name
resize_longest_side
Type
number
⚠ lipas na
default 0
Description
I-resize ang model para ang pinakamahabang bounding-box dimension ay katumbas ng tinukoy na halaga sa metro. Inirerekomenda naming gamitin ang dedikadong Resize API sa halip.
Ang auto_size, resize_height, at resize_longest_side ay mutually exclusive.
Name
auto_size
Type
boolean
⚠ lipas na
default false
Description
Kapag itinakda sa true, ginagamit ng serbisyo ang AI vision upang awtomatikong tantyain ang real-world na taas ng object at i-resize ang model nang naaayon. Inirerekomenda naming gamitin ang dedikadong Resize API sa halip.
Ang auto_size, resize_height, at resize_longest_side ay mutually exclusive.

Naaangkop lamang kapag auto_size = true

Name
origin_at
Type
string
⚠ lipas na
default bottom
Description
Posisyon ng origin. Inirerekomenda naming gamitin ang dedikadong Resize API sa halip.
Mga magagamit na halaga: bottom, center.

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

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

Ibinabalik

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

Mga Paraan ng Pagkabigo

Name
400 - Bad Request
Description
Hindi katanggap-tanggap ang request. Mga karaniwang sanhi:
- Nawawalang parameter: Dapat ibigay ang alinman sa model_url o input_task_id.
- Invalid na input task: Ang input_task_id ay dapat tumukoy sa isang matagumpay na task mula sa isang suportadong model.
- Invalid na model format: Ang model_url ay tumuturo sa isang file na may hindi suportadong extension.
- Hindi maabot na URL: Hindi ma-download ang model_url.
- Masyadong malaki ang model file: Ang model_url file ay lumampas sa 400 MB (http o https URL) o 100 MB (data: URI).
- Masyadong maraming faces: Ang model_url file ay higit sa 100 MB at may higit sa 10,000,000 faces. Bawasan ang bilang ng faces, pagkatapos ay ipadala muli ang file.
- ASCII FBX na higit sa 100 MB: Ang model_url file ay isang ASCII FBX na higit sa 100 MB. Ipadala ito bilang binary FBX o GLB.
- Hindi mabasang model file: Ang model_url file ay higit sa 100 MB at hindi mabasa ang header nito, halimbawa isang Draco-compressed na GLB o glTF, o isang binary FBX na mas luma sa 7.1.
- Masyadong komplikado ang model header: Ang model_url file ay higit sa 100 MB at ang header nito ay may masyadong maraming mesh, node, o record na susuriin. Bawasan ang bilang ng mga object sa file, pagkatapos ay ipadala ito muli.
- Invalid na topology: Invalid ang topology parameter.
- Mutually exclusive na mga parameter: Hindi maaaring parehong itakda ang auto_size at resize_height.
Name
401 - Unauthorized
Description
Nabigo ang authentication. Mangyaring suriin 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
Nalampasan mo 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 Remesh Task

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

Mga Parameter

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

Ibinabalik

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
}