แปลง API

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

POST/openapi/v1/convert

Create a Convert Task

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

พารามิเตอร์

ต้องระบุ 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

  • 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 ได้
  • 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