API Ubah saiz

Ubah saiz model 3D kepada saiz dunia sebenar, dalam meter. Tetapkan ketinggiannya atau panjang sisi terpanjangnya, atau biarkan Meshy menganggarkan ketinggian sebenar objek tersebut.

POST/openapi/v1/resize

Create a Resize task

Mencipta tugas Resize. Tugas berjalan di latar belakang. Untuk tempoh biasa yang diambil oleh tugas, 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
Diperlukan
Description
Diperlukan kecuali anda menghantar model_url. ID bagi tugas yang menghasilkan model 3D, contohnya tugas Teks ke 3D, Imej ke 3D, Remesh, atau Retekstur. Tugas tersebut mesti berasal daripada API dan mempunyai status SUCCEEDED. Meshy mengembalikan model yang telah diubah saiz sebagai fail GLB.

Name
model_url
Type
string
Diperlukan
Description
Diperlukan kecuali anda menghantar input_task_id. Model untuk diubah saiz, dalam bentuk URL awam atau data URI. Jika anda menghantar kedua-duanya, Meshy akan menggunakan input_task_id.
Model mestilah fail GLB, glTF, OBJ, FBX, atau STL bersaiz maksimum 400 MB daripada URL http atau https, atau 100 MB sebagai data URI. Untuk data URI, gunakan MIME type application/octet-stream.
Fail yang melebihi 100 MB juga mesti mematuhi peraturan berikut:
- Fail GLB, glTF, FBX, atau OBJ boleh mempunyai maksimum 10,000,000 muka. Meshy mengira muka sebagai segi tiga, jadi segi empat tepat dikira sebagai 2, dan jejaring yang dilukis lebih daripada sekali dikira sekali bagi setiap salinan.
- Fail FBX mestilah FBX binari 7.1 atau lebih baharu.
- Fail GLB atau glTF tidak boleh menggunakan pemampatan Draco.
Fail GLB, OBJ, FBX, atau STL mengekalkan formatnya dalam hasil. Fail .gltf atau data URI akan dikembalikan sebagai GLB.

Hantar tepat satu daripada resize_height, resize_longest_side, atau auto_size. Jika tiada satu pun dihantar, atau lebih daripada satu dihantar, akan mengembalikan 400.

Name
resize_height
Type
number
Description
Ketinggian baharu model dalam meter, lebih besar daripada 0. Nilai negatif akan mengembalikan 400.

Name
resize_longest_side
Type
number
Description
Panjang baharu bagi sisi terpanjang model dalam meter, lebih besar daripada 0. Nilai negatif akan mengembalikan 400. Meshy mengekalkan nisbah bidang model.

Name
auto_size
Type
boolean
Description
Sama ada untuk menganggarkan ketinggian sebenar objek menggunakan penglihatan AI dan mengubah saiz model mengikutnya. Melainkan anda menetapkan origin_at, Meshy akan meletakkan titik asal di bahagian bawah.

Name
origin_at
Type
string
lalai bottom
Description
Lokasi untuk meletakkan titik asal model selepas diubah saiz, bottom atau center.

Nilai yang dikembalikan

Medan result dalam respons mengandungi ID bagi tugas Resize yang baharu.

Mod kegagalan

Name
400 - Bad Request
Description
Permintaan tidak dapat dijalankan. Mesej ralat menyatakan masalah yang ditemui. Contohnya:
- Parameter hilang: Sama ada model_url atau input_task_id tidak dihantar.
- Mod ubah saiz hilang: Tiada satu pun daripada resize_height, resize_longest_side, dan auto_size yang dihantar.
- Parameter saling eksklusif: Permintaan mempunyai lebih daripada satu daripada resize_height, resize_longest_side, dan auto_size. Hantar hanya satu sahaja.
- Saiz negatif: resize_height atau resize_longest_side bernilai negatif.
- Tugas input tidak sah: input_task_id bukan tugas API yang berjaya dengan fail model.
- Format model tidak sah: Fail model_url mempunyai sambungan yang tidak disokong.
- URL tidak dapat dicapai: Meshy tidak dapat memuat turun fail model_url.
- Fail model terlalu besar: Fail model_url melebihi 400 MB daripada URL http atau https, atau melebihi 100 MB sebagai data URI.
- Terlalu banyak muka: Fail model_url melebihi 100 MB dan mempunyai lebih daripada 10,000,000 muka. Kurangkan bilangan muka, kemudian hantar fail semula.
- FBX ASCII melebihi 100 MB: Fail model_url ialah FBX ASCII melebihi 100 MB. Hantar sebagai FBX binari atau GLB.
- Fail model tidak dapat dibaca: Fail model_url melebihi 100 MB, dan Meshy tidak dapat membaca headernya. Contohnya, ia adalah GLB atau glTF yang dimampatkan menggunakan Draco, atau FBX binari yang lebih lama daripada 7.1.
- Header model terlalu kompleks: Fail model_url melebihi 100 MB, dan headernya mempunyai terlalu banyak jejaring, nod, atau rekod untuk disemak. Kurangkan bilangan objek dalam fail, kemudian hantar semula.
Betulkan permintaan, kemudian hantar semula. Lihat Errors.
Name
401 - Unauthorized
Description
Kunci API hilang atau tidak sah. Semak header Authorization.
Name
402 - Payment Required
Description
Contohnya:
- Kredit tidak mencukupi: Akaun tidak mempunyai kredit yang mencukupi untuk tugas ini, atau akaun telah mencapai had kredit. Semak baki kredit anda, kemudian cuba semula.
- Pelan percuma: Mencipta tugas memerlukan pelan berbayar. Naik taraf pelan anda dalam tetapan langganan, kemudian cuba semula.
Name
403 - Forbidden
Description
input_task_id ialah model relief rendah, yang tidak boleh diubah saiz oleh endpoint ini. Mesejnya ialah This model type does not support this operation. Hantar model yang lain.
Name
404 - Not Found
Description
input_task_id tidak sepadan dengan mana-mana tugas anda. Semak ID tugas, kemudian hantar permintaan semula.
Name
429 - Too Many Requests
Description
Anda telah melebihi had kadar anda. Tunggu, kemudian cuba semula. Lihat Rate limits.

GET/openapi/v1/resize/:id

Dapatkan tugas Ubah saiz

Mengembalikan tugas Ubah saiz 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 tugas daripada respons pembuatan (create).

Nilai pulangan

Objek tugas Ubah saiz.

DELETE/openapi/v1/resize/:id

Padam tugasan Ubah saiz

Memadam secara kekal tugasan Ubah saiz, termasuk model dan datanya. Anda tidak boleh membatalkan tindakan padam ini.

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 laluan

Name
id
Type
path
Description
ID tugasan yang hendak dipadam.

Status tugasan

Memadam tugasan PENDING akan memulangkan kredit yang digunakan semasa anda mencipta tugasan tersebut.

Tugasan IN_PROGRESS tidak boleh dipadam. Permintaan akan memulangkan 409 Conflict, dan tugasan tersebut terus berjalan. Meshy tidak memulangkan kredit untuk tugasan yang telah bermula, jadi memadamnya akan merugikan anda dari segi kredit dan juga hasilnya. Tunggu sehingga ia mencapai status SUCCEEDED, FAILED, atau CANCELED, kemudian padamkannya.

Memadam tugasan yang berada dalam status akhir (SUCCEEDED, FAILED, atau CANCELED) tidak memulangkan kreditnya.

Pulangan

200 OK apabila tugasan berjaya dipadam, atau 409 Conflict apabila tugasan berstatus IN_PROGRESS.

GET/openapi/v1/resize

Senaraikan tugasan Ubah saiz

Mengembalikan senarai tugasan Ubah saiz 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
lalai 1
Description
Nombor halaman yang hendak dikembalikan, sehingga 255. Nilai yang lebih besar akan mengembalikan 400.

Name
page_size
Type
integer
lalai 10
Description
Bilangan tugasan setiap halaman, sehingga 100.

Name
sort_by
Type
string
Description
Susunan isihan.
Nilai yang tersedia:
- +created_at: paling lama dahulu
- -created_at: paling baharu dahulu

Nilai Kembali

Senarai bersekat halaman bagi objek tugasan Ubah saiz.

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

Strim tugasan Ubah saiz

Menstrim kemas kini tugasan Ubah saiz 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 tugasan daripada respons create.

Nilai Pulangan

Satu strim objek tugasan Ubah saiz sebagai Server-Sent Events.

Setiap acara (event) memegang objek tugasan yang lengkap, dalam bentuk yang sama seperti yang dipulangkan oleh endpoint Get. Semasa tugasan masih PENDING atau IN_PROGRESS, medan hasilnya belum lagi mempunyai nilai.

Objek tugas Resize

Objek tugas Resize menerangkan satu ubah saiz model 3D. Ia menyimpan status, progress, dan fail model apabila tugas itu berjaya.

Ciri-ciri

Name
id
Type
string
Description
ID tugas. Anggap ia sebagai string legap, dan jangan bergantung pada formatnya.
Name
type
Type
string
Description
Jenis tugas, sentiasa resize.
Name
model_urls
Type
object
Description
URL muat turun untuk fail model yang telah diubah saiz. Untuk input_task_id, failnya sentiasa GLB. Untuk model_url, fail GLB, OBJ, FBX, atau STL mengekalkan formatnya, dan fail .gltf atau Data URI akan dikembalikan sebagai GLB.
Name
progress
Type
integer
Description
Berapa banyak bahagian tugas yang telah selesai, dalam peratusan. Nilainya 0 sehingga tugas bermula dan 100 apabila ia berjaya.
Name
status
Type
string
Description
Status tugas, salah satu daripada PENDING, IN_PROGRESS, SUCCEEDED, FAILED, atau CANCELED.
Name
preceding_tasks
Type
integer
Description
Bilangan tugas yang mendahului tugas ini dalam baris gilir. Nilai ini hanya bermakna semasa tugas berstatus PENDING.
Name
created_at
Type
timestamp
Description
Masa tugas dicipta, dalam milisaat Unix.
Name
started_at
Type
timestamp
Description
Masa tugas bermula, dalam milisaat Unix. Nilainya 0 sehingga tugas bermula.
Name
finished_at
Type
timestamp
Description
Masa tugas selesai, dalam milisaat Unix. Nilainya 0 sehingga tugas selesai.
Name
expires_at
Type
timestamp
Description
Masa URL muat turun tugas tamat tempoh, dalam milisaat Unix. Nilainya 0 sehingga tugas selesai.
Name
texture_urls
Type
array
Description
URL muat turun untuk peta tekstur model, apabila tugas berjaya: satu tatasusunan objek, satu untuk setiap set tekstur. Setiap objek mempunyai URL base_color, dan juga boleh mempunyai URL metallic, roughness, normal, emission, dan metallic_roughness. Nilainya null sehingga tugas berjaya, dan tatasusunan kosong apabila model tidak mempunyai peta tekstur.
Name
task_error
Type
object
Description
Butiran ralat apabila tugas gagal. Lihat Ralat.
Name
consumed_credits
Type
integer
Description
Bilangan kredit yang digunakan oleh tugas, iaitu 1 untuk tugas Resize. Nilainya 0 untuk tugas FAILED.