แปลง API

แปลงโมเดล 3D เป็นรูปแบบไฟล์อื่น จากงาน Meshy หรือจากไฟล์โมเดล

POST/openapi/v1/convert

สร้างงาน Convert

สร้างงาน Convert งานนี้จะทำงานในเบื้องหลัง ดูระยะเวลาที่งานมักใช้ได้ที่ Processing times

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

พารามิเตอร์

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

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 มีจำนวนหน้า (faces) ได้สูงสุด 10,000,000 หน้า Meshy นับหน้าเป็นรูปสามเหลี่ยม ดังนั้นรูปสี่เหลี่ยมจะนับเป็น 2 หน้า และเมชที่ถูกวาดซ้ำมากกว่าหนึ่งครั้งจะนับหนึ่งครั้งต่อสำเนา
- ไฟล์ FBX ต้องเป็น binary FBX เวอร์ชัน 7.1 ขึ้นไป
- ไฟล์ GLB หรือ glTF ต้องไม่ใช้การบีบอัดแบบ Draco

Name
target_formats
Type
string[]
จำเป็น
Description
รูปแบบไฟล์ที่จะสร้าง ต้องระบุอย่างน้อยหนึ่งรูปแบบ หากไม่ระบุหรือเป็นรายการว่าง จะคืนค่า 400
ค่าที่ใช้ได้:
- glb
- fbx
- obj
- usdz
- blend
- stl
- 3mf

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

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

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

Name
400 - Bad Request
Description
คำขอนี้ไม่สามารถทำงานได้ ข้อความแสดงข้อผิดพลาดจะระบุปัญหาที่พบ ตัวอย่างเช่น:
- ขาดพารามิเตอร์: ไม่ได้ส่งทั้ง model_url และ input_task_id
- ขาด target_formats: target_formats ขาดหายไปหรือไม่มีรูปแบบใดเลยในรายการ
- งานอินพุตไม่ถูกต้อง: 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 คีย์หรือ API คีย์ไม่ถูกต้อง ตรวจสอบ header 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/convert/:id

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

คืนค่างาน Convert ตามรหัส ID ของงานนั้น

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

พารามิเตอร์

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

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

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

DELETE/openapi/v1/convert/:id

ลบงาน Convert

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

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 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/convert

List Convert tasks

คืนค่ารายการงาน Convert ของคุณ

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

พารามิเตอร์

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: ใหม่สุดก่อน

ค่าที่คืนกลับ

รายการแบบแบ่งหน้าของ Convert task objects

GET/openapi/v1/convert/:id/stream

สตรีมงาน Convert

สตรีมการอัปเดตของงาน Convert ในรูปแบบ Server-Sent Events (SSE)

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
}

พารามิเตอร์

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

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

สตรีมของ Convert task objects ในรูปแบบ Server-Sent Events

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

วัตถุงาน Convert

วัตถุงาน Convert อธิบายการแปลงรูปแบบไฟล์ของโมเดล 3D หนึ่งงาน โดยจะเก็บสถานะ, progress และไฟล์โมเดลเมื่องานสำเร็จ

Properties

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