API Konversi

API Konversi memungkinkan Anda untuk mengonversi model 3D yang ada ke dalam format file yang berbeda.

POST/openapi/v1/convert

Membuat Tugas Konversi

Endpoint ini membuat tugas konversi format baru.

Parameter

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

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

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

Pengembalian

Properti result dari respons berisi id dari tugas konversi 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.
Tugas input tidak valid: input_task_id harus merujuk pada 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 melakukan tugas ini.

429 - Too Many Requests

Anda telah melebihi batas laju Anda.

Permintaan

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

Respons

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

GET/openapi/v1/convert/:id

Mengambil Tugas Konversi

Endpoint ini mengambil tugas konversi berdasarkan ID-nya.

Parameter

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

Mengembalikan

Objek Tugas Konversi.

Permintaan

GET

/openapi/v1/convert/:id

curl https://api.meshy.ai/openapi/v1/convert/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Respon

{
  "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 secara permanen menghapus tugas konversi, termasuk semua model dan data yang terkait. Tindakan ini tidak dapat dibatalkan.

Parameter Jalur

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

Mengembalikan

Mengembalikan 200 OK jika berhasil.

Permintaan

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

Respon

// Returns 200 Ok on success.

GET/openapi/v1/convert

Daftar Tugas Konversi

Endpoint ini memungkinkan Anda untuk 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 naik.
- -created_at: Urutkan berdasarkan waktu pembuatan dalam urutan turun.

Mengembalikan

Mengembalikan daftar dengan paginasi dari Objek Tugas Konversi.

Permintaan

GET

/openapi/v1/convert

curl https://api.meshy.ai/openapi/v1/convert?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Respon

[
  {
    "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 mengalirkan pembaruan real-time untuk tugas konversi menggunakan Server-Sent Events (SSE).

Parameter

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

Mengembalikan

Mengembalikan aliran Objek Tugas Konversi sebagai Server-Sent Events.

Untuk tugas PENDING atau IN_PROGRESS, aliran respons hanya akan menyertakan bidang progress dan status yang diperlukan.

Permintaan

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

Aliran Respons

// 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 mewakili pekerjaan konversi format.

Properti

id · string

Pengidentifikasi unik untuk tugas ini.

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 dari tugas (0-100).

status · string

Status dari tugas. Nilai yang mungkin: 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 lebih jelasnya.

consumed_credits · integer

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