UV Unwrap API

UV Unwrap API จะสร้าง UV Unwrap คุณภาพสูงสำหรับโมเดล 3D ที่มีอยู่โดยอัตโนมัติ ใช้เป็นขั้นตอนที่จำเป็นก่อนการทำเท็กซ์เจอร์ — หรือเมื่อใดก็ตามที่คุณต้องการเลย์เอาต์ UV ที่สะอาดและไม่ทับซ้อนกันสำหรับเครื่องมือขั้นถัดไป (Blender, Substance Painter, Unreal)

ผลลัพธ์คือ "โมเดลขาว UV" — มีรูปร่างเหมือนอินพุต แต่มีพิกัด UV ใหม่ทั้งหมดและไม่มีเท็กซ์เจอร์จริง (มีแมททีเรียลตัวแทนสีเทาขนาด 2×2 รวมอยู่เพื่อให้สล็อตแมททีเรียลของ glTF ถูกต้องอยู่เสมอ เครื่องมือมาตรฐานจะถือว่าสิ่งนี้ไม่มีเท็กซ์เจอร์)

ข้อจำกัด. Auto UV รองรับเมชที่มีได้สูงสุด 40,000 หน้า ในขณะนี้ — โมเดลที่ใหญ่กว่าจะถูกปฏิเสธด้วย 400; ให้รันรีเมชก่อนเพื่อลดจำนวนโพลิกอน เมชแบบ quad และ n-gon จะถูก ทำให้เป็นสามเหลี่ยม ระหว่างการสร้าง UV ดังนั้นเอาต์พุตจึงเป็นเมชสามเหลี่ยมเสมอ

POST/openapi/v1/uv-unwrap

สร้างงาน UV Unwrap

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

พารามิเตอร์

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

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

    ID ของงาน Meshy API ที่เสร็จสมบูรณ์ ซึ่งมีเอาต์พุต GLB ที่คุณต้องการทำ UV Unwrap (เช่น ผลลัพธ์ของ รูปภาพเป็น 3D, ข้อความเป็น 3D, หรือ รีเมช) งานต้นทางต้องมีสถานะเป็น SUCCEEDED และต้องสร้างไฟล์ GLB แล้ว

    หากเมชต้นทางเกินขีดจำกัดจำนวนหน้า 40,000 หน้า คำขอจะถูกปฏิเสธพร้อม 400 และคุณควรรันรีเมชก่อนเพื่อลดจำนวนโพลิกอนลง

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

    ระบุโมเดล 3D โดยตรงผ่าน URL ที่เข้าถึงได้แบบสาธารณะหรือ Data URI รองรับเฉพาะ .glb เท่านั้น — API อ่านไบนารี glTF และไม่แยกวิเคราะห์รูปแบบอื่น หากต้องการทำ UV Unwrap โมเดลในรูปแบบอื่น (.fbx, .obj, .stl, .gltf) ให้แปลงเป็น .glb ก่อนผ่าน แปลง API จากนั้นส่ง ID งานที่ได้เป็น input_task_id หรือ URL เอาต์พุต GLB ของงานนั้นที่นี่

    สำหรับ Data URI ให้ใช้ MIME type application/octet-stream

    ขีดจำกัด 40,000 หน้าเดียวกันนี้ใช้เหมือนกับ input_task_id: เมชที่มีขนาดเกินจะถูกปฏิเสธพร้อม 400 — รันรีเมชก่อน

ค่าที่ส่งคืน

พร็อพเพอร์ตี result ของการตอบกลับมี id ของงาน UV Unwrap ที่สร้างขึ้นใหม่

โหมดความล้มเหลว

  • Name
    400 - Bad Request
    Description

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

    • พารามิเตอร์ขาดหาย: ต้องระบุ input_task_id หรือ model_url
    • งานอินพุตไม่ถูกต้อง: input_task_id ต้องอ้างอิงถึงงานที่สำเร็จและมีผลลัพธ์เป็น GLB
    • เกินจำนวนหน้า: เมชต้นทางมีจำนวนหน้ามากกว่าขีดจำกัดของ UV Unwrap ให้รันรีเมชก่อน
    • รูปแบบโมเดลไม่ถูกต้อง: model_url ชี้ไปยังไฟล์ที่มีนามสกุลไม่รองรับ
    • URL เข้าถึงไม่ได้: ไม่สามารถดาวน์โหลด model_url ได้
  • Name
    401 - Unauthorized
    Description

    การยืนยันตัวตนล้มเหลว โปรดตรวจสอบ API คีย์ของคุณ

  • Name
    402 - Payment Required
    Description

    เครดิตไม่เพียงพอสำหรับดำเนินงานนี้ UV Unwrap มีค่าใช้จ่าย 5 เครดิตต่อการเรียกหนึ่งครั้ง

  • Name
    404 - Not Found
    Description

    ฟีเจอร์นี้ไม่ได้เปิดใช้งานสำหรับบัญชีของคุณ UV Unwrap ถูกควบคุมด้วยแฟล็ก Statsig ระหว่างการเปิดให้ใช้งาน — ติดต่อฝ่ายสนับสนุนของ Meshy หากคุณต้องการสิทธิ์เข้าถึง

  • Name
    429 - Too Many Requests
    Description

    คุณได้เกินการจำกัดอัตราของคุณแล้ว

Request

POST
/openapi/v1/uv-unwrap
# Chain from an existing Meshy task
curl https://api.meshy.ai/openapi/v1/uv-unwrap \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
      "input_task_id": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
    }'

# Or from a publicly accessible model URL
curl https://api.meshy.ai/openapi/v1/uv-unwrap \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
      "model_url": "https://example.com/path/to/model.glb"
    }'

Response

{
  "result": "019361c6-9b34-7b23-bef2-d0107c4d92e2"
}
GET/openapi/v1/uv-unwrap/:id

ดึงข้อมูลงาน UV Unwrap

เอนด์พอยต์นี้ดึงข้อมูลสถานะปัจจุบันของงาน UV Unwrap ตาม ID

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

ส่งกลับ ออบเจ็กต์งาน UV Unwrap

Request

GET
/openapi/v1/uv-unwrap/:id
curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

ดู ออบเจ็กต์งานตัวอย่าง ด้านล่าง

DELETE/openapi/v1/uv-unwrap/:id

ลบงาน UV Unwrap

ลบงาน UV Unwrap อย่างถาวร งานและผลลัพธ์ของงานนั้นจะไม่สามารถเข้าถึงได้อีก

Request

DELETE
/openapi/v1/uv-unwrap/:id
curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-X DELETE \
-H "Authorization: Bearer ${YOUR_API_KEY}"
GET/openapi/v1/uv-unwrap

แสดงรายการงาน UV Unwrap

ส่งคืนรายการงาน UV Unwrap ของผู้เรียกแบบแบ่งหน้า โดยเรียงจากใหม่สุดก่อน การแบ่งหน้ามาตรฐานผ่าน page_num และ page_size

Request

GET
/openapi/v1/uv-unwrap
curl "https://api.meshy.ai/openapi/v1/uv-unwrap?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"
GET/openapi/v1/uv-unwrap/:id/stream

สตรีมงาน UV Unwrap

สมัครรับข้อมูล progress ของงานในรูปแบบ Server-Sent Events แต่ละเหตุการณ์ message จะมีออบเจ็กต์งาน UV Unwrap; สตรีมจะปิดเมื่องานมีสถานะเป็น SUCCEEDED, FAILED หรือ CANCELED

ใช้สิ่งนี้แทนการโพล GET /openapi/v1/uv-unwrap/:id เพื่อลดความหน่วงเมื่อเสร็จสิ้น

Request

GET
/openapi/v1/uv-unwrap/:id/stream
curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-N

ออบเจ็กต์งาน UV Unwrap

  • Name
    id
    Type
    string
    Description

    ตัวระบุเฉพาะสำหรับงาน

  • Name
    type
    Type
    string
    Description

    เป็น uv-unwrap เสมอ

  • Name
    model_urls
    Type
    object
    Description

    URL ดาวน์โหลดที่ลงนามล่วงหน้าสำหรับโมเดลขาว UV ที่สร้างขึ้น UV Unwrap จะส่งคืนรายการ glb เพียงรายการเดียวเสมอ — เอาต์พุตจะคงจีออเมทรีของอินพุตไว้ สลับไปใช้พิกัด UV ใหม่ และใช้แมททีเรียลสีเทาเริ่มต้นแทนเท็กซ์เจอร์ใดๆ

  • Name
    thumbnail_url
    Type
    string
    Description

    URL ที่ลงนามล่วงหน้าไปยังตัวอย่าง PNG ของโมเดลขาว UV

  • Name
    progress
    Type
    integer
    Description

    progress ของงาน ตั้งแต่ 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

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

  • Name
    started_at
    Type
    timestamp
    Description

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

  • Name
    finished_at
    Type
    timestamp
    Description

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

  • Name
    expires_at
    Type
    timestamp
    Description

    ไทม์สแตมป์หลังจากที่ URL ดาวน์โหลดที่ลงนามไว้จะหมดอายุ หน่วยเป็นมิลลิวินาที

  • Name
    task_error
    Type
    object
    Description

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

  • Name
    consumed_credits
    Type
    integer
    Description

    เครดิตที่งานนี้ใช้ไป ส่งคืน 0 สำหรับงาน FAILED (เครดิตจะได้รับการคืนเมื่อเกิดความล้มเหลว) UV Unwrap คิดค่าบริการ 5 เครดิตเมื่อสำเร็จ

Example UV Unwrap Task Object

{
  "id": "019361c6-9b34-7b23-bef2-d0107c4d92e2",
  "type": "uv-unwrap",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019361c6-9b34-7b23-bef2-d0107c4d92e2/output/model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019361c6-9b34-7b23-bef2-d0107c4d92e2/output/preview.png?Expires=***",
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1716579120000,
  "started_at": 1716579122000,
  "finished_at": 1716579180000,
  "expires_at": 1716665580000,
  "task_error": {
    "message": ""
  },
  "consumed_credits": 5
}