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

API Konversi

Konversi model 3D ke format file lain, dari task Meshy atau dari file model.

POST/openapi/v1/convert

Buat tugas Convert

Membuat tugas Convert. Tugas berjalan di latar belakang. Untuk informasi berapa lama tugas biasanya berlangsung, lihat Waktu pemrosesan.

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"
}

Parameter

  • Name
    input_task_id
    Type
    string
    Wajib
    Description

    Wajib diisi kecuali Anda mengirim model_url. ID dari sebuah tugas yang menghasilkan model 3D, misalnya tugas Teks ke 3D, Gambar ke 3D, Remesh, Ubah ukuran, atau Retexture. Tugas tersebut harus berasal dari API dan memiliki status SUCCEEDED.

  • Name
    model_url
    Type
    string
    Wajib
    Description

    Wajib diisi kecuali Anda mengirim input_task_id. Model yang akan dikonversi, berupa URL publik atau data URI. Jika Anda mengirim keduanya, Meshy akan menggunakan input_task_id.

    Model harus berupa file GLB, glTF, OBJ, FBX, atau STL dengan ukuran maksimal 400 MB dari URL http atau https, atau 100 MB sebagai data URI. Untuk data URI, gunakan MIME type application/octet-stream.

    File di atas 100 MB juga harus mengikuti aturan berikut:

    • File GLB, glTF, FBX, atau OBJ dapat memiliki maksimal 10.000.000 faces. Meshy menghitung faces sebagai segitiga, jadi satu quad dihitung sebagai 2, dan mesh yang digambar lebih dari sekali dihitung sekali per salinan.
    • File FBX harus berupa FBX biner versi 7.1 atau lebih baru.
    • File GLB atau glTF tidak boleh menggunakan kompresi Draco.
  • Name
    target_formats
    Type
    string[]
    Wajib
    Description

    Format file yang akan dihasilkan. Cantumkan setidaknya satu. Daftar yang hilang atau kosong akan mengembalikan 400.

    Nilai yang tersedia:

    • glb
    • fbx
    • obj
    • usdz
    • blend
    • stl
    • 3mf

Hasil

Kolom result pada respons berisi ID dari tugas Convert yang baru.

Mode kegagalan

  • Name
    400 - Bad Request
    Description

    Permintaan tidak dapat dijalankan. Pesan kesalahan menunjukkan masalah yang ditemukan. Contohnya:

    • Parameter hilang: Baik model_url maupun input_task_id tidak dikirim.
    • target_formats hilang: target_formats hilang atau tidak mencantumkan format apa pun.
    • Tugas input tidak valid: input_task_id bukan merupakan tugas API yang berhasil dengan file model.
    • Format model tidak valid: File model_url memiliki ekstensi yang tidak didukung.
    • URL tidak dapat dijangkau: Meshy tidak dapat mengunduh file model_url.
    • File model terlalu besar: File model_url berukuran di atas 400 MB dari URL http atau https, atau di atas 100 MB sebagai data URI.
    • Terlalu banyak faces: File model_url berukuran di atas 100 MB dan memiliki lebih dari 10.000.000 faces. Kurangi jumlah faces, lalu kirim ulang file tersebut.
    • FBX ASCII di atas 100 MB: File model_url adalah FBX ASCII di atas 100 MB. Kirim sebagai FBX biner atau GLB.
    • File model tidak dapat dibaca: File model_url berukuran di atas 100 MB, dan Meshy tidak dapat membaca headernya. Misalnya, file tersebut adalah GLB atau glTF yang dikompresi dengan Draco, atau FBX biner yang lebih lama dari versi 7.1.
    • Header model terlalu kompleks: File model_url berukuran di atas 100 MB, dan headernya memiliki terlalu banyak mesh, node, atau record untuk diperiksa. Kurangi jumlah objek dalam file, lalu kirim ulang.

    Perbaiki permintaan, lalu kirim ulang. Lihat Kesalahan.

  • Name
    401 - Unauthorized
    Description

    Kunci API hilang atau tidak valid. Periksa header Authorization.

  • Name
    402 - Payment Required
    Description

    Contohnya:

    • Kredit tidak cukup: Akun tidak memiliki cukup kredit untuk tugas ini, atau akun telah mencapai batas kredit. Periksa saldo kredit Anda, lalu coba lagi.
    • Paket gratis: Membuat tugas memerlukan paket berbayar. Tingkatkan paket Anda di pengaturan langganan, lalu coba lagi.
  • Name
    403 - Forbidden
    Description

    input_task_id adalah model bas-relief, yang tidak dapat dikonversi oleh endpoint ini. Pesannya adalah This model type does not support this operation. Kirim model yang berbeda.

  • Name
    404 - Not Found
    Description

    input_task_id tidak cocok dengan tugas Anda mana pun. Periksa ID tugas, lalu kirim ulang permintaan.

  • Name
    429 - Too Many Requests
    Description

    Anda melampaui batas laju Anda. Tunggu, lalu coba lagi. Lihat Batas laju.

GET/openapi/v1/convert/:id

Mendapatkan task Convert

Mengembalikan task Convert berdasarkan ID-nya.

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
}

Parameter

  • Name
    id
    Type
    path
    Description

    ID task dari respons pembuatan.

Returns

Objek task Convert.

DELETE/openapi/v1/convert/:id

Hapus task Convert

Menghapus task Convert secara permanen, termasuk model dan datanya. Anda tidak bisa membatalkan penghapusan ini.

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."
}

Parameter path

  • Name
    id
    Type
    path
    Description

    ID task yang akan dihapus.

Status task

Menghapus task PENDING akan mengembalikan kredit yang digunakan saat Anda membuatnya.

Task IN_PROGRESS tidak dapat dihapus. Permintaan akan mengembalikan 409 Conflict, dan task tersebut tetap berjalan. Meshy tidak mengembalikan kredit untuk task yang sudah dimulai, sehingga menghapusnya akan membuat Anda kehilangan kredit sekaligus hasilnya. Tunggu hingga task mencapai status SUCCEEDED, FAILED, atau CANCELED, baru kemudian hapus.

Menghapus task yang berada dalam status akhir (SUCCEEDED, FAILED, atau CANCELED) tidak akan mengembalikan kreditnya.

Returns

200 OK ketika task berhasil dihapus, atau 409 Conflict ketika task berstatus IN_PROGRESS.

GET/openapi/v1/convert

List Convert tasks

Mengembalikan daftar tugas Konversi Anda.

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
  }
]

Parameter

  • Name
    page_num
    Type
    integer
    default 1
    Description

    Nomor halaman yang akan dikembalikan, hingga 255. Nilai yang lebih besar akan mengembalikan 400.

  • Name
    page_size
    Type
    integer
    default 10
    Description

    Jumlah tugas per halaman, hingga 100.

  • Name
    sort_by
    Type
    string
    Description

    Urutan pengurutan.

    Nilai yang tersedia:

    • +created_at: terlama lebih dulu
    • -created_at: terbaru lebih dulu

Returns

Daftar berhalaman dari objek tugas Konversi.

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

Stream Tugas Convert

Melakukan streaming pembaruan tugas Convert sebagai 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
}

Parameter

  • Name
    id
    Type
    path
    Description

    ID tugas dari respons pembuatan.

Returns

Sebuah stream objek tugas Convert sebagai Server-Sent Events.

Setiap event memuat objek tugas secara lengkap, dalam bentuk yang sama seperti yang dikembalikan oleh endpoint Get. Selama tugas berstatus PENDING atau IN_PROGRESS, kolom hasilnya belum memiliki nilai.

Objek task Convert

Objek task Convert menjelaskan satu konversi format dari sebuah model 3D. Objek ini menyimpan status, progress, dan file model saat task berhasil.

Properties

  • Name
    id
    Type
    string
    Description

    ID task. Perlakukan sebagai string buram, dan jangan bergantung pada formatnya.

  • Name
    type
    Type
    string
    Description

    Tipe task, selalu convert.

  • Name
    model_urls
    Type
    object
    Description

    URL unduhan untuk model yang telah dikonversi, satu per format file. Hanya format dalam target_formats yang memiliki URL. Format yang tidak Anda minta tidak memiliki key, bukannya string kosong.

  • Name
    progress
    Type
    integer
    Description

    Seberapa banyak task telah selesai, dalam persentase. Nilainya 0 sampai task dimulai dan 100 saat task berhasil.

  • Name
    status
    Type
    string
    Description

    Status task, salah satu dari PENDING, IN_PROGRESS, SUCCEEDED, FAILED, atau CANCELED.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Jumlah task yang berada di depan task ini dalam antrean. Nilai ini hanya bermakna selama task masih PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

    Waktu task dibuat, dalam milidetik Unix.

  • Name
    started_at
    Type
    timestamp
    Description

    Waktu task dimulai, dalam milidetik Unix. Nilainya 0 sampai task dimulai.

  • Name
    finished_at
    Type
    timestamp
    Description

    Waktu task selesai, dalam milidetik Unix. Nilainya 0 sampai task selesai.

  • Name
    expires_at
    Type
    timestamp
    Description

    Waktu URL unduhan task ini kedaluwarsa, dalam milidetik Unix. Nilainya 0 sampai task selesai.

  • Name
    texture_urls
    Type
    array
    Description

    URL unduhan untuk peta tekstur model, saat task berhasil: sebuah array objek, satu per set tekstur. Setiap objek memiliki URL base_color, dan juga bisa memiliki URL metallic, roughness, normal, emission, dan metallic_roughness. Nilainya null sampai task berhasil, dan array kosong saat model tidak memiliki peta tekstur.

  • Name
    task_error
    Type
    object
    Description

    Detail kesalahan saat task gagal. Lihat Kesalahan.

  • Name
    consumed_credits
    Type
    integer
    Description

    Jumlah kredit yang digunakan task, yaitu 1 untuk task Convert. Nilainya 0 untuk task FAILED.