Convert API

Pinapayagan ka ng Convert API na i-convert ang mga umiiral na 3D na modelo sa iba't ibang format ng file.

POST/openapi/v1/convert

Create a Convert Task

Ang endpoint na ito ay gumagawa ng bagong task para sa pag-convert ng format.

Mga Parameter

Isa lang sa input_task_id o model_url ang kinakailangan. Kung ibinigay ang dalawa, ang input_task_id ang magiging priority.

  • Name
    input_task_id
    Type
    string
    Kinakailangan
    Description

    Ang ID ng isang natapos na Meshy task na ang modelo nito ay nais mong i-convert. Ang task ay dapat may status na SUCCEEDED.

  • Name
    model_url
    Type
    string
    Kinakailangan
    Description

    Isang publicly accessible URL 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.

  • Name
    target_formats
    Type
    string[]
    Kinakailangan
    Description

    Isang listahan ng mga output format para sa na-convert na modelo. Mga available na value: glb, fbx, obj, usdz, blend, stl, 3mf.

Mga Ibinabalik

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

Mga Sitwasyon ng Kabiguan

  • 400 - Bad Request

Ang request ay hindi katanggap-tanggap. Karaniwang mga sanhi:

  • Missing parameter: Alinman sa model_url o input_task_id ay dapat ibigay.
  • Missing target_formats: Dapat magtakda ng kahit isang target format.
  • Invalid input task: Ang input_task_id ay dapat tumutukoy sa isang matagumpay na task.
  • Invalid model format: Ang model_url ay tumuturo sa isang file na may extension na hindi suportado.
  • Unreachable URL: Hindi ma-download ang model_url.
  • 401 - Unauthorized

Nabigo ang authentication. Pakisuri ang iyong API key.

  • 402 - Payment Required

Hindi sapat na credits upang isagawa ang task na ito.

  • 429 - Too Many Requests

Lumampas ka na sa iyong rate limit.

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"
}
GET/openapi/v1/convert/:id

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

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": {
      "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/openapi/v1/convert/:id

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

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 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/convert

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 100 na 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

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
  }
]
GET/openapi/v1/convert/:id/stream

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

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
}

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.