ปรับขนาด API

ปรับขนาด API ช่วยให้คุณสามารถปรับขนาดโมเดล 3D ที่มีอยู่ให้เป็นขนาดจริงในโลกแห่งความเป็นจริงได้ คุณสามารถระบุความสูงที่แน่นอน กำหนดข้อจำกัดด้านด้านที่ยาวที่สุด หรือให้ AI ประมาณขนาดที่เหมาะสมโดยอัตโนมัติ

POST/openapi/v1/resize

สร้าง Resize Task

เอนด์พอยต์นี้สร้างงานปรับขนาดใหม่

พารามิเตอร์

ต้องระบุ input_task_id หรือ model_url เพียงอย่างใดอย่างหนึ่งเท่านั้น หากระบุทั้งสองอย่าง input_task_id จะมีลำดับความสำคัญก่อน

Name
input_task_id
Type
string
จำเป็น
Description
ID ของงาน Meshy ที่เสร็จสมบูรณ์แล้วซึ่งคุณต้องการปรับขนาดโมเดล งานนั้นต้องมีสถานะเป็น SUCCEEDED รูปแบบผลลัพธ์จะเป็น GLB

Name
model_url
Type
string
จำเป็น
Description
URL ที่เข้าถึงได้แบบสาธารณะหรือ data URI ที่ชี้ไปยังไฟล์โมเดล 3D รูปแบบที่รองรับ: .glb, .gltf, .obj, .fbx, .stl สำหรับ Data URI ให้ใช้ MIME type: application/octet-stream รูปแบบผลลัพธ์จะคงรูปแบบเดิมของโมเดลที่นำเข้า

ต้องระบุ mode การปรับขนาดเพียงหนึ่งอย่างเท่านั้น: resize_height, resize_longest_side, หรือ auto_size พารามิเตอร์ทั้งสามนี้ใช้ร่วมกันไม่ได้

Name
resize_height
Type
number
Description
ปรับขนาดโมเดลให้มีความสูงตามค่าที่กำหนด วัดเป็นเมตร

Name
resize_longest_side
Type
number
Description
ปรับขนาดโมเดลให้ด้านที่ยาวที่สุดตรงกับค่านี้ วัดเป็นเมตร โดยจะคงอัตราส่วนภาพเดิมไว้

Name
auto_size
Type
boolean
Description
เมื่อตั้งค่าเป็น true บริการจะใช้ AI vision เพื่อประมาณความสูงจริงของวัตถุโดยอัตโนมัติ และปรับขนาดโมเดลให้สอดคล้องกัน จุดกำเนิดจะเป็นค่าเริ่มต้น bottom เว้นแต่จะระบุ origin_at ไว้อย่างชัดเจน

Name
origin_at
Type
string
ค่าเริ่มต้น bottom
Description
ตำแหน่งของจุดกำเนิดหลังจากปรับขนาด
ค่าที่ใช้ได้: bottom, center

ค่าที่ส่งกลับ

พร็อพเพอร์ตี้ result ของการตอบกลับจะมี id ของงานปรับขนาดที่สร้างขึ้นใหม่

รูปแบบความล้มเหลว

400 - Bad Request

คำขอไม่สามารถยอมรับได้ สาเหตุที่พบบ่อย:

ขาดพารามิเตอร์: ต้องระบุ model_url หรือ input_task_id อย่างใดอย่างหนึ่ง
ขาด mode การปรับขนาด: ต้องระบุอย่างน้อยหนึ่งใน resize_height, resize_longest_side, หรือ auto_size
พารามิเตอร์ที่ใช้ร่วมกันไม่ได้: resize_height, resize_longest_side, และ auto_size ไม่สามารถใช้ร่วมกันได้
งานนำเข้าไม่ถูกต้อง: input_task_id ต้องอ้างอิงถึงงานที่สำเร็จแล้ว
รูปแบบโมเดลไม่ถูกต้อง: model_url ชี้ไปยังไฟล์ที่มีนามสกุลไม่รองรับ
ไม่สามารถเข้าถึง URL ได้: ไม่สามารถดาวน์โหลด model_url ได้

401 - Unauthorized

การยืนยันตัวตนล้มเหลว โปรดตรวจสอบ API คีย์ของคุณ

402 - Payment Required

เครดิตไม่เพียงพอสำหรับการทำงานนี้

429 - Too Many Requests

คุณเกินขีดจำกัดการจำกัดอัตราแล้ว

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

เรียกดูงานปรับขนาด (Resize Task)

เอนด์พอยต์นี้ใช้เรียกดูงานปรับขนาดตาม ID ของงานนั้น

พารามิเตอร์

Name
id
Type
path
Description
ID ของงานปรับขนาดที่ต้องการเรียกดู

ค่าที่ส่งกลับ

ออบเจ็กต์ Resize Task

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

ลบงานปรับขนาด

เอนด์พอยต์นี้จะลบงานปรับขนาดอย่างถาวร รวมถึงโมเดลและข้อมูลทั้งหมดที่เกี่ยวข้อง การกระทำนี้ไม่สามารถย้อนกลับได้

Path Parameters

Name
id
Type
path
Description
ID ของงานปรับขนาดที่ต้องการลบ

สถานะของงาน

งานที่ยังอยู่ในสถานะ PENDING จะถูกลบ และเครดิตที่ใช้ไปตอนสร้างงานจะได้รับการคืนเงิน

งานที่อยู่ในสถานะ IN_PROGRESS แล้วไม่สามารถลบได้ คำขอจะถูกปฏิเสธด้วย 409 Conflict และงานจะยังคงทำงานต่อไป เครดิตสำหรับงานที่ worker เริ่มดำเนินการไปแล้วจะไม่สามารถขอคืนได้ ดังนั้นการลบงานระหว่างที่กำลังทำงานอยู่จะทำให้คุณเสียทั้งเครดิตและผลลัพธ์ ให้รอจนกว่างานจะถึงสถานะ SUCCEEDED, FAILED หรือ CANCELED แล้วจึงค่อยลบ

งานที่อยู่ในสถานะสุดท้าย (SUCCEEDED, FAILED หรือ CANCELED) จะถูกลบ โดยไม่มีการคืนเครดิต

ค่าที่ส่งกลับ

ส่งคืน 200 OK เมื่อสำเร็จ หรือ 409 Conflict เมื่องานอยู่ในสถานะ 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

เอนด์พอยต์นี้ช่วยให้คุณสามารถดึงรายการของงานปรับขนาดได้

พารามิเตอร์

Name
page_num
Type
integer
ค่าเริ่มต้น 1
Description
หมายเลขหน้าสำหรับการแบ่งหน้า

Name
page_size
Type
integer
ค่าเริ่มต้น 10
Description
จำนวนรายการต่อหน้า สูงสุดที่อนุญาตคือ 100 รายการ

Name
sort_by
Type
string
Description
ฟิลด์ที่ใช้สำหรับจัดเรียง ค่าที่ใช้ได้:
- +created_at: จัดเรียงตามเวลาที่สร้างจากน้อยไปมาก
- -created_at: จัดเรียงตามเวลาที่สร้างจากมากไปน้อย

ผลลัพธ์ที่ส่งกลับ

ส่งกลับรายการแบบแบ่งหน้าของ 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

สตรีมงานปรับขนาด

เอนด์พอยต์นี้จะสตรีมข้อมูลอัปเดตแบบเรียลไทม์สำหรับงานปรับขนาดโดยใช้ Server-Sent Events (SSE)

พารามิเตอร์

Name
id
Type
path
Description
รหัสเฉพาะของงานปรับขนาดที่ต้องการสตรีม

ค่าที่ส่งกลับ

ส่งคืนสตรีมของ The Resize Task Objects ในรูปแบบ Server-Sent Events

สำหรับงานที่มีสถานะ PENDING หรือ IN_PROGRESS สตรีมการตอบกลับจะมีเฉพาะฟิลด์ progress และ status ที่จำเป็นเท่านั้น

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
}

The Resize Task Object

Resize Task object แสดงถึงงานปรับขนาด

Properties

id · string

ตัวระบุที่ไม่ซ้ำกันสำหรับ task

type · string

ประเภทของ task ค่าคือ resize

model_urls · object

URL สำหรับดาวน์โหลดไฟล์โมเดลที่ถูกปรับขนาดแล้ว เมื่อใช้ input_task_id ผลลัพธ์จะเป็น GLB เสมอ เมื่อใช้ model_url ผลลัพธ์จะคงรูปแบบเดิมไว้

progress · integer

progress ของ task (0-100)

status · string

สถานะของ task ค่าที่เป็นไปได้: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED

preceding_tasks · integer

จำนวนของ task ที่อยู่ก่อนหน้า มีความหมายเฉพาะเมื่อสถานะเป็น PENDING เท่านั้น

created_at · timestamp

ไทม์สแตมป์ของเวลาที่สร้าง task มีหน่วยเป็นมิลลิวินาที

started_at · timestamp

ไทม์สแตมป์ของเวลาที่เริ่ม task มีหน่วยเป็นมิลลิวินาที เป็น 0 หากยังไม่เริ่ม

finished_at · timestamp

ไทม์สแตมป์ของเวลาที่ task เสร็จสิ้น มีหน่วยเป็นมิลลิวินาที เป็น 0 หากยังไม่เสร็จสิ้น

task_error · object

อ็อบเจกต์ข้อผิดพลาดหาก task ล้มเหลว ดู ข้อผิดพลาด สำหรับรายละเอียดเพิ่มเติม

consumed_credits · integer

จำนวนเครดิตที่ถูกใช้ไปโดย task นี้ (1 เครดิตต่อ resize task หนึ่งครั้ง) จะคืนค่า 0 สำหรับ task ที่มีสถานะ FAILED