Convert API

Convert API memungkinkan Anda melakukan Konversi model 3D yang sudah ada ke 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 wajib diisi. Jika keduanya diberikan, 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 yang dapat diakses publik atau data URI yang menunjuk 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.

Return

Properti result pada 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 diberikan.
  • 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 menunjuk 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 cukup untuk melakukan tugas 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.