Resize API

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

POST/openapi/v1/resize

Create a Resize Task

Endpoint ini membuat tugas resize baru.

Tugas ini berjalan di latar belakang. Untuk informasi berapa lama biasanya proses ini berlangsung, lihat Processing Times.

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 ubah ukurannya. Tugas 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 menunjuk ke file model 3D. Format yang didukung: .glb, .gltf, .obj, .fbx, .stl. Untuk Data URI, gunakan MIME type: application/octet-stream. URL .glb, .obj, .fbx, atau .stl akan mempertahankan formatnya pada output; URL .gltf atau data URI akan menghasilkan GLB.
Ukuran file maksimum: 400 MB untuk URL http atau https, 100 MB untuk URI data:.
File GLB, glTF, FBX, atau OBJ yang melebihi 100 MB boleh memiliki paling banyak 10.000.000 permukaan (faces). Permukaan dihitung sebagai segitiga: sebuah quad dihitung sebagai 2, dan sebuah mesh yang digambar lebih dari sekali dihitung sekali per salinan. Di atas 100 MB, file FBX harus berupa FBX biner 7.1 atau lebih baru, dan file GLB atau glTF tidak boleh menggunakan kompresi Draco.

Tepat satu mode resize wajib diisi: resize_height, resize_longest_side, atau auto_size. Ketiga parameter ini 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 akan dipertahankan.

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

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

Returns

Properti result pada respons berisi id dari tugas resize 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 salah satu dari resize_height, resize_longest_side, atau auto_size harus ditentukan.
Parameter saling eksklusif: resize_height, resize_longest_side, dan auto_size tidak dapat digabungkan.
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.
File model terlalu besar: File model_url melebihi 400 MB (URL http atau https) atau 100 MB (URI data:).
Terlalu banyak permukaan: File model_url berukuran lebih dari 100 MB dan memiliki lebih dari 10.000.000 permukaan. Kurangi jumlah permukaan, lalu kirim file tersebut kembali.
FBX ASCII di atas 100 MB: File model_url adalah FBX ASCII yang melebihi 100 MB. Kirim sebagai FBX biner atau GLB.
File model tidak dapat dibaca: File model_url berukuran lebih dari 100 MB dan headernya tidak dapat dibaca, misalnya GLB atau glTF yang terkompresi Draco, atau FBX biner yang lebih lama dari 7.1.
Header model terlalu kompleks: File model_url berukuran lebih dari 100 MB dan headernya memiliki terlalu banyak mesh, node, atau record untuk diperiksa. Kurangi jumlah objek dalam file, lalu kirim kembali.

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 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 resize berdasarkan ID-nya.

Parameter

Name
id
Type
path
Description
ID dari tugas resize 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

Hapus Tugas Ubah ukuran

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

Parameter Jalur

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 terpakai 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 mencapai status SUCCEEDED, FAILED, atau CANCELED, baru kemudian hapus.

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

Hasil

Mengembalikan 200 OK jika berhasil, atau 409 Conflict ketika 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

List Resize Tasks

Endpoint ini memungkinkan Anda untuk mengambil daftar tugas resize.

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

Stream 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-stream.

Returns

Mengembalikan stream dari The Resize Task Objects sebagai Server-Sent Events.

Untuk tugas dengan status PENDING atau IN_PROGRESS, response stream hanya akan menyertakan field 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 Resize

Objek Task Resize merepresentasikan sebuah job resize.

Properties

id · string

Pengenal unik untuk task tersebut.

type · string

Jenis task. Nilainya adalah resize.

model_urls · object

URL yang dapat diunduh untuk file model hasil resize. Saat menggunakan input_task_id, output selalu berupa GLB. Saat menggunakan model_url, input .glb, .obj, .fbx, atau .stl akan mempertahankan formatnya, sedangkan input .gltf atau Data URI akan menghasilkan GLB.

progress · integer

Progress dari task tersebut (0-100).

status · string

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

preceding_tasks · integer

Jumlah task yang mendahului. Hanya berarti 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 kesalahan jika task gagal. Lihat Kesalahan untuk detail lebih lanjut.

consumed_credits · integer

Jumlah kredit yang terpakai oleh task ini (1 kredit per task resize). Mengembalikan 0 untuk task yang FAILED.