Resize API

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

POST/openapi/v1/resize

สร้างงานปรับขนาด (Resize)

สร้างงานปรับขนาด (Resize) งานนี้จะทำงานในพื้นหลัง สำหรับระยะเวลาที่งานมักใช้ ดูที่ ระยะเวลาในการประมวลผล

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

พารามิเตอร์

Name
input_task_id
Type
string
จำเป็น
Description
จำเป็นต้องระบุ เว้นแต่คุณจะส่ง model_url คือ ID ของงานที่สร้างโมเดล 3D ตัวอย่างเช่น งานข้อความเป็น 3D, รูปภาพเป็น 3D, รีเมช หรือรีเท็กซ์เจอร์ งานนั้นต้องมาจาก API และมีสถานะเป็น SUCCEEDED Meshy จะส่งคืนโมเดลที่ปรับขนาดแล้วเป็นไฟล์ GLB

Name
model_url
Type
string
จำเป็น
Description
จำเป็นต้องระบุ เว้นแต่คุณจะส่ง input_task_id คือโมเดลที่จะปรับขนาด โดยเป็น URL สาธารณะหรือ data URI หากคุณส่งทั้งสองอย่าง Meshy จะใช้ input_task_id
โมเดลต้องเป็นไฟล์ GLB, glTF, OBJ, FBX หรือ STL ขนาดไม่เกิน 400 MB จาก URL แบบ http หรือ https หรือไม่เกิน 100 MB ในรูปแบบ data URI สำหรับ data URI ให้ใช้ MIME type เป็น application/octet-stream
ไฟล์ที่มีขนาดเกิน 100 MB ต้องเป็นไปตามกฎเหล่านี้ด้วย:
- ไฟล์ GLB, glTF, FBX หรือ OBJ มีได้ไม่เกิน 10,000,000 หน้า (faces) Meshy นับหน้าเป็นสามเหลี่ยม ดังนั้นรูปสี่เหลี่ยมจะนับเป็น 2 และเมชที่วาดซ้ำมากกว่าหนึ่งครั้งจะนับหนึ่งครั้งต่อสำเนา
- ไฟล์ FBX ต้องเป็น binary FBX เวอร์ชัน 7.1 ขึ้นไป
- ไฟล์ GLB หรือ glTF ต้องไม่ใช้การบีบอัดแบบ Draco
ไฟล์ GLB, OBJ, FBX หรือ STL จะคงรูปแบบเดิมไว้ในผลลัพธ์ ไฟล์ .gltf หรือ data URI จะถูกส่งคืนเป็น GLB

ให้ส่งค่าใดค่าหนึ่งเท่านั้นจาก resize_height, resize_longest_side หรือ auto_size หากไม่ส่งเลยหรือส่งมากกว่าหนึ่งค่า จะได้รับการตอบกลับ 400

Name
resize_height
Type
number
Description
ความสูงใหม่ของโมเดลในหน่วยเมตร ต้องมากกว่า 0 ค่าที่เป็นลบจะได้รับการตอบกลับ 400

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

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

Name
origin_at
Type
string
ค่าเริ่มต้น bottom
Description
ตำแหน่งที่จะวางจุดกำเนิดของโมเดลหลังจากปรับขนาด คือ bottom หรือ center

ผลลัพธ์ที่ส่งคืน

ฟิลด์ result ของการตอบกลับจะเก็บ ID ของงานปรับขนาดใหม่

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

Name
400 - Bad Request
Description
คำขอนี้ไม่สามารถทำงานได้ ข้อความแสดงข้อผิดพลาดจะระบุว่าพบปัญหาใด ตัวอย่างเช่น:
- ขาดพารามิเตอร์: ไม่ได้ส่งทั้ง model_url และ input_task_id
- ขาด resize mode: ไม่ได้ส่งทั้ง resize_height, resize_longest_side และ auto_size
- พารามิเตอร์ที่แยกจากกัน: คำขอมีมากกว่าหนึ่งค่าจาก resize_height, resize_longest_side และ auto_size ให้ส่งเพียงค่าเดียว
- ขนาดเป็นลบ: resize_height หรือ resize_longest_side เป็นค่าลบ
- งานนำเข้าไม่ถูกต้อง: input_task_id ไม่ใช่งาน API ที่สำเร็จและมีไฟล์โมเดล
- รูปแบบโมเดลไม่ถูกต้อง: ไฟล์ model_url มีนามสกุลที่ไม่รองรับ
- URL ไม่สามารถเข้าถึงได้: Meshy ไม่สามารถดาวน์โหลดไฟล์ model_url ได้
- ไฟล์โมเดลมีขนาดใหญ่เกินไป: ไฟล์ model_url มีขนาดเกิน 400 MB จาก URL แบบ http หรือ https หรือเกิน 100 MB ในรูปแบบ data URI
- จำนวนหน้ามากเกินไป: ไฟล์ model_url มีขนาดเกิน 100 MB และมีหน้ามากกว่า 10,000,000 หน้า ให้ลดจำนวนหน้า แล้วส่งไฟล์อีกครั้ง
- ASCII FBX เกิน 100 MB: ไฟล์ model_url เป็น ASCII FBX ที่มีขนาดเกิน 100 MB ให้ส่งเป็น binary FBX หรือ GLB แทน
- ไม่สามารถอ่านไฟล์โมเดลได้: ไฟล์ model_url มีขนาดเกิน 100 MB และ Meshy ไม่สามารถอ่านส่วนหัวของไฟล์ได้ ตัวอย่างเช่น เป็น GLB หรือ glTF ที่บีบอัดด้วย Draco หรือเป็น binary FBX ที่เก่ากว่าเวอร์ชัน 7.1
- ส่วนหัวของโมเดลซับซ้อนเกินไป: ไฟล์ model_url มีขนาดเกิน 100 MB และส่วนหัวมีเมช โหนด หรือเรคคอร์ดมากเกินกว่าจะตรวจสอบได้ ให้ลดจำนวนออบเจกต์ในไฟล์ แล้วส่งอีกครั้ง
แก้ไขคำขอ แล้วส่งใหม่อีกครั้ง ดูที่ ข้อผิดพลาด
Name
401 - Unauthorized
Description
API คีย์หายไปหรือไม่ถูกต้อง ตรวจสอบส่วนหัว Authorization
Name
402 - Payment Required
Description
ตัวอย่างเช่น:
- เครดิตไม่เพียงพอ: บัญชีมีเครดิตไม่เพียงพอสำหรับงานนี้ หรือบัญชีถึงขีดจำกัดเครดิตแล้ว ตรวจสอบยอดเครดิตคงเหลือ แล้วลองใหม่
- แพ็กเกจฟรี: การสร้างงานต้องใช้แพ็กเกจแบบชำระเงิน อัปเกรดแพ็กเกจของคุณได้ที่การตั้งค่าการสมัครสมาชิก แล้วลองใหม่
Name
403 - Forbidden
Description
input_task_id เป็นโมเดลแบบนูนต่ำ (bas-relief) ซึ่งเอนด์พอยต์นี้ไม่สามารถปรับขนาดได้ ข้อความแจ้งคือ This model type does not support this operation ให้ส่งโมเดลอื่นแทน
Name
404 - Not Found
Description
input_task_id ไม่ตรงกับงานใดๆ ของคุณ ตรวจสอบ ID ของงาน แล้วส่งคำขออีกครั้ง
Name
429 - Too Many Requests
Description
คุณเกินการจำกัดอัตราที่กำหนดไว้ กรุณารอสักครู่แล้วลองใหม่ ดูที่ การจำกัดอัตรา

GET/openapi/v1/resize/:id

ดึงข้อมูลงาน Resize

คืนค่างาน Resize ตาม ID ของงานนั้น

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
}

พารามิเตอร์

Name
id
Type
path
Description
ID ของงานจากคำตอบของการสร้าง

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

อ็อบเจ็กต์งาน Resize

DELETE/openapi/v1/resize/:id

ลบงาน Resize

ลบงาน Resize อย่างถาวร รวมถึงโมเดลและข้อมูลของงานนั้น คุณไม่สามารถยกเลิกการลบได้

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

พารามิเตอร์ของพาธ

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

สถานะของงาน

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

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

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

ผลลัพธ์ที่ส่งคืน

200 OK เมื่อลบงานสำเร็จ หรือ 409 Conflict เมื่อสถานะของงานเป็น IN_PROGRESS

GET/openapi/v1/resize

รายการงาน Resize

ส่งคืนรายการงาน 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
  }
]

พารามิเตอร์

Name
page_num
Type
integer
ค่าเริ่มต้น 1
Description
หมายเลขหน้าที่ต้องการส่งคืน สูงสุด 255 หากใส่ค่ามากกว่านี้จะส่งคืน 400

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

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

ส่งคืน

รายการแบบแบ่งหน้าของ อ็อบเจ็กต์งาน Resize

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

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

สตรีมความคืบหน้าของงาน ปรับขนาด ในรูปแบบ 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
}

พารามิเตอร์

Name
id
Type
path
Description
รหัสงานจากการตอบกลับตอนสร้างงาน

ผลลัพธ์ที่ได้

สตรีมของ อ็อบเจกต์งาน ปรับขนาด ในรูปแบบ Server-Sent Events

แต่ละอีเวนต์จะมีอ็อบเจกต์งานฉบับเต็ม ในรูปแบบเดียวกับที่เอนด์พอยต์ Get ส่งกลับมา ขณะที่งานยังอยู่ในสถานะ PENDING หรือ IN_PROGRESS ฟิลด์ผลลัพธ์ต่าง ๆ จะยังไม่มีค่า

The Resize task object

Resize task object อธิบายการปรับขนาดโมเดล 3D หนึ่งครั้ง โดยเก็บสถานะ progress และไฟล์โมเดลเมื่อ task สำเร็จ

Properties

Name
id
Type
string
Description
ID ของ task ให้ถือว่าเป็น string ที่ไม่มีความหมายตายตัว และอย่าอ้างอิงรูปแบบของมัน
Name
type
Type
string
Description
ประเภทของ task ซึ่งเป็น resize เสมอ
Name
model_urls
Type
object
Description
URL สำหรับดาวน์โหลดไฟล์โมเดลที่ปรับขนาดแล้ว สำหรับ input_task_id ไฟล์จะเป็น GLB เสมอ ส่วนสำหรับ model_url ไฟล์ GLB, OBJ, FBX หรือ STL จะคงรูปแบบเดิมไว้ ในขณะที่ไฟล์ .gltf หรือ data URI จะถูกแปลงกลับมาเป็น GLB
Name
progress
Type
integer
Description
task เสร็จไปแล้วเท่าไร แสดงเป็นเปอร์เซ็นต์ โดยจะเป็น 0 จนกว่า task จะเริ่ม และเป็น 100 เมื่อสำเร็จ
Name
status
Type
string
Description
สถานะของ task ซึ่งเป็นหนึ่งใน PENDING, IN_PROGRESS, SUCCEEDED, FAILED, หรือ CANCELED
Name
preceding_tasks
Type
integer
Description
จำนวน task ที่อยู่ก่อนหน้า task นี้ในคิว ค่านี้มีความหมายเฉพาะตอนที่ task มีสถานะเป็น PENDING เท่านั้น
Name
created_at
Type
timestamp
Description
เวลาที่สร้าง task หน่วยเป็นมิลลิวินาทีแบบ Unix
Name
started_at
Type
timestamp
Description
เวลาที่ task เริ่มทำงาน หน่วยเป็นมิลลิวินาทีแบบ Unix โดยจะเป็น 0 จนกว่า task จะเริ่ม
Name
finished_at
Type
timestamp
Description
เวลาที่ task เสร็จสิ้น หน่วยเป็นมิลลิวินาทีแบบ Unix โดยจะเป็น 0 จนกว่า task จะเสร็จสิ้น
Name
expires_at
Type
timestamp
Description
เวลาที่ URL สำหรับดาวน์โหลดของ task จะหมดอายุ หน่วยเป็นมิลลิวินาทีแบบ Unix โดยจะเป็น 0 จนกว่า task จะเสร็จสิ้น
Name
texture_urls
Type
array
Description
URL สำหรับดาวน์โหลดเท็กซ์เจอร์ของโมเดล เมื่อ task สำเร็จ: เป็น array ของ object โดยหนึ่งชุดต่อหนึ่ง texture set แต่ละ object จะมี URL ของ base_color และอาจมี URL ของ metallic, roughness, normal, emission, และ metallic_roughness ด้วย ค่านี้จะเป็น null จนกว่า task จะสำเร็จ และเป็น array ว่างเมื่อโมเดลไม่มีเท็กซ์เจอร์
Name
task_error
Type
object
Description
รายละเอียดข้อผิดพลาดเมื่อ task ล้มเหลว ดู ข้อผิดพลาด
Name
consumed_credits
Type
integer
Description
จำนวนเครดิตที่ task ใช้ไป ซึ่งเป็น 1 สำหรับ Resize task โดยจะเป็น 0 สำหรับ task ที่มีสถานะ FAILED