Resize API

API Ubah saiz membolehkan anda mengubah saiz model 3D sedia ada kepada dimensi dunia sebenar. Anda boleh menentukan ketinggian yang tepat, kekangan sisi terpanjang, atau membiarkan AI menganggarkan saiz yang sesuai secara automatik.

POST/openapi/v1/resize

Create a Resize Task

Endpoint ini mencipta tugas resize baharu.

Tugas ini berjalan di latar belakang. Untuk tempoh masa yang biasanya diambil, lihat Processing Times.

Parameter

Hanya salah satu daripada input_task_id atau model_url diperlukan. Jika kedua-duanya diberikan, input_task_id mengambil keutamaan.

Name
input_task_id
Type
string
Diperlukan
Description
ID bagi tugas Meshy yang telah selesai yang modelnya ingin anda ubah saiz. Tugas tersebut mestilah mempunyai status SUCCEEDED. Format output akan menjadi GLB.

Name
model_url
Type
string
Diperlukan
Description
URL yang boleh diakses secara awam atau data URI yang menunjuk kepada fail model 3D. Format yang disokong: .glb, .gltf, .obj, .fbx, .stl. Untuk Data URI, gunakan MIME type: application/octet-stream. URL .glb, .obj, .fbx atau .stl mengekalkan formatnya dalam output; URL .gltf atau data URI menghasilkan GLB.
Saiz fail maksimum: 400 MB untuk URL http atau https, 100 MB untuk URI data:.
Fail GLB, glTF, FBX atau OBJ yang melebihi 100 MB boleh mempunyai paling banyak 10,000,000 muka. Muka dikira sebagai segi tiga: segi empat dikira sebagai 2, dan jejaring yang dilukis lebih daripada sekali dikira sekali bagi setiap salinan. Melebihi 100 MB, fail FBX mestilah FBX binari 7.1 atau lebih baharu, dan fail GLB atau glTF tidak boleh menggunakan mampatan Draco.

Tepat satu mode resize diperlukan: resize_height, resize_longest_side, atau auto_size. Ketiga-tiga parameter ini saling eksklusif.

Name
resize_height
Type
number
Description
Ubah saiz model kepada ketinggian tertentu yang diukur dalam meter.

Name
resize_longest_side
Type
number
Description
Ubah saiz model supaya sisi terpanjangnya sepadan dengan nilai ini, diukur dalam meter. Nisbah aspek dikekalkan.

Name
auto_size
Type
boolean
Description
Apabila ditetapkan kepada true, perkhidmatan menggunakan penglihatan AI untuk menganggarkan secara automatik ketinggian sebenar objek tersebut dan mengubah saiz model mengikutnya. Titik asal akan menjadi lalai kepada bottom melainkan origin_at ditetapkan secara eksplisit.

Name
origin_at
Type
string
lalai bottom
Description
Kedudukan titik asal selepas pengubahan saiz.
Nilai yang tersedia: bottom, center.

Pulangan

Sifat result bagi respons mengandungi id bagi tugas resize yang baharu dicipta.

Mod Kegagalan

400 - Bad Request

Permintaan tidak dapat diterima. Punca biasa:

Parameter hilang: Sama ada model_url atau input_task_id mesti diberikan.
Mode resize hilang: Sekurang-kurangnya salah satu daripada resize_height, resize_longest_side, atau auto_size mesti dinyatakan.
Parameter saling eksklusif: resize_height, resize_longest_side, dan auto_size tidak boleh digabungkan.
Tugas input tidak sah: input_task_id mesti merujuk kepada tugas yang berjaya.
Format model tidak sah: model_url menunjuk kepada fail dengan sambungan yang tidak disokong.
URL tidak dapat dicapai: model_url tidak dapat dimuat turun.
Fail model terlalu besar: Fail model_url melebihi 400 MB (URL http atau https) atau 100 MB (URI data:).
Terlalu banyak muka: Fail model_url melebihi 100 MB dan mempunyai lebih daripada 10,000,000 muka. Kurangkan bilangan muka, kemudian hantar semula fail tersebut.
ASCII FBX melebihi 100 MB: Fail model_url adalah ASCII FBX yang melebihi 100 MB. Hantarnya sebagai FBX binari atau GLB.
Fail model tidak boleh dibaca: Fail model_url melebihi 100 MB dan headernya tidak dapat dibaca, contohnya GLB atau glTF yang dimampatkan dengan 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 tersebut, kemudian hantar semula.

401 - Unauthorized

Pengesahan gagal. Sila semak kunci API anda.

402 - Payment Required

Kredit tidak mencukupi untuk melaksanakan tugas ini.

429 - Too Many Requests

Anda telah melebihi had kadar 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

Dapatkan Semula Tugas Ubah Saiz

endpoint ini mendapatkan semula tugas ubah saiz mengikut IDnya.

Parameter

Name
id
Type
path
Description
ID tugas ubah saiz yang hendak didapatkan semula.

Hasil Kembali

Objek Tugas Ubah Saiz.

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

Padam Tugas Ubah saiz

Endpoint ini memadam tugas ubah saiz secara kekal, termasuk semua model dan data yang berkaitan. Tindakan ini tidak boleh diundurkan.

Parameter Laluan

Name
id
Type
path
Description
ID tugas ubah saiz yang hendak dipadam.

Status Tugas

Tugas yang masih PENDING akan dipadam dan kredit yang digunakan semasa penciptaan akan dikembalikan.

Tugas yang sudah IN_PROGRESS tidak boleh dipadam: permintaan akan ditolak dengan 409 Conflict dan tugas tersebut terus berjalan. Kredit bagi tugas yang telah mula diproses oleh worker tidak boleh dikembalikan, jadi memadamnya semasa ia sedang berjalan akan menyebabkan anda kehilangan kredit dan juga hasilnya. Tunggu sehingga ia mencapai status SUCCEEDED, FAILED atau CANCELED, kemudian padamkannya.

Tugas yang berada dalam status akhir (SUCCEEDED, FAILED atau CANCELED) akan dipadam tanpa sebarang bayaran balik.

Nilai Pulangan

Memulangkan 200 OK jika berjaya, atau 409 Conflict apabila 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

Senaraikan Tugas Ubah Saiz

Endpoint ini membolehkan anda mendapatkan semula senarai tugas ubah saiz.

Parameter

Name
page_num
Type
integer
lalai 1
Description
Nombor halaman untuk penomboran halaman.

Name
page_size
Type
integer
lalai 10
Description
Had saiz halaman. Maksimum yang dibenarkan ialah 100 item.

Name
sort_by
Type
string
Description
Medan untuk disusun mengikut. Nilai yang tersedia:
- +created_at: Susun mengikut masa penciptaan dalam tertib menaik.
- -created_at: Susun mengikut masa penciptaan dalam tertib menurun.

Pulangan

Mengembalikan senarai berhalaman bagi 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

Alirkan Tugas Ubah Saiz

Endpoint ini mengalirkan kemas kini masa nyata untuk tugas ubah saiz menggunakan Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Pengecam unik untuk tugas ubah saiz yang hendak dialirkan.

Nilai Pulangan

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

Untuk tugas PENDING atau IN_PROGRESS, aliran respons hanya akan mengandungi medan 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 Tugasan Ubah Saiz

Objek Tugasan Ubah Saiz mewakili kerja ubah saiz.

Ciri-ciri

id · string

Pengenal unik untuk tugasan.

type · string

Jenis tugasan. Nilainya ialah resize.

model_urls · object

URL yang boleh dimuat turun untuk fail model yang telah diubah saiz. Apabila menggunakan input_task_id, output sentiasa dalam bentuk GLB. Apabila menggunakan model_url, input .glb, .obj, .fbx atau .stl mengekalkan formatnya, manakala input .gltf atau Data URI menghasilkan GLB.

progress · integer

Progress tugasan (0-100).

status · string

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

preceding_tasks · integer

Bilangan tugasan yang mendahului. Hanya bermakna apabila status adalah PENDING.

created_at · timestamp

Cap masa bila tugasan ini dicipta, dalam milisaat.

started_at · timestamp

Cap masa bila tugasan ini dimulakan, dalam milisaat. 0 jika belum dimulakan.

finished_at · timestamp

Cap masa bila tugasan ini selesai, dalam milisaat. 0 jika belum selesai.

task_error · object

Objek ralat jika tugasan gagal. Lihat Ralat untuk butiran lanjut.

consumed_credits · integer

Bilangan kredit yang digunakan oleh tugasan ini (1 kredit bagi setiap tugasan ubah saiz). Mengembalikan 0 untuk tugasan FAILED.