API Konversi

API Konversi memungkinkan Anda mengonversi model 3D yang sudah ada ke dalam berbagai format file.

POST/openapi/v1/convert

Buat Tugas Konversi

Endpoint ini membuat tugas konversi format baru.

Parameter

Hanya salah satu dari input_task_id atau model_url yang wajib. Jika keduanya diberikan, input_task_id akan mendapat prioritas.

Name
input_task_id
Type
string
Wajib
Description
ID dari tugas Meshy yang telah selesai dan modelnya ingin Anda konversi. Tugas tersebut harus memiliki status SUCCEEDED.

Name
model_url
Type
string
Wajib
Description
URL yang dapat diakses 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.

Name
target_formats
Type
string[]
Wajib
Description
Daftar format output untuk model yang dikonversi. Nilai yang tersedia: glb, fbx, obj, usdz, blend, stl, 3mf.

Mengembalikan

Properti result dari respons berisi id dari tugas konversi yang baru dibuat.

Mode Kegagalan

400 - Bad Request

Permintaan tidak dapat diterima. Penyebab umum:

Parameter tidak ada: Salah satu dari model_url atau input_task_id harus diberikan.
target_formats tidak ada: Setidaknya satu format target harus ditentukan.
Tugas input tidak valid: input_task_id harus merujuk ke tugas 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.

401 - Unauthorized

Autentikasi gagal. Silakan periksa kunci API Anda.

402 - Payment Required

Kredit tidak mencukupi untuk menjalankan tugas ini.

429 - Too Many Requests

Anda telah melampaui 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

Ambil Tugas Konversi

endpoint ini mengambil tugas konversi berdasarkan ID-nya.

Parameter

Name
id
Type
path
Description
ID tugas konversi yang akan diambil.

Mengembalikan

Objek Tugas 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

Hapus Tugas Konversi

Endpoint ini menghapus secara permanen tugas konversi, termasuk semua model dan data terkait. Tindakan ini tidak dapat dibatalkan.

Parameter Path

Name
id
Type
path
Description
ID tugas konversi yang akan dihapus.

Mengembalikan

Mengembalikan 200 OK jika berhasil.

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

// Returns 200 Ok on success.

GET/openapi/v1/convert

Daftar Tugas Konversi

Endpoint ini memungkinkan Anda mengambil daftar tugas konversi.

Parameter

Name
page_num
Type
integer
default 1
Description
Nomor halaman untuk paginasi.

Name
page_size
Type
integer
default 10
Description
Batas ukuran halaman. Maksimum yang diizinkan adalah 50 item.

Name
sort_by
Type
string
Description
Bidang untuk pengurutan. Nilai yang tersedia:
- +created_at: Urutkan berdasarkan waktu pembuatan dalam urutan menaik.
- -created_at: Urutkan berdasarkan waktu pembuatan dalam urutan menurun.

Mengembalikan

Mengembalikan daftar terpaginasi dari Objek Tugas Konversi.

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

Streaming Tugas Konversi

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

Parameter

Name
id
Type
path
Description
Pengidentifikasi unik untuk tugas konversi yang akan di-stream.

Mengembalikan

Mengembalikan stream Objek Tugas Konversi sebagai Server-Sent Events.

Untuk tugas PENDING atau IN_PROGRESS, stream respons hanya akan menyertakan bidang 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 Konversi

Objek Tugas Konversi merepresentasikan tugas konversi format.

Properti

id · string

Pengidentifikasi unik untuk tugas.

type · string

Jenis tugas. Nilainya adalah convert.

model_urls · object

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

progress · integer

Progress tugas (0-100).

status · string

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

preceding_tasks · integer

Jumlah tugas sebelumnya. Bermakna hanya 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 Kesalahan untuk detail lebih lanjut.

consumed_credits · integer

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