lowpoly dihentikan pada 30 Okt 2026. Ganti model sebelum tanggal-tanggal ini agar permintaan tidak error.

Convert API

Convert API memungkinkan Anda melakukan Konversi model 3D yang sudah ada ke format file yang berbeda.

POST/openapi/v1/convert

Buat Convert Task

Endpoint ini membuat task konversi format baru.

Task berjalan di latar belakang. Untuk mengetahui berapa lama biasanya hal ini berlangsung, lihat Waktu Pemrosesan.

Parameter

Hanya salah satu dari input_task_id atau model_url yang wajib diisi. Jika keduanya disediakan, input_task_id memiliki prioritas.

  • Name
    input_task_id
    Type
    string
    Wajib
    Description

    ID dari task Meshy yang telah selesai yang model-nya ingin Anda konversi. Task tersebut harus memiliki status SUCCEEDED.

  • Name
    model_url
    Type
    string
    Wajib
    Description

    URL yang dapat diakses secara publik atau data URI yang mengarah ke file model 3D. Format yang didukung: .glb, .gltf, .obj, .fbx, .stl. Untuk Data URI, gunakan MIME type: application/octet-stream.

    Ukuran file maksimum: 400 MB untuk URL http atau https, 100 MB untuk URI data:.

    File GLB, glTF, FBX atau OBJ yang berukuran lebih dari 100 MB dapat memiliki paling banyak 10.000.000 face. Face dihitung sebagai segitiga: satu quad dihitung sebagai 2, dan sebuah mesh yang digambar lebih dari sekali dihitung satu kali per salinan. Di atas 100 MB, file FBX harus berupa binary FBX 7.1 atau yang lebih baru, dan file GLB atau glTF tidak boleh menggunakan kompresi Draco.

  • Name
    target_formats
    Type
    string[]
    Wajib
    Description

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

Nilai yang Dikembalikan

Properti result dari respons berisi id dari convert task yang baru dibuat.

Mode Kegagalan

  • 400 - Bad Request

Permintaan tidak dapat diterima. Penyebab umum:

  • Parameter hilang: Salah satu dari model_url atau input_task_id harus disediakan.
  • target_formats hilang: Setidaknya satu format target harus ditentukan.
  • Input task tidak valid: input_task_id harus merujuk pada task yang berhasil.
  • Format model tidak valid: model_url mengarah ke file dengan ekstensi yang tidak didukung.
  • URL tidak dapat dijangkau: model_url tidak dapat diunduh.
  • File model terlalu besar: File model_url melebihi 400 MB (URL http atau https) atau 100 MB (URI data:).
  • Terlalu banyak face: File model_url berukuran lebih dari 100 MB dan memiliki lebih dari 10.000.000 face. Kurangi jumlah face, lalu kirim ulang file tersebut.
  • ASCII FBX lebih dari 100 MB: File model_url adalah ASCII FBX yang berukuran lebih dari 100 MB. Kirim sebagai binary FBX atau GLB.
  • File model tidak dapat dibaca: File model_url berukuran lebih dari 100 MB dan header-nya tidak dapat dibaca, misalnya GLB atau glTF yang terkompresi Draco, atau binary FBX yang lebih lama dari 7.1.
  • Header model terlalu kompleks: File model_url berukuran lebih dari 100 MB dan header-nya memiliki terlalu banyak mesh, node, atau record untuk diperiksa. Kurangi jumlah objek dalam file, lalu kirim ulang.
  • 401 - Unauthorized

Autentikasi gagal. Silakan periksa kunci API Anda.

  • 402 - Payment Required

Kredit tidak cukup untuk melakukan task ini.

  • 429 - Too Many Requests

Anda telah melebihi batas laju 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

Mengambil Task Konversi

Endpoint ini mengambil task konversi berdasarkan ID-nya.

Parameter

  • Name
    id
    Type
    path
    Description

    ID dari task konversi yang akan diambil.

Returns

Objek Task Konversi.

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

Menghapus Convert Task

Endpoint ini menghapus secara permanen sebuah convert task, termasuk semua model dan data yang terkait. Tindakan ini tidak dapat dibatalkan.

Path Parameters

  • Name
    id
    Type
    path
    Description

    ID dari convert task yang akan dihapus.

Status Task

Task yang masih berstatus PENDING akan dihapus dan kredit yang digunakan saat pembuatan akan dikembalikan.

Task yang sudah berstatus IN_PROGRESS tidak dapat dihapus: permintaan akan ditolak dengan 409 Conflict dan task akan tetap berjalan. Kredit untuk task yang sudah mulai diproses oleh worker tidak dapat dikembalikan, sehingga menghapusnya saat masih berjalan akan membuat Anda kehilangan kredit sekaligus hasilnya. Tunggu hingga statusnya mencapai SUCCEEDED, FAILED, atau CANCELED, baru kemudian hapus.

Task dengan status akhir (SUCCEEDED, FAILED, atau CANCELED) akan dihapus tanpa pengembalian kredit.

Returns

Mengembalikan 200 OK jika berhasil, atau 409 Conflict ketika task berstatus 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

Daftar Tugas Convert

Endpoint ini memungkinkan Anda mengambil daftar tugas convert.

Parameter

  • Name
    page_num
    Type
    integer
    default 1
    Description

    Nomor halaman untuk paginasi.

  • Name
    page_size
    Type
    integer
    default 10
    Description

    Batas ukuran halaman. Maksimal yang diizinkan adalah 100 item.

  • Name
    sort_by
    Type
    string
    Description

    Kolom untuk pengurutan. Nilai yang tersedia:

    • +created_at: Urutkan berdasarkan waktu pembuatan secara ascending.
    • -created_at: Urutkan berdasarkan waktu pembuatan secara descending.

Returns

Mengembalikan daftar berpaginasi dari 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

Stream a Convert Task

Endpoint ini melakukan streaming pembaruan secara real-time untuk sebuah tugas konversi menggunakan Server-Sent Events (SSE).

Parameter

  • Name
    id
    Type
    path
    Description

    Pengenal unik untuk tugas konversi yang akan di-stream.

Returns

Mengembalikan sebuah stream berisi The Convert Task Objects sebagai Server-Sent Events.

Untuk tugas dengan status PENDING atau IN_PROGRESS, stream respons hanya akan menyertakan field 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 Convert Task

Objek Convert Task merepresentasikan pekerjaan konversi format.

Properties

  • id · string

Pengenal unik untuk tugas ini.

  • type · string

Jenis tugas. Nilainya adalah convert.

  • model_urls · object

URL yang dapat diunduh untuk file model hasil konversi. Hanya format yang ditentukan dalam target_formats yang akan memiliki URL. Properti format lainnya akan berupa string kosong.

  • progress · integer

Progress dari tugas ini (0-100).

  • status · string

Status dari tugas ini. Kemungkinan nilai: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • preceding_tasks · integer

Jumlah tugas yang mendahului. Hanya berarti ketika status adalah PENDING.

  • created_at · timestamp

Stempel waktu saat tugas dibuat, dalam milidetik.

  • started_at · timestamp

Stempel waktu saat tugas dimulai, dalam milidetik. 0 jika belum dimulai.

  • finished_at · timestamp

Stempel waktu saat tugas selesai, dalam milidetik. 0 jika belum selesai.

  • task_error · object

Objek kesalahan jika tugas gagal. Lihat Errors untuk detail lebih lanjut.

  • consumed_credits · integer

Jumlah kredit yang dikonsumsi oleh tugas ini (1 kredit per tugas convert). Mengembalikan 0 untuk tugas FAILED.