lowpoly dihentikan pada 30 Okt 2026. Ganti model sebelum tanggal-tanggal ini agar permintaan tidak error. Lihat semua penghentian

API Ubah ukuran

Ubah ukuran model 3D menjadi ukuran dunia nyata, dalam meter. Atur tingginya atau panjang sisi terpanjangnya, atau biarkan Meshy memperkirakan tinggi objek di dunia nyata.

POST/openapi/v1/resize

Buat tugas Resize

Membuat tugas Resize. Tugas ini berjalan di latar belakang. Untuk mengetahui berapa lama tugas biasanya berlangsung, lihat Processing times.

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

Parameter

  • Name
    input_task_id
    Type
    string
    Wajib
    Description

    Wajib diisi kecuali Anda mengirim model_url. ID dari tugas yang menghasilkan model 3D, misalnya tugas Text to 3D, Image to 3D, Remesh, atau Retexture. Tugas tersebut harus berasal dari API dan memiliki status SUCCEEDED. Meshy mengembalikan model yang telah diubah ukurannya sebagai file GLB.

  • Name
    model_url
    Type
    string
    Wajib
    Description

    Wajib diisi kecuali Anda mengirim input_task_id. Model yang akan diubah ukurannya, berupa URL publik atau data URI. Jika Anda mengirim keduanya, Meshy akan menggunakan input_task_id.

    Model harus berupa file GLB, glTF, OBJ, FBX, atau STL dengan ukuran maksimum 400 MB dari URL http atau https, atau 100 MB sebagai data URI. Untuk data URI, gunakan MIME type application/octet-stream.

    File yang berukuran lebih dari 100 MB juga harus mengikuti aturan berikut:

    • File GLB, glTF, FBX, atau OBJ dapat memiliki paling banyak 10.000.000 faces. Meshy menghitung faces sebagai triangles, sehingga quad dihitung sebagai 2, dan mesh yang digambar lebih dari sekali dihitung satu kali per salinan.
    • File FBX harus berupa binary FBX 7.1 atau yang lebih baru.
    • File GLB atau glTF tidak boleh menggunakan kompresi Draco.

    File GLB, OBJ, FBX, atau STL akan mempertahankan formatnya pada hasil. File .gltf atau data URI akan dikembalikan sebagai GLB.

Kirim tepat satu dari resize_height, resize_longest_side, atau auto_size. Jika tidak mengirim satu pun, atau mengirim lebih dari satu, akan menghasilkan 400.

  • Name
    resize_height
    Type
    number
    Description

    Tinggi baru model dalam meter, harus lebih besar dari 0. Nilai negatif akan menghasilkan 400.

  • Name
    resize_longest_side
    Type
    number
    Description

    Panjang baru dari sisi terpanjang model dalam meter, harus lebih besar dari 0. Nilai negatif akan menghasilkan 400. Meshy mempertahankan rasio aspek model.

  • Name
    auto_size
    Type
    boolean
    Description

    Apakah akan memperkirakan tinggi objek di dunia nyata menggunakan AI vision dan mengubah ukuran model sesuai dengan itu. Kecuali Anda mengatur origin_at, Meshy akan menempatkan titik asal di bagian bawah.

  • Name
    origin_at
    Type
    string
    default bottom
    Description

    Tempat menempatkan titik asal model setelah pengubahan ukuran, bottom atau center.

Hasil yang dikembalikan

Bidang result pada respons berisi ID dari tugas Resize yang baru.

Mode kegagalan

  • Name
    400 - Bad Request
    Description

    Permintaan tidak dapat dijalankan. Pesan kesalahan menyebutkan masalah apa yang ditemukan. Contohnya:

    • Parameter hilang: Baik model_url maupun input_task_id tidak dikirim.
    • Mode resize hilang: Tidak ada satu pun dari resize_height, resize_longest_side, dan auto_size yang dikirim.
    • Parameter saling eksklusif: Permintaan memiliki lebih dari satu dari resize_height, resize_longest_side, dan auto_size. Kirim hanya satu.
    • Ukuran negatif: resize_height atau resize_longest_side bernilai negatif.
    • Tugas input tidak valid: input_task_id bukan tugas API yang berhasil dengan file model.
    • Format model tidak valid: File model_url memiliki ekstensi yang tidak didukung.
    • URL tidak dapat dijangkau: Meshy tidak dapat mengunduh file model_url.
    • File model terlalu besar: File model_url berukuran lebih dari 400 MB dari URL http atau https, atau lebih dari 100 MB sebagai data URI.
    • Terlalu banyak faces: File model_url berukuran lebih dari 100 MB dan memiliki lebih dari 10.000.000 faces. Kurangi jumlah faces, lalu kirim file tersebut lagi.
    • ASCII FBX lebih dari 100 MB: File model_url adalah ASCII FBX yang berukuran lebih dari 100 MB. Kirim sebagai binary FBX atau GLB.
    • File model tidak dapat dibaca: File model_url berukuran lebih dari 100 MB, dan Meshy tidak dapat membaca headernya. Contohnya, file tersebut adalah GLB atau glTF terkompresi Draco, atau binary FBX 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 lagi.

    Perbaiki permintaan, lalu kirim lagi. Lihat Errors.

  • Name
    401 - Unauthorized
    Description

    Kunci API hilang atau tidak valid. Periksa header Authorization.

  • Name
    402 - Payment Required
    Description

    Contohnya:

    • Kredit tidak cukup: Akun tidak memiliki cukup kredit untuk tugas ini, atau akun telah mencapai batas kredit. Periksa saldo kredit Anda, lalu coba lagi.
    • Paket gratis: Membuat tugas memerlukan paket berbayar. Tingkatkan paket Anda di pengaturan langganan Anda, lalu coba lagi.
  • Name
    403 - Forbidden
    Description

    input_task_id adalah model bas-relief, yang tidak dapat diubah ukurannya oleh endpoint ini. Pesannya adalah This model type does not support this operation. Kirim model yang berbeda.

  • Name
    404 - Not Found
    Description

    input_task_id tidak cocok dengan tugas Anda mana pun. Periksa ID tugas, lalu kirim permintaan lagi.

  • Name
    429 - Too Many Requests
    Description

    Anda melampaui batas laju Anda. Tunggu, lalu coba lagi. Lihat Rate limits.

GET/openapi/v1/resize/:id

Dapatkan task Ubah ukuran

Mengembalikan task Ubah ukuran berdasarkan ID-nya.

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
}

Parameter

  • Name
    id
    Type
    path
    Description

    ID task dari respons pembuatan.

Hasil

Objek task Ubah ukuran.

DELETE/openapi/v1/resize/:id

Hapus tugas Resize

Menghapus tugas Resize secara permanen, termasuk model dan datanya. Anda tidak dapat membatalkan penghapusan.

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

Parameter jalur

  • Name
    id
    Type
    path
    Description

    ID tugas yang akan dihapus.

Status tugas

Menghapus tugas PENDING akan mengembalikan kredit yang digunakan saat Anda membuatnya.

Tugas IN_PROGRESS tidak dapat dihapus. Permintaan akan mengembalikan 409 Conflict, dan tugas tersebut akan tetap berjalan. Meshy tidak mengembalikan kredit untuk tugas yang sudah dimulai, jadi menghapusnya akan membuat Anda kehilangan baik kredit maupun hasilnya. Tunggu hingga tugas tersebut mencapai SUCCEEDED, FAILED, atau CANCELED, lalu hapus tugas tersebut.

Menghapus tugas dengan status akhir (SUCCEEDED, FAILED, atau CANCELED) tidak akan mengembalikan kreditnya.

Mengembalikan

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

GET/openapi/v1/resize

Daftar tugas Ubah ukuran

Mengembalikan daftar tugas Ubah ukuran Anda.

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

Parameter

  • Name
    page_num
    Type
    integer
    default 1
    Description

    Nomor halaman yang akan dikembalikan, hingga 255. Nilai yang lebih besar akan mengembalikan 400.

  • Name
    page_size
    Type
    integer
    default 10
    Description

    Jumlah tugas per halaman, hingga 100.

  • Name
    sort_by
    Type
    string
    Description

    Urutan pengurutan.

    Nilai yang tersedia:

    • +created_at: yang terlama lebih dulu
    • -created_at: yang terbaru lebih dulu

Returns

Daftar berhalaman dari objek tugas Ubah ukuran.

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

Streaming Tugas Resize

Melakukan streaming pembaruan tugas Resize sebagai Server-Sent Events (SSE).

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
}

Parameter

  • Name
    id
    Type
    path
    Description

    ID tugas dari respons pembuatan.

Returns

Sebuah stream objek tugas Resize sebagai Server-Sent Events.

Setiap event menyimpan objek tugas lengkap, dalam bentuk yang sama seperti yang dikembalikan oleh endpoint Get. Selama tugas masih PENDING atau IN_PROGRESS, bidang hasilnya belum memiliki nilai.

The Resize task object

Objek task Resize menjelaskan satu proses pengubahan ukuran model 3D. Objek ini menyimpan status, progress, dan file model saat task berhasil.

Properties

  • Name
    id
    Type
    string
    Description

    ID task. Perlakukan sebagai string buram, dan jangan bergantung pada formatnya.

  • Name
    type
    Type
    string
    Description

    Jenis task, selalu resize.

  • Name
    model_urls
    Type
    object
    Description

    URL unduhan untuk file model yang telah diubah ukurannya. Untuk input_task_id, filenya selalu GLB. Untuk model_url, file GLB, OBJ, FBX, atau STL akan mempertahankan formatnya, sedangkan file .gltf atau data URI akan dikembalikan sebagai GLB.

  • Name
    progress
    Type
    integer
    Description

    Seberapa banyak task telah selesai, dalam persentase. Nilainya 0 sampai task dimulai dan 100 saat berhasil.

  • Name
    status
    Type
    string
    Description

    Status task, salah satu dari PENDING, IN_PROGRESS, SUCCEEDED, FAILED, atau CANCELED.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Jumlah task yang berada di depan task ini dalam antrean. Nilai ini hanya berarti selama task berstatus PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

    Waktu task dibuat, dalam milidetik Unix.

  • Name
    started_at
    Type
    timestamp
    Description

    Waktu task dimulai, dalam milidetik Unix. Nilainya 0 sampai task dimulai.

  • Name
    finished_at
    Type
    timestamp
    Description

    Waktu task selesai, dalam milidetik Unix. Nilainya 0 sampai task selesai.

  • Name
    expires_at
    Type
    timestamp
    Description

    Waktu URL unduhan task kedaluwarsa, dalam milidetik Unix. Nilainya 0 sampai task selesai.

  • Name
    texture_urls
    Type
    array
    Description

    URL unduhan untuk peta tekstur model, saat task berhasil: sebuah array objek, satu untuk setiap set tekstur. Setiap objek memiliki URL base_color, dan juga dapat memiliki URL metallic, roughness, normal, emission, dan metallic_roughness. Nilainya null sampai task berhasil, dan array kosong saat model tidak memiliki peta tekstur.

  • Name
    task_error
    Type
    object
    Description

    Detail kesalahan saat task gagal. Lihat Kesalahan.

  • Name
    consumed_credits
    Type
    integer
    Description

    Jumlah kredit yang digunakan task, yaitu 1 untuk task Resize. Nilainya 0 untuk task FAILED.