lowpoly akan dihentikan pada 30 Okt 2026. Tukar model sebelum tarikh-tarikh ini untuk mengelakkan ralat permintaan.

API Tukar

API Tukar membolehkan anda menukar model 3D sedia ada kepada format fail yang berbeza.

POST/openapi/v1/convert

Cipta Tugas Convert

Endpoint ini mencipta tugas penukaran format yang baharu.

Tugas ini berjalan di latar belakang. Untuk tempoh masa yang biasanya diambil, lihat Masa Pemprosesan.

Parameter

Hanya salah satu daripada input_task_id atau model_url yang diperlukan. Jika kedua-duanya disediakan, input_task_id akan diutamakan.

  • Name
    input_task_id
    Type
    string
    Diperlukan
    Description

    ID bagi tugas Meshy yang telah selesai yang jejaringnya ingin anda tukar. Tugas tersebut mestilah berstatus SUCCEEDED.

  • Name
    model_url
    Type
    string
    Diperlukan
    Description

    URL yang boleh diakses secara awam atau data URI yang menunjuk kepada fail model 3D. Format yang disokong: .glb, .gltf, .obj, .fbx, .stl. Untuk Data URI, gunakan MIME type: application/octet-stream.

    Saiz fail maksimum: 400 MB untuk URL http atau https, 100 MB untuk URI data:.

    Fail GLB, glTF, FBX atau OBJ yang melebihi 100 MB boleh mempunyai paling banyak 10,000,000 muka. Muka dikira sebagai segi tiga: segi empat dikira sebagai 2, dan jejaring yang dilukis lebih daripada sekali dikira sekali bagi setiap salinan. Melebihi 100 MB, fail FBX mestilah FBX binari 7.1 atau lebih baharu, dan fail GLB atau glTF tidak boleh menggunakan mampatan Draco.

  • Name
    target_formats
    Type
    string[]
    Diperlukan
    Description

    Senarai format output untuk model yang ditukar. Nilai yang tersedia: glb, fbx, obj, usdz, blend, stl, 3mf.

Pulangan

Sifat result dalam respons mengandungi id bagi tugas convert yang baharu dicipta.

Mod Kegagalan

  • 400 - Bad Request

Permintaan tidak dapat diterima. Punca biasa:

  • Parameter tiada: Sama ada model_url atau input_task_id mesti disediakan.
  • target_formats tiada: Sekurang-kurangnya satu format sasaran mesti dinyatakan.
  • Tugas input tidak sah: input_task_id mesti merujuk kepada tugas yang berjaya.
  • Format model tidak sah: model_url menunjuk kepada fail dengan sambungan yang tidak disokong.
  • URL tidak dapat dicapai: model_url tidak dapat dimuat turun.
  • Fail model terlalu besar: Fail model_url melebihi 400 MB (URL http atau https) atau 100 MB (URI data:).
  • Terlalu banyak muka: Fail model_url melebihi 100 MB dan mempunyai lebih daripada 10,000,000 muka. Kurangkan bilangan muka, kemudian hantar semula fail tersebut.
  • FBX ASCII melebihi 100 MB: Fail model_url ialah FBX ASCII yang melebihi 100 MB. Hantar sebagai FBX binari atau GLB.
  • Fail model tidak boleh dibaca: Fail model_url melebihi 100 MB dan pengepalanya tidak dapat dibaca, contohnya GLB atau glTF yang dimampatkan Draco, atau FBX binari yang lebih lama daripada 7.1.
  • Pengepala model terlalu kompleks: Fail model_url melebihi 100 MB dan pengepalanya mempunyai terlalu banyak jejaring, nod atau rekod untuk disemak. Kurangkan bilangan objek dalam fail tersebut, kemudian hantar semula.
  • 401 - Unauthorized

Pengesahan gagal. Sila semak kunci API anda.

  • 402 - Payment Required

Kredit tidak mencukupi untuk melaksanakan tugas ini.

  • 429 - Too Many Requests

Anda telah melebihi had kadar anda.

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

Dapatkan Semula Tugas Convert

Endpoint ini mendapatkan semula tugas convert mengikut ID-nya.

Parameter

  • Name
    id
    Type
    path
    Description

    ID bagi tugas convert yang hendak didapatkan semula.

Nilai Pulangan

Objek Convert Task.

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

Padam Tugas Tukar

Endpoint ini memadam tugas tukar secara kekal, termasuk semua model dan data yang berkaitan. Tindakan ini tidak boleh diterbalikkan.

Parameter Laluan

  • Name
    id
    Type
    path
    Description

    ID tugas tukar yang hendak dipadam.

Status Tugas

Tugas yang masih PENDING akan dipadam dan kredit yang digunakan semasa ia dicipta akan dikembalikan.

Tugas yang sudah IN_PROGRESS tidak boleh dipadam: permintaan tersebut ditolak dengan 409 Conflict dan tugas itu terus berjalan. Kredit bagi tugas yang telah mula diproses oleh worker tidak boleh dikembalikan, jadi memadamnya semasa ia sedang berjalan akan menyebabkan anda kehilangan kredit dan hasilnya sekali. Tunggu sehingga ia mencapai status SUCCEEDED, FAILED atau CANCELED, kemudian padamkannya.

Tugas yang berada dalam status akhir (SUCCEEDED, FAILED atau CANCELED) akan dipadam tanpa bayaran balik.

Pemulangan

Mengembalikan 200 OK apabila berjaya, atau 409 Conflict apabila tugas tersebut sedang 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

Senaraikan Tugas Tukar

Endpoint ini membolehkan anda mendapatkan senarai tugas tukar.

Parameter

  • Name
    page_num
    Type
    integer
    lalai 1
    Description

    Nombor halaman untuk penomboran halaman.

  • Name
    page_size
    Type
    integer
    lalai 10
    Description

    Had saiz halaman. Maksimum yang dibenarkan adalah 100 item.

  • Name
    sort_by
    Type
    string
    Description

    Medan untuk diisih mengikut. Nilai yang tersedia:

    • +created_at: Isih mengikut masa penciptaan secara menaik.
    • -created_at: Isih mengikut masa penciptaan secara menurun.

Nilai Pulangan

Mengembalikan senarai bernomboran halaman bagi Objek Tugas Tukar.

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

Alirkan Tugas Convert

Endpoint ini mengalirkan kemas kini masa nyata untuk tugas convert menggunakan Server-Sent Events (SSE).

Parameter

  • Name
    id
    Type
    path
    Description

    Pengenal unik untuk tugas convert yang hendak dialirkan.

Nilai Pulangan

Memulangkan aliran Objek Tugas Convert sebagai Server-Sent Events.

Bagi tugas berstatus PENDING atau IN_PROGRESS, aliran respons hanya akan mengandungi medan progress dan status yang diperlukan.

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
}

Objek Tugas Convert

Objek Tugas Convert mewakili satu tugas penukaran format.

Sifat-sifat

  • id · string

Pengenal unik untuk tugas tersebut.

  • type · string

Jenis tugas. Nilainya adalah convert.

  • model_urls · object

URL yang boleh dimuat turun untuk fail model yang telah ditukar. Hanya format yang dinyatakan dalam target_formats akan mempunyai URL. Sifat format lain akan menjadi rentetan kosong.

  • progress · integer

Progress tugas tersebut (0-100).

  • status · string

Status tugas tersebut. Nilai yang mungkin: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • preceding_tasks · integer

Bilangan tugas yang mendahului. Hanya bermakna apabila status adalah PENDING.

  • created_at · timestamp

Cap masa bila tugas tersebut dicipta, dalam milisaat.

  • started_at · timestamp

Cap masa bila tugas tersebut dimulakan, dalam milisaat. 0 jika belum dimulakan.

  • finished_at · timestamp

Cap masa bila tugas tersebut selesai, dalam milisaat. 0 jika belum selesai.

  • task_error · object

Objek ralat jika tugas tersebut gagal. Lihat Ralat untuk maklumat lanjut.

  • consumed_credits · integer

Bilangan kredit yang digunakan oleh tugas ini (1 kredit bagi setiap tugas convert). Mengembalikan 0 untuk tugas FAILED.