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

แปลง API

แปลง API ช่วยให้คุณสามารถแปลงโมเดล 3D ที่มีอยู่ให้เป็นรูปแบบไฟล์อื่นได้

POST/openapi/v1/convert

Create a Convert Task

เอนด์พอยต์นี้สร้างงานแปลงรูปแบบไฟล์ใหม่

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

พารามิเตอร์

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

  • Name
    input_task_id
    Type
    string
    จำเป็น
    Description

    ID ของงาน Meshy ที่เสร็จสมบูรณ์แล้วซึ่งมีโมเดลที่คุณต้องการแปลง งานนั้นต้องมีสถานะเป็น SUCCEEDED

  • Name
    model_url
    Type
    string
    จำเป็น
    Description

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

    ขนาดไฟล์สูงสุด: 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

  • Name
    target_formats
    Type
    string[]
    จำเป็น
    Description

    รายการรูปแบบเอาต์พุตสำหรับโมเดลที่แปลงแล้ว ค่าที่ใช้ได้: glb, fbx, obj, usdz, blend, stl, 3mf

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

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

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

  • 400 - Bad Request

คำขอนี้ไม่สามารถยอมรับได้ สาเหตุทั่วไปได้แก่:

  • ขาดพารามิเตอร์: ต้องระบุ model_url หรือ input_task_id อย่างใดอย่างหนึ่ง
  • ขาด target_formats: ต้องระบุรูปแบบเป้าหมายอย่างน้อยหนึ่งรายการ
  • งานอินพุตไม่ถูกต้อง: 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/convert
curl https://api.meshy.ai/openapi/v1/convert \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["fbx", "stl"]
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}
GET/openapi/v1/convert/:id

ดึงข้อมูลงานแปลง

เอนด์พอยต์นี้ใช้สำหรับดึงข้อมูลงานแปลงตามรหัส ID ของงานนั้น

พารามิเตอร์

  • Name
    id
    Type
    path
    Description

    รหัส ID ของงานแปลงที่ต้องการดึงข้อมูล

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

ออบเจ็กต์ Convert Task

Request

GET
/openapi/v1/convert/:id
curl https://api.meshy.ai/openapi/v1/convert/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "convert",
  "model_urls": {
      "glb": "",
      "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
      "obj": "",
      "usdz": "",
      "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}
DELETE/openapi/v1/convert/:id

ลบ Convert Task

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

พารามิเตอร์พาธ (Path Parameters)

  • Name
    id
    Type
    path
    Description

    ID ของ convert task ที่ต้องการลบ

สถานะของ Task

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

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

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

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

ส่งกลับ 200 OK เมื่อสำเร็จ หรือ 409 Conflict เมื่อ task อยู่ในสถานะ IN_PROGRESS

Request

DELETE
/openapi/v1/convert/:id
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/convert/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/convert

List Convert 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 Convert Task Objects

Request

GET
/openapi/v1/convert
curl https://api.meshy.ai/openapi/v1/convert?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "convert",
    "model_urls": {
      "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
      "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null,
    "consumed_credits": 1
  }
]
GET/openapi/v1/convert/:id/stream

สตรีมงานแปลง

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

พารามิเตอร์

  • Name
    id
    Type
    path
    Description

    ตัวระบุเฉพาะสำหรับงานแปลงที่ต้องการสตรีม

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

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

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

Request

GET
/openapi/v1/convert/:id/stream
curl -N https://api.meshy.ai/openapi/v1/convert/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": "convert",
  "model_urls": {
    "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
    "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}

The Convert Task Object

Convert Task object แสดงถึงงานแปลงรูปแบบไฟล์

Properties

  • id · string

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

  • type · string

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

  • model_urls · object

URL สำหรับดาวน์โหลดไฟล์โมเดลที่แปลงแล้ว มีเฉพาะรูปแบบที่ระบุใน target_formats เท่านั้นที่จะมี URL ส่วนคุณสมบัติของรูปแบบอื่นจะเป็นสตริงว่าง

  • 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