API Ubah saiz

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

Cipta Tugas Ubah Saiz

Endpoint ini mencipta tugas ubah saiz baharu.

Parameter

Hanya salah satu daripada input_task_id atau model_url yang diperlukan. Jika kedua-duanya disediakan, input_task_id diberi 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 umum atau data URI yang menunjuk kepada fail model 3D. Format yang disokong: .glb, .gltf, .obj, .fbx, .stl. Untuk Data URI, gunakan jenis MIME: application/octet-stream. Format output akan mengekalkan format asal model input.

Tepat satu mode ubah saiz 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 akan dikekalkan.

Name
auto_size
Type
boolean
Description
Apabila ditetapkan kepada true, perkhidmatan ini menggunakan penglihatan AI untuk menganggarkan secara automatik ketinggian sebenar objek tersebut di dunia nyata dan mengubah saiz model dengan sewajarnya. 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 ubah saiz.
Nilai yang tersedia: bottom, center.

Pemulangan

Sifat result pada respons mengandungi id bagi tugas ubah saiz 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 disediakan.
Mode ubah saiz hilang: Sekurang-kurangnya satu daripada resize_height, resize_longest_side, atau auto_size mesti ditentukan.
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.

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

Parameter

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

Pulangan

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 diubah semula.

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 pada masa penciptaan akan dikembalikan.

Tugas yang sudah IN_PROGRESS tidak boleh dipadam: permintaan akan ditolak dengan 409 Conflict dan tugas akan terus berjalan. Kredit untuk tugas yang telah dimulakan oleh worker tidak boleh dikembalikan, jadi memadamnya semasa berjalan akan menyebabkan anda kehilangan kedua-dua kredit dan hasilnya. Tunggu sehingga ia mencapai SUCCEEDED, FAILED atau CANCELED, kemudian padamkannya.

Tugas dalam keadaan terminal (SUCCEEDED, FAILED atau CANCELED) akan dipadam tanpa bayaran balik.

Pemulangan

Mengembalikan 200 OK apabila berjaya, atau 409 Conflict apabila tugas 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 Resize

Endpoint ini membolehkan anda mendapatkan senarai tugas resize.

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 diisih. Nilai yang tersedia:
- +created_at: Isih mengikut masa penciptaan secara menaik.
- -created_at: Isih mengikut masa penciptaan secara menurun.

Pulangan

Mengembalikan senarai bernomboran halaman bagi Objek Tugas Resize.

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

Menstrim Tugas Ubah Saiz

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

Parameter

Name
id
Type
path
Description
Pengenal unik untuk tugas ubah saiz yang hendak distrim.

Nilai Pulangan

Mengembalikan strim Objek Tugas Ubah Saiz sebagai Server-Sent Events.

Untuk tugas berstatus PENDING atau IN_PROGRESS, strim 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 Tugas Resize

Objek Tugas Resize mewakili kerja pengubahsuaian saiz.

Ciri-ciri

id · string

Pengecam unik untuk tugas tersebut.

type · string

Jenis tugas. 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, output mengekalkan format asal.

progress · integer

Kemajuan tugas (0-100).

status · string

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

preceding_tasks · integer

Bilangan tugas terdahulu. Bermakna hanya apabila status adalah PENDING.

created_at · timestamp

Cap masa bila tugas dicipta, dalam milisaat.

started_at · timestamp

Cap masa bila tugas dimulakan, dalam milisaat. 0 jika belum dimulakan.

finished_at · timestamp

Cap masa bila tugas selesai, dalam milisaat. 0 jika belum selesai.

task_error · object

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

consumed_credits · integer

Bilangan kredit yang digunakan oleh tugas ini (1 kredit bagi setiap tugas resize). Mengembalikan 0 untuk tugas FAILED.