Convert API

I-convert ang 3D model sa ibang mga format ng file, mula sa isang Meshy task o mula sa isang model file.

POST/openapi/v1/convert

Gumawa ng Convert task

Gumagawa ng Convert task. Tumatakbo ang task sa background. Para sa karaniwang tagal ng isang task, tingnan ang Processing times.

Request

POST

/openapi/v1/convert

curl https://api.meshy.ai/openapi/v1/convert \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["fbx", "stl"]
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

Mga Parameter

Name
input_task_id
Type
string
Kinakailangan
Description
Kinakailangan maliban kung magpapadala ka ng model_url. Ang ID ng task na gumawa ng 3D model, halimbawa ang isang Text to 3D, Image to 3D, Remesh, Resize, o Retexture task. Dapat ang task ay galing sa API at may status na SUCCEEDED.

Name
model_url
Type
string
Kinakailangan
Description
Kinakailangan maliban kung magpapadala ka ng input_task_id. Ang model na i-convert, bilang isang public URL o isang data URI. Kung ipapadala mo pareho, gagamitin ng Meshy ang input_task_id.
Ang model ay dapat isang GLB, glTF, OBJ, FBX, o STL file na hindi hihigit sa 400 MB mula sa isang http o https URL, o 100 MB bilang data URI. Para sa data URI, gamitin ang MIME type na application/octet-stream.
Ang file na lampas sa 100 MB ay dapat ding sumunod sa mga sumusunod na patakaran:
- Ang isang GLB, glTF, FBX, o OBJ file ay maaari lamang magkaroon ng hanggang 10,000,000 faces. Binibilang ng Meshy ang faces bilang triangles, kaya ang quad ay binibilang bilang 2, at ang mesh na naguguhit nang higit sa isang beses ay binibilang isang beses kada kopya.
- Ang FBX file ay dapat binary FBX 7.1 o mas bago.
- Ang GLB o glTF file ay hindi dapat gumagamit ng Draco compression.

Name
target_formats
Type
string[]
Kinakailangan
Description
Ang mga file format na gagawin. Maglista ng hindi bababa sa isa. Kung nawawala o walang laman ang listahan, magbabalik ito ng 400.
Mga available na value:
- glb
- fbx
- obj
- usdz
- blend
- stl
- 3mf

Mga Ibinabalik

Ang result field ng response ay naglalaman ng ID ng bagong Convert task.

Mga Paraan ng Pagkabigo

Name
400 - Bad Request
Description
Hindi matakbo ang request. Sinasabi ng error message kung anong problema ang natagpuan. Halimbawa:
- Nawawalang parameter: Hindi ipinadala ang model_url o input_task_id.
- Nawawalang target_formats: Nawawala ang target_formats o walang nakalistang format.
- Di-wastong input task: Ang input_task_id ay hindi isang matagumpay na API task na may model file.
- Di-wastong model format: Ang model_url file ay may extension na hindi suportado.
- Hindi maabot na URL: Hindi ma-download ng Meshy ang model_url file.
- Masyadong malaki ang model file: Ang model_url file ay lampas sa 400 MB mula sa http o https URL, o lampas sa 100 MB bilang data URI.
- Masyadong maraming faces: Ang model_url file ay lampas 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 lampas sa 100 MB: Ang model_url file ay isang ASCII FBX na lampas sa 100 MB. Ipadala ito bilang binary FBX o GLB.
- Hindi mabasang model file: Ang model_url file ay lampas sa 100 MB, at hindi mabasa ng Meshy ang header nito. Halimbawa, ito ay isang Draco-compressed GLB o glTF, o isang binary FBX na mas luma sa 7.1.
- Masyadong kumplikado ang model header: Ang model_url file ay lampas sa 100 MB, at ang header nito ay may masyadong maraming meshes, nodes, o records na susuriin. Bawasan ang bilang ng mga object sa file, pagkatapos ay ipadala muli ito.
Ayusin ang request, pagkatapos ay ipadala muli ito. Tingnan ang Errors.
Name
401 - Unauthorized
Description
Nawawala o hindi wasto ang API key. Suriin ang Authorization header.
Name
402 - Payment Required
Description
Halimbawa:
- Hindi sapat na credits: Ang account ay walang sapat na credits para sa task na ito, o naabot ng account ang limitasyon ng credit. Suriin ang iyong balanse ng credit, pagkatapos ay subukan muli.
- Libreng plano: Ang paggawa ng task ay nangangailangan ng bayad na plano. I-upgrade ang iyong plano sa iyong subscription settings, pagkatapos ay subukan muli.
Name
403 - Forbidden
Description
Ang input_task_id ay isang bas-relief model, na hindi kayang i-convert ng endpoint na ito. Ang mensahe ay This model type does not support this operation. Magpadala ng ibang model.
Name
404 - Not Found
Description
Ang input_task_id ay hindi tumutugma sa alinman sa iyong mga task. Suriin ang task ID, pagkatapos ay ipadala muli ang request.
Name
429 - Too Many Requests
Description
Nalampasan mo ang iyong rate limit. Maghintay, pagkatapos ay subukan muli. Tingnan ang Rate limits.

GET/openapi/v1/convert/:id

Kumuha ng Convert task

Ibinabalik ang isang Convert task ayon sa ID nito.

Request

GET

/openapi/v1/convert/:id

curl https://api.meshy.ai/openapi/v1/convert/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "convert",
  "model_urls": {
      "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
      "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}

Mga Parameter

Name
id
Type
path
Description
Ang task ID mula sa create response.

Ibinabalik

Ang Convert task object.

DELETE/openapi/v1/convert/:id

I-delete ang isang Convert task

Permanenteng binubura ang isang Convert task, kasama na ang mga modelo at datos nito. Hindi mo na maaaring i-undo ang pagbura.

Request

DELETE

/openapi/v1/convert/:id

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/convert/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 keeps 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."
}

Path parameters

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

Status ng task

Ang pagbura sa isang PENDING na task ay nagre-refund ng mga credits na nagamit noong ginawa mo ito.

Ang isang IN_PROGRESS na task ay hindi maaaring i-delete. Ang kahilingan ay nagbabalik ng 409 Conflict, at patuloy na tumatakbo ang task. Hindi nagre-refund si Meshy para sa isang task na nasimulan na, kaya kapag dine-delete mo ito, mawawala sa iyo ang credits at ang resulta. Hintayin itong umabot sa SUCCEEDED, FAILED, o CANCELED, bago mo ito i-delete.

Ang pagbura sa isang task na nasa panghuling status (SUCCEEDED, FAILED, o CANCELED) ay hindi nagre-refund ng mga credits nito.

Mga Ibinabalik

200 OK kapag na-delete na ang task, o 409 Conflict kapag ang task ay IN_PROGRESS.

GET/openapi/v1/convert

List Convert tasks

Nagbabalik ng listahan ng iyong mga Convert task.

Request

GET

/openapi/v1/convert

curl https://api.meshy.ai/openapi/v1/convert?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "convert",
    "model_urls": {
      "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
      "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null,
    "consumed_credits": 1
  }
]

Mga Parameter

Name
page_num
Type
integer
default 1
Description
Ang numero ng pahinang ibabalik, hanggang 255. Ang mas malaking value ay nagbabalik ng 400.

Name
page_size
Type
integer
default 10
Description
Ang bilang ng mga task kada pahina, hanggang 100.

Name
sort_by
Type
string
Description
Ang pagkakaayos ng pag-uuri.
Mga available na value:
- +created_at: pinakaluma muna
- -created_at: pinakabago muna

Mga Ibabalik (Returns)

Isang paginated na listahan ng mga Convert task object.

GET/openapi/v1/convert/:id/stream

I-stream ang Convert task

Nagsi-stream ng mga update ng Convert task bilang Server-Sent Events (SSE).

Request

GET

/openapi/v1/convert/:id/stream

curl -N https://api.meshy.ai/openapi/v1/convert/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Message event examples illustrate task progress.
event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "convert",
  "model_urls": {
    "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
    "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}

Mga Parameter

Name
id
Type
path
Description
Ang task ID mula sa sagot ng create.

Ibinabalik

Isang stream ng Convert task objects bilang Server-Sent Events.

Bawat event ay naglalaman ng buong task object, sa parehong hugis na ibinabalik ng Get endpoint. Habang ang task ay PENDING o IN_PROGRESS, wala pang value ang mga field ng resulta nito.

The Convert task object

Ang isang Convert task object ay naglalarawan ng isang format conversion ng isang 3D model. Ito ang naghahawak ng status, ng progress, at ng mga model file kapag nagtagumpay ang task.

Properties

Name
id
Type
string
Description
Ang task ID. Ituring ito bilang isang opaque string, at huwag umasa sa format nito.
Name
type
Type
string
Description
Ang uri ng task, palaging convert.
Name
model_urls
Type
object
Description
Mga download URL para sa na-convert na model, isa para sa bawat file format. Ang mga format lamang na nasa target_formats ang may URL. Ang isang format na hindi mo hiniling ay walang key, sa halip na walang laman na string.
Name
progress
Type
integer
Description
Kung gaano karami ang natapos na sa task, bilang isang porsyento. Ito ay 0 hanggang magsimula ang task at 100 kapag ito ay nagtagumpay.
Name
status
Type
string
Description
Ang status ng task, isa sa PENDING, IN_PROGRESS, SUCCEEDED, FAILED, o CANCELED.
Name
preceding_tasks
Type
integer
Description
Ang bilang ng mga task na nauuna sa task na ito sa queue. Makabuluhan lamang ang value na ito habang ang task ay PENDING.
Name
created_at
Type
timestamp
Description
Oras nang likhain ang task, sa Unix milliseconds.
Name
started_at
Type
timestamp
Description
Oras nang magsimula ang task, sa Unix milliseconds. Ito ay 0 hanggang magsimula ang task.
Name
finished_at
Type
timestamp
Description
Oras nang matapos ang task, sa Unix milliseconds. Ito ay 0 hanggang matapos ang task.
Name
expires_at
Type
timestamp
Description
Oras na mag-e-expire ang mga download URL ng task, sa Unix milliseconds. Ito ay 0 hanggang matapos ang task.
Name
texture_urls
Type
array
Description
Mga download URL para sa mga texture map ng model, kapag nagtagumpay ang task: isang array ng mga object, isa para sa bawat texture set. Ang bawat object ay may base_color URL, at maaari ring magkaroon ng metallic, roughness, normal, emission, at metallic_roughness na mga URL. Ito ay null hanggang magtagumpay ang task, at isang walang laman na array kapag ang model ay walang texture map.
Name
task_error
Type
object
Description
Ang mga detalye ng error kapag nabigo ang task. Tingnan ang Errors.
Name
consumed_credits
Type
integer
Description
Ang bilang ng credits na ginamit ng task, na 1 para sa isang Convert task. Ito ay 0 para sa isang FAILED na task.