lowpoly จะยุติการให้บริการในวันที่ 30 ต.ค. 2569 โปรดเปลี่ยนโมเดลก่อนวันที่เหล่านี้เพื่อหลีกเลี่ยงข้อผิดพลาดของคำขอ

Resize API

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

POST/openapi/v1/resize

สร้าง Resize Task

เอนด์พอยต์นี้สร้างงาน resize ใหม่

งานนี้ทำงานอยู่เบื้องหลัง สำหรับระยะเวลาที่มักใช้ โปรดดูที่ Processing Times

พารามิเตอร์

ต้องระบุเพียงหนึ่งเดียวระหว่าง 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 URL แบบ .glb, .obj, .fbx หรือ .stl จะคงรูปแบบเดิมไว้ในผลลัพธ์ ส่วน URL แบบ .gltf หรือ data URI จะได้ผลลัพธ์เป็น GLB

    ขนาดไฟล์สูงสุด: 400 MB สำหรับ URL แบบ http หรือ https, 100 MB สำหรับ data: URI

    ไฟล์ GLB, glTF, FBX หรือ OBJ ที่มีขนาดเกิน 100 MB สามารถมีจำนวนหน้า (faces) ได้สูงสุด 10,000,000 หน้า โดยนับหน้าเป็นรูปสามเหลี่ยม: รูปสี่เหลี่ยมนับเป็น 2 หน้า และเมชที่ถูกวาดซ้ำมากกว่าหนึ่งครั้งจะนับหนึ่งครั้งต่อสำเนา สำหรับไฟล์ที่มีขนาดเกิน 100 MB ไฟล์ FBX ต้องเป็น binary FBX เวอร์ชัน 7.1 ขึ้นไป และไฟล์ GLB หรือ glTF ต้องไม่ใช้การบีบอัดแบบ Draco

ต้องระบุ resize 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 ของงาน resize ที่เพิ่งสร้างขึ้นใหม่

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

  • 400 - Bad Request

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

  • ขาดพารามิเตอร์: ต้องระบุ model_url หรือ input_task_id อย่างใดอย่างหนึ่ง
  • ขาด resize mode: ต้องระบุอย่างน้อยหนึ่งใน resize_height, resize_longest_side หรือ auto_size
  • พารามิเตอร์ที่ใช้แทนกันไม่ได้: resize_height, resize_longest_side และ auto_size ไม่สามารถใช้ร่วมกันได้
  • งานอินพุตไม่ถูกต้อง: input_task_id ต้องอ้างอิงถึงงานที่สำเร็จแล้ว
  • รูปแบบโมเดลไม่ถูกต้อง: model_url ชี้ไปยังไฟล์ที่มีนามสกุลที่ไม่รองรับ
  • ไม่สามารถเข้าถึง URL ได้: ไม่สามารถดาวน์โหลด 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 และไม่สามารถอ่านส่วนหัวได้ ตัวอย่างเช่น GLB หรือ glTF ที่บีบอัดแบบ Draco หรือ binary FBX ที่เก่ากว่าเวอร์ชัน 7.1
  • ส่วนหัวของโมเดลซับซ้อนเกินไป: ไฟล์ model_url มีขนาดเกิน 100 MB และส่วนหัวมีจำนวนเมช โหนด หรือเรคคอร์ดมากเกินกว่าจะตรวจสอบได้ โปรดลดจำนวนออบเจกต์ในไฟล์แล้วส่งอีกครั้ง
  • 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

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

  • type · string

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

  • model_urls · object

URL สำหรับดาวน์โหลดไฟล์โมเดลที่ปรับขนาดแล้ว เมื่อใช้ input_task_id ผลลัพธ์จะเป็น GLB เสมอ เมื่อใช้ model_url อินพุตที่เป็น .glb, .obj, .fbx หรือ .stl จะคงรูปแบบเดิมไว้ ส่วนอินพุตที่เป็น .gltf หรือ Data URI จะให้ผลลัพธ์เป็น GLB

  • progress · integer

progress ของงาน (0-100)

  • status · string

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

  • preceding_tasks · integer

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

  • created_at · timestamp

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

  • started_at · timestamp

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

  • finished_at · timestamp

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

  • task_error · object

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

  • consumed_credits · integer

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