Meshy API Webhooks vs Polling: เมื่อผลลัพธ์พร้อมใช้งาน

งานการสร้างด้วย Meshy API (Text to 3D, Image to 3D, Rigging และอื่น ๆ) ทำงานแบบอะซิงโครนัส — คุณส่งงานแล้วจากนั้นจึงต้องตรวจสอบว่าเสร็จสิ้นเมื่อใดก่อนดึงผลลัพธ์ บทความนี้อธิบายวงจรชีวิตของงานและสองวิธีที่รองรับในการทราบว่างานเสร็จสิ้นแล้ว: polling และ webhooks — พร้อมวิธีหลีกเลี่ยงปัญหาที่พบบ่อยที่สุดอย่าง "errors retrieving the model"

งานการสร้างทุกรายการจะเคลื่อนผ่านชุดสถานะเล็กๆ ซึ่งส่งคืนมาในฟิลด์ status ของออบเจ็กต์งาน:

• PENDING — งานถูกจัดเข้า คิวแล้วแต่ยังไม่ได้เริ่มประมวลผล

• IN_PROGRESS — งานกำลังถูกประมวลผลอยู่ ฟิลด์ progress (0-100) จะเพิ่มขึ้นเมื่อการทำงานคืบหน้า

• SUCCEEDED — งานเสร็จสมบูรณ์แล้วและ progress เป็น 100 URL ของผลลัพธ์ (ไฟล์โมเดล เท็กซ์เจอร์ ภาพตัวอย่าง) พร้อมใช้งานใน response แล้ว

• FAILED — งานไม่สามารถเสร็จสมบูรณ์ได้ เครดิตสำหรับงานที่ล้มเหลวจะถูกคืนอัตโนมัติ

• CANCELED — งานถูกยกเลิกก่อนที่จะเสร็จสมบูรณ์

กฎที่สำคัญที่สุดเพียงข้อเดียวเมื่อเชื่อมต่อกับ API: ห้ามพยายามดึงหรือใช้ URL ของผลลัพธ์จนกว่าสถานะ status ของงานจะเป็น SUCCEEDED การอ่านผลลัพธ์ในขณะที่งานยังเป็น PENDING หรือ IN_PROGRESS คือสาเหตุที่พบบ่อยที่สุดของรายงาน "errors retrieving the model"

การ Polling หมายถึงการเรียก endpoint "get task" ซ้ำๆ ด้วย task ID ของคุณ จนกว่างานจะเข้าสู่สถานะสุดท้าย (SUCCEEDED, FAILED หรือ CANCELED) ลูปการ Polling แบบง่ายมีลักษณะดังนี้:

• ส่งคำขอสร้างและบันทึก task id ที่ได้รับกลับมา

• เรียก endpoint "retrieve task" ที่เกี่ยวข้อง (เช่น endpoint ระบุงานตาม ID ของ Text to 3D หรือ Image to 3D) ตามช่วงเวลาที่กำหนด — โดยทั่วไปคือทุกๆ สองสามวินาที

• ตรวจสอบฟิลด์ status ในแต่ละการตอบกลับ ให้ Polling ต่อไปตราบใดที่สถานะยังเป็น PENDING หรือ IN_PROGRESS

• หยุด Polling ทันทีที่ status เป็น SUCCEEDED (อ่าน URL ของผลลัพธ์), FAILED หรือ CANCELED

• เพิ่มการป้องกันด้วย timeout/จำนวนครั้งสูงสุดที่เหมาะสมในไคลเอนต์ของคุณ เพื่อไม่ให้งานที่ค้างอยู่ถูก Polling ไปตลอด

การ Polling นั้นง่ายและเหมาะกับสคริปต์ งานแบบแบตช์ และการเชื่อมต่อที่มีปริมาณต่ำ สำหรับการเชื่อมต่อที่มีปริมาณสูงหรือต้องการความหน่วงต่ำ โดยปกติแล้ว webhook จะเหมาะกว่า

แทนที่จะถามซ้ำๆ ว่า "เสร็จหรือยัง?" คุณสามารถให้ Meshy แจ้งเตือนเซิร์ฟเวอร์ของคุณทันทีที่งานเสร็จสิ้น การใช้ webhooks:

• กำหนดค่า URL ของ webhook (callback) ที่ Meshy สามารถเข้าถึงได้ — โดยทั่วไปจะตั้งค่าที่ระดับการตั้งค่าบัญชี/API หรือส่งเป็นพารามิเตอร์ในคำขอสร้าง ขึ้นอยู่กับ endpoint

• ตรวจสอบให้แน่ใจว่า endpoint ของคุณเข้าถึงได้แบบสาธารณะผ่าน HTTPS และตอบสนองอย่างรวดเร็ว (ส่งคืนสถานะ 2xx ทันที จากนั้นประมวลผล payload แบบอะซิงโครนัส)

• เมื่องานถึงสถานะสิ้นสุด Meshy จะส่ง payload ไปยัง endpoint ของคุณซึ่งมี id ของงานและ status สุดท้าย

• เมื่อได้รับ ให้ค้นหารายละเอียดงานแบบเต็มโดยใช้ id ผ่าน API แทนที่จะเชื่อถือเนื้อหา webhook เพียงอย่างเดียว เพื่อให้แน่ใจว่าคุณได้ผลลัพธ์ที่เป็นทางการและเป็นปัจจุบัน

Webhooks ช่วยลดการเรียก API ที่ไม่จำเป็นและแจ้งเตือนคุณได้เกือบจะทันที แต่คุณยังควรมี polling เป็น fallback เป็นระยะสำหรับงานที่การส่ง webhook อาจถูกพลาดหรือล่าช้า (เช่น เนื่องจากปัญหาเครือข่ายชั่วคราวฝั่งคุณ)

ไม่ว่าคุณจะใช้ polling หรือ webhooks โค้ดจัดการผลลัพธ์ของคุณควรทำงานซ้ำโดยไม่เปลี่ยนผลลัพธ์ (idempotent) — กล่าวคือ เรียกใช้ซ้ำได้มากกว่าหนึ่งครั้งสำหรับงานเดียวกันโดยไม่มีผลข้างเคียง สิ่งนี้สำคัญเพราะ:

• webhook อาจถูกส่งมาถึงมากกว่าหนึ่งครั้งสำหรับงานเดียวกัน (การลองใหม่จากฝั่งผู้ส่ง การทำสำเนาข้อมูลในเครือข่าย ฯลฯ)

• ลูป polling และตัวจัดการ webhook อาจพยายามประมวลผลงานที่เสร็จสมบูรณ์แล้วงานเดียวกันพร้อมกัน หากทั้งสองอย่างทำงานอยู่

เพื่อให้คงความสามารถในการทำงานซ้ำโดยไม่เปลี่ยนผลลัพธ์ ให้ใช้ id ของงานเป็นกุญแจในตรรกะการประมวลผลของคุณ — ตัวอย่างเช่น ตรวจสอบว่าคุณได้จัดเก็บหรือดาวน์โหลดผลลัพธ์สำหรับ id นั้นไปแล้วหรือไม่ก่อนที่จะทำซ้ำ และทำให้ "ทำเครื่องหมายว่าประมวลผลแล้ว" เป็นขั้นตอนเดียวแบบอะตอมมิกในฐานข้อมูลของคุณ

การตอบกลับที่มี "status": "SUCCEEDED" และ "progress": 100 เป็นสัญญาณเดียวที่รับประกันว่าข้อมูลผลลัพธ์ (URL ของโมเดล เท็กซ์เจอร์ และภาพขนาดย่อ) จะครบถ้วนและพร้อมใช้งานได้อย่างปลอดภัย ในโค้ดของคุณ ให้ทำดังนี้:

• ตรวจสอบ status === "SUCCEEDED" ก่อนที่จะอ่านค่าใดๆ จากฟิลด์ result หรือ URL ของโมเดล

• อย่าอาศัยเพียง progress — ควรตรวจสอบ status ด้วยเสมอ เนื่องจาก progress อาจแสดงค่าสูงขึ้นชั่วคราวก่อนที่งานจะเสร็จสมบูรณ์

• ดาวน์โหลดไฟล์ผลลัพธ์โดยเร็วเมื่อได้ SUCCEEDED — ทรัพยากรที่สร้างขึ้นจะถูกเก็บไว้บนเซิร์ฟเวอร์ของ Meshy ในระยะเวลาจำกัด หลังจากนั้น URL จะไม่สามารถเข้าถึงได้อีก

รายงานส่วนใหญ่ที่ว่า "ฉันดึงโมเดลของฉันไม่ได้" มักเกิดจากสาเหตุใดสาเหตุหนึ่งต่อไปนี้:

• ดึงผลลัพธ์เร็วเกินไป การเรียก URL ผลลัพธ์ หรือการอ่านฟิลด์ของโมเดล ก่อนที่ status จะเป็น SUCCEEDED ซึ่งเป็นสาเหตุที่พบบ่อยที่สุด

• แอสเซ็ตหมดอายุ การรอ слишком นานเกินไปหลัง SUCCEEDED ก่อนดาวน์โหลด — URL ผลลัพธ์จะหยุดใช้งานได้หลังจากพ้นช่วงเวลาการเก็บรักษาสำหรับงานประเภทนั้น

• ใช้ task ID ที่เก่าหรือผิด — ตัวอย่างเช่น นำ ID จากคำขอก่อนหน้าที่ไม่เกี่ยวข้องกันมาใช้ซ้ำ

• ถือว่า FAILED เป็นสถานะชั่วคราว และยังคง polling งานที่ล้มเหลวไปแล้วแทนที่จะส่งคำขอใหม่

• ปัญหาเครือข่าย/หมดเวลา ระหว่างเซิร์ฟเวอร์ของคุณกับ Meshy ซึ่งถูกตีความผิดว่าเป็นปัญหาการสร้าง

หากการสร้างไม่ตรงกับความคาดหวังของคุณ หรือคำขอล้มเหลวโดยสิ้นเชิง โปรดคำนึงถึงสิ่งต่อไปนี้:

• ปัจจุบัน Meshy API ไม่รองรับการลองใหม่งานที่มีอยู่เดิมในตำแหน่งเดิม — หากต้องการลองอีกครั้ง ให้ส่งคำขอสร้างใหม่ ซึ่งจะใช้เครดิตตามปกติ

• สำหรับความล้มเหลวของเครือข่ายชั่วคราวเมื่อเรียก API (timeout, การตอบกลับ 5xx) การรอแบบ exponential backoff ช่วงสั้นๆ ก่อนส่งคำขออีกครั้งถือว่าเหมาะสม

• สำหรับการ polling เอง ให้ลองใหม่การเรียก "get task" เมื่อเกิดข้อผิดพลาดของเครือข่ายชั่วคราว แต่ไม่ควรถือว่าการ poll ที่ล้มเหลวเพียงครั้งเดียวเป็นการสร้างที่ล้มเหลว — ให้เชื่อถือฟิลด์ status ก็ต่อเมื่อได้รับการตอบกลับที่สำเร็จแล้วเท่านั้น

• หากคุณต้องการฟังก์ชันการลองใหม่ในตัวสำหรับการสร้าง โปรดติดต่อทีมขายของ Meshy เพื่อสอบถามเกี่ยวกับตัวเลือกแผน enterprise

สาเหตุเกือบทุกครั้งคือโค้ดพยายามอ่านผลลัพธ์ก่อนที่งานจะเสร็จสิ้น ควรตรวจสอบว่า status เป็น SUCCEEDED (และ progress เป็น 100) ก่อนดึง URL ของโมเดลเสมอ

Polling ตั้งค่าได้ง่ายกว่าและเหมาะกับสคริปต์ที่ใช้งานปริมาณน้อยหรือใช้งานครั้งเดียว ส่วน Webhooks เหมาะกับการผสานรวมในสภาพแวดล้อม production ที่มีงานหลายอย่างทำงานพร้อมกัน เนื่องจากช่วยหลีกเลี่ยงการส่งคำขอซ้ำโดยไม่จำเป็นและแจ้งเตือนคุณทันทีเมื่องานเสร็จสิ้น

จัดการแบบ idempotent (การทำงานซ้ำโดยไม่เปลี่ยนผลลัพธ์) — ตรวจสอบ id ของงานกับรายการที่คุณประมวลผลไปแล้ว และข้ามการประมวลผลซ้ำหากจัดการไปแล้ว

ให้เปลี่ยนไปใช้การ polling งานด้วย id โดยตรงแทน นอกจากนี้ควรตรวจสอบว่า endpoint ของคุณเข้าถึงได้จากภายนอกผ่าน HTTPS และตอบกลับด้วย 2xx อย่างรวดเร็ว เนื่องจาก endpoint ที่ตอบช้าหรือเข้าถึงไม่ได้อาจทำให้เกิดปัญหาในการส่ง webhook

ยังไม่สามารถทำได้ในขณะนี้ — คุณต้องส่งคำขอสร้างใหม่ ซึ่งจะใช้เครดิตตามปกติ หากต้องการการสนับสนุนการลองใหม่ในตัว โปรดติดต่อฝ่ายขายเกี่ยวกับตัวเลือกสำหรับองค์กร

ไฟล์ผลลัพธ์จะถูกเก็บไว้บนเซิร์ฟเวอร์ของ Meshy ในระยะเวลาจำกัดหลังงานเสร็จสิ้น ดังนั้นควรดาวน์โหลดผลลัพธ์ไปยังที่จัดเก็บของคุณเองทันทีที่งานสำเร็จ แทนที่จะรอ