Resize API

API Resize memungkinkan Anda untuk Ubah ukuran model 3D yang sudah ada ke dimensi dunia nyata. Anda dapat menentukan tinggi yang tepat, batasan sisi terpanjang, atau membiarkan AI secara otomatis memperkirakan ukuran yang sesuai.

POST/openapi/v1/resize

Membuat Resize Task

Endpoint ini membuat resize task baru.

Parameter

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

Name
input_task_id
Type
string
Wajib
Description
ID dari task Meshy yang telah selesai dan modelnya ingin Anda ubah ukuran. Task tersebut harus memiliki status SUCCEEDED. Format output akan berupa GLB.

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. Format output akan mempertahankan format asli dari model input.

Tepat satu mode resize diperlukan: resize_height, resize_longest_side, atau auto_size. Ketiga parameter ini bersifat mutually exclusive (saling eksklusif).

Name
resize_height
Type
number
Description
Mengubah ukuran model menjadi tinggi tertentu yang diukur dalam meter.

Name
resize_longest_side
Type
number
Description
Mengubah ukuran model sehingga sisi terpanjangnya sesuai dengan nilai ini, diukur dalam meter. Rasio aspek dipertahankan.

Name
auto_size
Type
boolean
Description
Ketika disetel ke true, layanan ini menggunakan AI vision untuk secara otomatis memperkirakan tinggi objek di dunia nyata dan mengubah ukuran model sesuai dengan itu. Titik asal akan default ke bottom kecuali origin_at disetel secara eksplisit.

Name
origin_at
Type
string
default bottom
Description
Posisi titik asal setelah pengubahan ukuran.
Nilai yang tersedia: bottom, center.

Pengembalian

Properti result dari respons berisi id dari resize 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.
Mode resize hilang: Setidaknya satu dari resize_height, resize_longest_side, atau auto_size harus ditentukan.
Parameter yang saling eksklusif: resize_height, resize_longest_side, dan auto_size tidak dapat digabungkan.
Task input tidak valid: input_task_id harus mengacu pada task yang berhasil.
Format model tidak valid: model_url mengarah ke file dengan ekstensi yang tidak didukung.
URL tidak dapat diakses: model_url tidak dapat diunduh.

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 melampaui batas laju Anda.

Request

POST

/openapi/v1/resize

# Simple: resize to a specific height
curl https://api.meshy.ai/openapi/v1/resize \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "resize_height": 1.8
  }'

# Advanced: resize longest side with custom origin
curl https://api.meshy.ai/openapi/v1/resize \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "model_url": "https://example.com/model.glb",
    "resize_longest_side": 2.0,
    "origin_at": "center"
  }'

Response

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

GET/openapi/v1/resize/:id

Mengambil Tugas Ubah ukuran

Endpoint ini mengambil tugas ubah ukuran berdasarkan ID-nya.

Parameter

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

Returns

Objek Tugas Ubah ukuran.

Request

GET

/openapi/v1/resize/:id

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "resize",
  "model_urls": {
      "glb": "https://assets.meshy.ai/.../model.glb?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}

DELETE/openapi/v1/resize/:id

Menghapus Tugas Ubah ukuran

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

Parameter Path

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

Status Tugas

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

Tugas yang sudah berstatus IN_PROGRESS tidak dapat dihapus: permintaan akan ditolak dengan 409 Conflict dan tugas tetap berjalan. Kredit untuk tugas yang sudah mulai dikerjakan oleh worker tidak dapat dikembalikan, sehingga menghapusnya di tengah proses akan membuat Anda kehilangan kredit sekaligus hasilnya. Tunggu hingga tugas mencapai status SUCCEEDED, FAILED, atau CANCELED, baru kemudian hapus.

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

Hasil

Mengembalikan 200 OK jika berhasil, atau 409 Conflict saat tugas berstatus IN_PROGRESS.

Request

DELETE

/openapi/v1/resize/:id

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/resize/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/resize

Daftar Tugas Ubah Ukuran

Endpoint ini memungkinkan Anda mengambil daftar tugas ubah ukuran.

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 100 item.

Name
sort_by
Type
string
Description
Kolom yang digunakan untuk mengurutkan. Nilai yang tersedia:
- +created_at: Urutkan berdasarkan waktu pembuatan secara menaik (ascending).
- -created_at: Urutkan berdasarkan waktu pembuatan secara menurun (descending).

Returns

Mengembalikan daftar berpaginasi dari The Resize Task Objects.

Request

GET

/openapi/v1/resize

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "resize",
    "model_urls": {
      "glb": "https://assets.meshy.ai/.../model.glb?Expires=..."
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null,
    "consumed_credits": 1
  }
]

GET/openapi/v1/resize/:id/stream

Streaming Tugas Ubah Ukuran

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

Parameter

Name
id
Type
path
Description
Pengidentifikasi unik untuk tugas ubah ukuran yang akan di-streaming.

Hasil

Mengembalikan aliran The Resize Task Objects sebagai Server-Sent Events.

Untuk tugas dengan status PENDING atau IN_PROGRESS, stream respons hanya akan menyertakan kolom progress dan status yang diperlukan.

Request

GET

/openapi/v1/resize/:id/stream

curl -N https://api.meshy.ai/openapi/v1/resize/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": "resize",
  "model_urls": {
    "glb": "https://assets.meshy.ai/.../model.glb?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}

Objek Task Ubah ukuran

Objek Task Ubah ukuran merepresentasikan pekerjaan pengubahan ukuran.

Properties

id · string

Pengidentifikasi unik untuk task.

type · string

Jenis task. Nilainya adalah resize.

model_urls · object

URL yang dapat diunduh untuk file model yang telah diubah ukurannya. Saat menggunakan input_task_id, output selalu berupa GLB. Saat menggunakan model_url, output tetap mempertahankan format aslinya.

progress · integer

Progress dari task (0-100).

status · string

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

preceding_tasks · integer

Jumlah task yang mendahului. Hanya relevan ketika status adalah PENDING.

created_at · timestamp

Stempel waktu saat task dibuat, dalam milidetik.

started_at · timestamp

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

finished_at · timestamp

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

task_error · object

Objek error jika task gagal. Lihat Kesalahan untuk detail lebih lanjut.

consumed_credits · integer

Jumlah kredit yang dikonsumsi oleh task ini (1 kredit per task ubah ukuran). Mengembalikan 0 untuk task dengan status FAILED.