Convert API
Pinapayagan ka ng Convert API na i-convert ang mga umiiral na 3D na modelo sa iba't ibang format ng file.
Create a Convert Task
Ang endpoint na ito ay gumagawa ng bagong format conversion task.
Ang task ay tumatakbo sa background. Para malaman kung gaano karaming oras ang karaniwang kinakailangan, tingnan ang Processing Times.
Mga Parameter
Isa lamang sa input_task_id o model_url ang required. Kung parehong ibinigay, ang input_task_id ang mauuna.
- Name
- input_task_id
- Type
- string
- Kinakailangan
- Description
Ang ID ng isang kumpletong Meshy task na ang mesh nito ay gusto mong i-convert. Dapat ang status ng task ay
SUCCEEDED.
- Name
- model_url
- Type
- string
- Kinakailangan
- Description
Isang URL na pwedeng ma-access ng publiko o data URI na tumuturo sa isang 3D model file. Mga sinusuportahang format:
.glb,.gltf,.obj,.fbx,.stl. Para sa Data URIs, gamitin ang MIME type:application/octet-stream.Maximum na laki ng file: 400 MB para sa
httpohttpsURL, 100 MB para sadata: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 bawat kopya. 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[]
- Kinakailangan
- Description
Isang listahan ng mga output format para sa na-convert na mesh. Mga available na value:
glb,fbx,obj,usdz,blend,stl,3mf.
Mga Ibinabalik
Ang result property ng response ay naglalaman ng id ng bagong gawang convert task.
Mga Mode ng Kabiguan
400 - Bad Request
Ang request ay hindi katanggap-tanggap. Mga karaniwang dahilan:
- Nawawalang parameter: Dapat ibigay alinman sa
model_urloinput_task_id. - Nawawalang target_formats: Dapat magtakda ng kahit isang target format.
- Hindi valid na input task: Ang
input_task_iday dapat tumutukoy sa isang matagumpay na task. - Hindi valid na format ng mesh: Ang
model_urlay tumuturo sa isang file na may hindi sinusuportahang extension. - Hindi ma-reach na URL: Hindi ma-download ang
model_url. - Masyadong malaki ang mesh file: Ang
model_urlfile ay lumampas sa 400 MB (httpohttpsURL) o 100 MB (data:URI). - Masyadong maraming faces: Ang
model_urlfile 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_urlfile ay isang ASCII FBX na higit sa 100 MB. Ipadala ito bilang binary FBX o GLB. - Hindi mabasang mesh file: Ang
model_urlfile ay higit sa 100 MB at hindi mabasa ang header nito, halimbawa isang Draco-compressed GLB o glTF, o isang binary FBX na mas luma kaysa 7.1. - Masyadong komplikado ang header ng mesh: Ang
model_urlfile ay higit 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.
401 - Unauthorized
Nabigo ang authentication. Pakisuri ang iyong API key.
402 - Payment Required
Hindi sapat na credits para gawin ang task na ito.
429 - Too Many Requests
Nalampasan mo na ang iyong rate limit.
Request
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"
}
Kunin ang Convert Task
Kinukuha ng endpoint na ito ang isang convert task gamit ang ID nito.
Mga Parameter
- Name
- id
- Type
- path
- Description
Ang ID ng convert task na kukunin.
Ibinabalik
Ang Convert Task object.
Request
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": {
"glb": "",
"fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
"obj": "",
"usdz": "",
"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
}
Delete a Convert Task
Ang endpoint na ito ay permanenteng magtatanggal ng convert task, kasama na ang lahat ng kaugnay na mga modelo at datos. Ang aksyong ito ay hindi na maibabalik.
Path Parameters
- Name
- id
- Type
- path
- Description
Ang ID ng convert task na tatanggalin.
Katayuan ng Task
Ang isang task na PENDING pa ay tatanggalin at ang mga credits na nagamit
sa oras ng paglikha nito ay isasauli.
Ang isang task na IN_PROGRESS na ay hindi maaaring tanggalin: ang kahilingan ay
tinatanggihan ng 409 Conflict at ang task ay patuloy na tatakbo. Ang mga credits para sa isang task
na nasimulan na ng worker ay hindi na maibabalik, kaya kung tatanggalin ito habang tumatakbo
ay mawawalan ka ng credits at ng resulta pareho. Hintayin muna itong umabot sa
SUCCEEDED, FAILED o CANCELED, bago ito tanggalin.
Ang isang task na nasa terminal state (SUCCEEDED, FAILED o CANCELED) ay tatanggalin
nang walang refund.
Ibinabalik
Ibinabalik ang 200 OK kapag matagumpay, o 409 Conflict kapag ang task ay
IN_PROGRESS.
Request
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 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."
}
Ilista ang mga Convert Task
Ang endpoint na ito ay nagbibigay-daan sa iyo na kumuha ng listahan ng mga convert task.
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 ng laki ng pahina. Ang pinakamataas na pinapayagan ay
100na item.
- Name
- sort_by
- Type
- string
- Description
Field na gagamitin sa pag-uuri. Mga magagamit na value:
+created_at: Iuri ayon sa oras ng paglikha nang pataas (ascending).-created_at: Iuri ayon sa oras ng paglikha nang pababa (descending).
Ibinabalik
Nagbabalik ng paginated na listahan ng The Convert Task Objects.
Request
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
}
]
Mag-stream ng Convert Task
Ang endpoint na ito ay nag-stream ng real-time na mga update para sa isang convert task gamit ang Server-Sent Events (SSE).
Mga Parameter
- Name
- id
- Type
- path
- Description
Natatanging identifier para sa convert task na i-stream.
Mga Ibabalik
Nagbabalik ng stream ng The Convert Task Objects bilang Server-Sent Events.
Para sa mga task na PENDING o IN_PROGRESS, ang response stream ay maglalaman lamang ng kinakailangang mga field na progress at status.
Request
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
}
Ang Convert Task Object
Ang Convert Task object ay kumakatawan sa isang format conversion job.
Properties
id· string
Ang natatanging identifier para sa task.
type· string
Uri ng task. Ang value ay convert.
model_urls· object
Mga na-download na URL para sa na-convert na model files. Ang mga format lang na tinukoy sa target_formats ang magkakaroon ng URLs. Ang ibang format properties ay magiging empty strings.
progress· integer
Progress ng task (0-100).
status· string
Status ng task. Mga posibleng value: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
preceding_tasks· integer
Ang bilang ng mga naunang task. Makabuluhan lamang kapag ang status ay PENDING.
created_at· timestamp
Timestamp kung kailan ginawa ang task, sa milliseconds.
started_at· timestamp
Timestamp kung kailan nagsimula ang task, sa milliseconds. 0 kung hindi pa nagsimula.
finished_at· timestamp
Timestamp kung kailan natapos ang task, sa milliseconds. 0 kung hindi pa natatapos.
task_error· object
Error object kung nabigo ang task. Tingnan ang Errors para sa karagdagang detalye.
consumed_credits· integer
Ang bilang ng credits na ginamit ng task na ito (1 credit kada convert task). Nagbabalik ng 0 para sa mga FAILED na task.