ข้อความเป็น 3D API

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

ข้อความเป็น 3D ใช้เวิร์กโฟลว์แบบสองขั้นตอน ขั้นแรก ให้สร้างงาน preview (mode: "preview") เพื่อสร้างเมช 3D โดยไม่มีเท็กซ์เจอร์ เพื่อให้คุณสามารถประเมินรูปทรงได้ จากนั้น ส่ง task ID ของ preview ที่เสร็จสมบูรณ์แล้วไปยังงาน refine (mode: "refine") เพื่อนำเท็กซ์เจอร์มาใส่ในเมช ทั้งสองขั้นตอนใช้เอนด์พอยต์เดียวกัน

POST/openapi/v2/text-to-3d

สร้างงาน Text to 3D Preview

เอนด์พอยต์นี้สร้างงาน Text to 3D preview ซึ่งสร้างเมช 3D ที่ยังไม่มีพื้นผิว (จีออเมทรีเท่านั้น) จาก prompt ที่เป็นข้อความ นี่เป็นขั้นตอนแรกของเวิร์กโฟลว์สองขั้นตอน เมื่อ preview สำเร็จแล้ว ให้ใช้ task ID ที่ได้รับคืนมาเพื่อสร้างงาน refine สำหรับการใส่พื้นผิว อ้างอิง The Text to 3D Task Object สำหรับ response schema แบบเต็ม

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

พารามิเตอร์

Name
mode
Type
string
จำเป็น
Description
ฟิลด์นี้ควรตั้งเป็น "preview" เมื่อสร้างงาน preview
Name
prompt
Type
string
จำเป็น
Description
อธิบายว่าโมเดล 3D เป็นวัตถุชนิดใด สูงสุด 800 ตัวอักษร
Name
model_type
Type
string
ค่าเริ่มต้น standard
Description
ระบุประเภทของการสร้างเมช 3D
ค่าที่ใช้ได้:
- standard: การสร้างเมช 3D แบบรายละเอียดสูงทั่วไป
- smart-topology: เลือกโมเดล Smart Topology ด้วย ai_model (meshy-t2)
- lowpoly (เลิกใช้ และจะถูกยกเลิกในวันที่ 30 ตุลาคม 2026): สร้างเมชแบบโลว์โพลีที่ปรับให้เหมาะกับโพลิกอนที่สะอาดขึ้น เราแนะนำให้ใช้ Meshy T2 แทน: smart-topology กับ meshy-t2
เมื่อเลือก smart-topology แล้ว should_remesh และ decimation_mode จะถูกละเว้น และรับเฉพาะ topology: triangle เท่านั้น
lowpoly จะถูกยกเลิกในวันที่ 30 ตุลาคม 2026 หลังจากวันดังกล่าว คำขอที่มี model_type: "lowpoly" จะได้รับข้อผิดพลาดกลับมา เราแนะนำให้เปลี่ยนไปใช้ Meshy T2 (model_type: "smart-topology" ร่วมกับ ai_model: "meshy-t2") เมื่อเลือก lowpoly แล้ว ai_model, topology, target_polycount และ should_remesh จะถูกละเว้น
Name
ai_model
Type
string
ค่าเริ่มต้น latest
Description
ID ของโมเดลที่จะใช้ ค่าที่ใช้ได้ขึ้นอยู่กับ model_type
การสร้างแบบ Standard (model_type: standard):
- meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
- meshy-7 (เลิกใช้): ใช้ meshy-7.1 แทน
การสร้างแบบ Smart Topology (model_type: smart-topology):
- meshy-t2 (ค่าเริ่มต้น): โมเดล Smart Topology — topology ที่สะอาดขึ้น มีการแยกชิ้นส่วนตามธรรมชาติ ผลลัพธ์เป็นสามเหลี่ยม และสามารถกำหนดจำนวนหน้าได้ด้วย target_polycount
Name
geometry_resolution
Type
string
ค่าเริ่มต้น standard
Description
รอบการสร้างจีออเมทรี 2k จะรัน Ultra pass ที่ 2048³; 4k จะรันที่ 4096³ เพื่อ รายละเอียดพื้นผิวที่ละเอียดที่สุด
ค่าที่ใช้ได้: standard, 2k, 4k
รองรับเฉพาะใน mode preview เท่านั้น ต้องใช้ meshy-7.1 หรือ latest
Name
ultra_mode
Type
boolean
⚠ เลิกใช้แล้ว
ค่าเริ่มต้น false
Description
ใช้ geometry_resolution แทน ultra_mode: true เทียบเท่ากับ geometry_resolution: "2k"
Name
should_remesh
Type
boolean
ค่าเริ่มต้น false (Meshy 6 and Meshy 7 models), true (others)
Description
ควบคุมว่าจะเปิดใช้งานขั้นตอน remesh หรือไม่ สำหรับโมเดลคุณภาพสูงสุด เราแนะนำให้ตั้งค่า should_remesh เป็น false

ใช้เฉพาะเมื่อ should_remesh = true

Name
topology
Type
string
ค่าเริ่มต้น triangle
Description
ระบุ topology ของโมเดลที่สร้างขึ้น
ค่าที่ใช้ได้:
- quad: สร้างเมชที่ส่วนใหญ่เป็นรูปสี่เหลี่ยม
- triangle: สร้างเมชสามเหลี่ยมแบบลดจำนวนโพลิกอน
ผลลัพธ์ของ Smart Topology เป็นสามเหลี่ยมเท่านั้น การร้องขอ quad ร่วมกับ ai_model: meshy-t2 จะได้รับข้อผิดพลาดกลับมา
Name
decimation_mode
Type
integer
Description
เปิดใช้งานการลดจำนวนโพลิกอนแบบปรับตัวโดยการตั้งค่าระดับจำนวนโพลิกอน เมื่อตั้งค่านี้ target_polycount จะถูกละเว้น
ค่าที่ใช้ได้:
- 1: แบบปรับตัว — จำนวนโพลิกอนสูงสุด
- 2: แบบปรับตัว — จำนวนโพลิกอนสูง
- 3: แบบปรับตัว — จำนวนโพลิกอนปานกลาง
- 4: แบบปรับตัว — จำนวนโพลิกอนต่ำ

Name
target_polycount
Type
integer
Description
จำนวนโพลิกอน (หน้า) เป้าหมายในผลลัพธ์ จำนวนจริงอาจเบี่ยงเบนจากเป้าหมายขึ้นอยู่กับจีออเมทรี
target_polycount มีผลใน 2 กรณีที่เป็นอิสระต่อกัน:
- Remesh — กับ should_remesh: true บนโมเดล standard เมชจะถูกรีเมช (ลดจำนวนโพลิกอน) ให้ใกล้เคียงกับจำนวนนี้ ช่วงตั้งแต่ 100 ถึง 300,000 ค่าเริ่มต้น 30,000 หากตั้งค่า decimation_mode ไว้ จะมีลำดับความสำคัญเหนือกว่า และ target_polycount จะถูกละเว้น
- Smart Topology — กับ model_type: smart-topology และ ai_model: meshy-t2 โมเดลจะถูกสร้างขึ้นโดยตรงด้วยจำนวนหน้านี้ โดยไม่มีการรัน remesh และไม่จำเป็นต้องใช้ should_remesh ช่วงตั้งแต่ 100 ถึง 15,000 ค่าเริ่มต้น 4,000

Name
symmetry_mode
Type
string
⚠ เลิกใช้แล้ว
ค่าเริ่มต้น auto
Description
เลิกใช้แล้ว พารามิเตอร์นี้ไม่มีผลต่อผลลัพธ์อีกต่อไป
ฟิลด์ symmetry_mode ควบคุมพฤติกรรมของสมมาตรระหว่างกระบวนการสร้างโมเดล
ค่าที่ใช้ได้มีดังนี้:
- off: ปิดใช้งานสมมาตร
- auto: กำหนดและใช้สมมาตรโดยอัตโนมัติตามจีออเมทรีของอินพุต
- on: บังคับใช้สมมาตรระหว่างการสร้าง
Name
pose_mode
Type
string
ค่าเริ่มต้น ""
Description
ระบุ pose mode สำหรับโมเดลที่สร้างขึ้น
ค่าที่ใช้ได้:
- a-pose: สร้างโมเดลในท่า A
- t-pose: สร้างโมเดลในท่า T
- "" (สตริงว่าง): ไม่มีการใช้ท่าเฉพาะเจาะจง
Name
is_a_t_pose
Type
boolean
⚠ เลิกใช้แล้ว
ค่าเริ่มต้น false
Description
ใช้ pose_mode แทน ระบุว่าจะสร้างโมเดลในท่า A/T หรือไม่
Name
art_style
Type
string
⚠ เลิกใช้แล้ว
ค่าเริ่มต้น realistic
Description
ไม่รองรับ Meshy-6 คำขอที่ใช้ Meshy-6 จะละเว้น art_style และบางชุดค่าผสมอาจทำให้เกิดข้อผิดพลาด ค่าที่ใช้ได้: realistic, sculpture
enable_pbr ควรตั้งค่าเป็น false เมื่อใช้สไตล์ Sculpture เนื่องจากสไตล์ Sculpture จะสร้างชุด PBR แมปของตัวเอง
Name
moderation
Type
boolean
ค่าเริ่มต้น false
Description
เมื่อตั้งค่าเป็น true เนื้อหาอินพุตจะถูกตรวจสอบโดยอัตโนมัติเพื่อหาเนื้อหาที่อาจเป็นอันตราย หากตรวจพบเนื้อหาที่เป็นอันตราย งานจะไม่ดำเนินการต่อไปยังการสร้าง
ข้อความจาก prompt จะถูกตรวจสอบ
Name
target_formats
Type
string[]
Description
ระบุรูปแบบไฟล์ 3D ที่จะรวมอยู่ในผลลัพธ์ จะมีการสร้างและส่งคืนเฉพาะรูปแบบที่ร้องขอเท่านั้น ซึ่งสามารถลดเวลาที่ใช้ในการทำงานให้เสร็จสมบูรณ์ได้ เมื่อไม่ระบุ จะรวมรูปแบบที่รองรับทั้งหมด
ค่าที่ใช้ได้: glb, obj, fbx, stl, usdz, 3mf
เมื่อไม่ระบุ จะมีการสร้างรูปแบบทั้งหมดยกเว้น 3mf โดย 3mf จะรวมอยู่ด้วยก็ต่อเมื่อมีการระบุอย่างชัดเจนเท่านั้น
Name
alpha_thumbnail
Type
boolean
ค่าเริ่มต้น false
Description
เมื่อตั้งค่าเป็น true งานจะเรนเดอร์เวอร์ชันพื้นหลังโปร่งใส (RGBA) ของ preview เพิ่มเติม และส่งคืนเป็น alpha_thumbnail_url ใน response ของ GET ฟิลด์ thumbnail_url ที่มีอยู่เดิมจะไม่เปลี่ยนแปลง
Name
auto_size
Type
boolean
ค่าเริ่มต้น false
Description
เมื่อตั้งค่าเป็น true บริการจะใช้ AI vision เพื่อประมาณความสูงของวัตถุในโลกจริงโดยอัตโนมัติ และปรับขนาดโมเดลให้สอดคล้องกัน จุดกำเนิดจะเป็น bottom โดยค่าเริ่มต้น เว้นแต่จะตั้งค่า origin_at ไว้อย่างชัดเจน

ใช้เฉพาะเมื่อ auto_size = true

Name
origin_at
Type
string
ค่าเริ่มต้น bottom
Description
ตำแหน่งของจุดกำเนิดเมื่อเปิดใช้งาน auto_size
ค่าที่ใช้ได้: bottom, center

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

คุณสมบัติ result ของ response จะมี id ของงาน Text to 3D ที่สร้างขึ้นใหม่

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

Name
400 - Bad Request
Description
คำขอไม่สามารถยอมรับได้ สาเหตุทั่วไป:
- ขาดพารามิเตอร์: พารามิเตอร์ที่จำเป็น (เช่น prompt, mode) ขาดหายไป
- พารามิเตอร์ไม่ถูกต้อง: art_style ไม่ใช่หนึ่งในค่าที่อนุญาต
- prompt ยาวเกินไป: prompt เกินขีดจำกัดจำนวนตัวอักษร
- โมเดลไม่รองรับ low poly: ai_model: "meshy-6-lite" ไม่รองรับ model_type: "lowpoly"
- โมเดลไม่รองรับ Ultra: geometry_resolution ต้องใช้ meshy-7.1 หรือ latest
Name
401 - Unauthorized
Description
การยืนยันตัวตนล้มเหลว กรุณาตรวจสอบ API คีย์ของคุณ
Name
402 - Payment Required
Description
เครดิตไม่เพียงพอสำหรับการดำเนินงานนี้
Name
429 - Too Many Requests
Description
คุณเกินขีดจำกัดอัตราการใช้งานแล้ว

Request

POST

/openapi/v2/text-to-3d

# Simple preview with required params only
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a monster mask"
}'

# Preview with Ultra 4K geometry, remesh and A-pose
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a futuristic robot warrior",
  "ai_model": "meshy-7.1",
  "geometry_resolution": "4k",
  "should_remesh": true,
  "target_polycount": 100000,
  "pose_mode": "a-pose",
  "target_formats": ["glb"]
}'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

POST/openapi/v2/text-to-3d

สร้าง Task Refine สำหรับข้อความเป็น 3D

เอนด์พอยต์นี้สร้าง task refine สำหรับข้อความเป็น 3D ซึ่งจะใส่เท็กซ์เจอร์ให้กับเมชพรีวิวที่เสร็จสมบูรณ์แล้ว คุณต้องระบุ preview_task_id จากtask พรีวิวที่สำเร็จ นี่คือขั้นตอนที่สองของกระบวนการทำงานสองขั้นตอน

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

พารามิเตอร์

Name
mode
Type
string
จำเป็น
Description
ฟิลด์นี้ควรตั้งค่าเป็น "refine" เมื่อสร้าง refine task
Name
preview_task_id
Type
string
จำเป็น
Description
id ของ preview task ที่เกี่ยวข้อง
สถานะของ preview task ที่ระบุต้องเป็น SUCCEEDED
Name
enable_pbr
Type
boolean
ค่าเริ่มต้น false
Description
สร้าง PBR แมป (metallic, roughness, normal) เพิ่มเติมจาก base color นอกจากนี้ยังมี emission map รวมอยู่ด้วยเมื่อ ai_model เป็น meshy-6 ยกเว้นที่ texture_resolution: 8k (จะไม่มีการสร้าง emission map) meshy-6-lite, meshy-7.1 และ latest จะไม่สร้าง emission map และการ refine ของพรีวิว meshy-t2 ที่ไม่ได้ตั้งค่า ai_model ก็เช่นกัน
Name
texture_resolution
Type
string
ค่าเริ่มต้น 2k
Description
ความละเอียดของเท็กซ์เจอร์ base color หนึ่งในค่า 2k (2048×2048), 4k (4096×4096) หรือ 8k (8192×8192) ความละเอียดที่สูงขึ้นจะจับรายละเอียดพื้นผิวได้มากขึ้น ใช้ได้เฉพาะกับ refine mode เท่านั้น
4k และ 8k ต้องใช้ ai_model เป็น meshy-6, meshy-7.1 หรือ latest ที่ 8k จะไม่มีการสร้าง emission map
Name
hd_texture
Type
boolean
⚠ เลิกใช้แล้ว
ค่าเริ่มต้น false
Description
ใช้ texture_resolution แทน — เทียบเท่ากับ texture_resolution: "4k" เมื่อตั้งค่าทั้งสองอย่าง texture_resolution จะมีความสำคัญกว่า
Name
texture_prompt
Type
string
Description
ระบุ prompt ข้อความเพิ่มเติมเพื่อกำหนดทิศทางกระบวนการใส่เท็กซ์เจอร์ สูงสุด 800 ตัวอักษร
Name
texture_image_url
Type
string
Description
ระบุรูปภาพ 2 มิติเพื่อกำหนดทิศทางกระบวนการใส่เท็กซ์เจอร์ ปัจจุบันรองรับรูปแบบ .jpg, .jpeg, .png และ .webp
ขนาดไฟล์สูงสุด: 20 MB
มีสองวิธีในการระบุรูปภาพ:
- URL ที่เข้าถึงได้แบบสาธารณะ: URL ที่สามารถเข้าถึงได้จากอินเทอร์เน็ตสาธารณะ
- Data URI: data URI ของรูปภาพที่เข้ารหัสแบบ base64 ตัวอย่าง data URI: data:image/jpeg;base64,<your base64-encoded image data>
การใส่เท็กซ์เจอร์จากรูปภาพอาจทำงานได้ไม่ดีนักหากมีความแตกต่างของจีออเมทรีอย่างมากระหว่างแอสเซ็ตต้นฉบับกับรูปภาพที่อัปโหลด สามารถใช้ texture_image_url หรือ texture_prompt เพียงอย่างใดอย่างหนึ่งเท่านั้นในการกำหนดทิศทางกระบวนการใส่เท็กซ์เจอร์ หากระบุทั้งสองพารามิเตอร์ ระบบจะใช้ texture_prompt ในการใส่เท็กซ์เจอร์ให้กับโมเดลโดยค่าเริ่มต้น
Name
ai_model
Type
string
ค่าเริ่มต้น inherited from the preview task
Description
ID ของโมเดลที่จะใช้สำหรับการ refine
ค่าที่ใช้ได้:
- meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
- meshy-7 (เลิกใช้): ใช้ meshy-7.1 แทน
ละเว้นพารามิเตอร์นี้เพื่อสืบทอดโมเดลที่ใช้โดย preview task ซึ่งจะทำให้พรีวิวและ refine ของมันใช้โมเดลเดียวกันตลอดกระบวนการ ระบุค่าอย่างชัดเจนเพื่อแทนที่การสืบทอดนั้น
การระบุ latest อย่างชัดเจนจะถูกตีความที่นี่เหมือนกับที่เกิดขึ้นใน preview task (ปัจจุบันคือ Meshy 7.1) ดังนั้นพรีวิว latest และ refine latest ของมันจะใช้โมเดลเท็กซ์เจอร์เดียวกันเสมอ
Name
moderation
Type
boolean
ค่าเริ่มต้น false
Description
เมื่อตั้งค่าเป็น true เนื้อหาที่ป้อนเข้ามาจะถูกตรวจสอบโดยอัตโนมัติเพื่อหาเนื้อหาที่อาจเป็นอันตราย หากตรวจพบเนื้อหาที่เป็นอันตราย task จะไม่ดำเนินการต่อไปยังขั้นตอนการสร้าง
ทั้งข้อความจาก texture_prompt และรูปภาพจาก texture_image_url จะถูกตรวจสอบ
Name
remove_lighting
Type
boolean
ค่าเริ่มต้น true
Description
ลบแสงไฮไลต์และเงาออกจากเท็กซ์เจอร์ base color ทำให้ได้ผลลัพธ์ที่สะอาดขึ้นและใช้งานได้ดีกว่าภายใต้การตั้งค่าแสงแบบกำหนดเอง
มีผลเฉพาะเมื่อ ai_model เป็น meshy-6 เท่านั้น meshy-7.1 และ latest จะยอมรับค่านี้แต่ไม่นำไปใช้งาน เช่นเดียวกับการ refine ของพรีวิว meshy-t2 ที่ไม่ได้ตั้งค่า ai_model การตั้งค่านี้กับ meshy-6-lite จะส่งคืนข้อผิดพลาด
Name
target_formats
Type
string[]
Description
ระบุรูปแบบไฟล์ 3D ที่จะรวมอยู่ในผลลัพธ์ เฉพาะรูปแบบที่ร้องขอเท่านั้นที่จะถูกสร้างและส่งคืน ซึ่งสามารถลดเวลาการทำงานของ task ได้ หากละเว้นพารามิเตอร์นี้ จะรวมรูปแบบที่รองรับทั้งหมด
ค่าที่ใช้ได้: glb, obj, fbx, stl, usdz, 3mf
หากละเว้นพารามิเตอร์นี้ จะมีการสร้างรูปแบบทั้งหมดยกเว้น 3mf โดย 3mf จะรวมอยู่ด้วยก็ต่อเมื่อมีการระบุอย่างชัดเจนเท่านั้น
Name
alpha_thumbnail
Type
boolean
ค่าเริ่มต้น false
Description
เมื่อตั้งค่าเป็น true task จะเรนเดอร์เวอร์ชันพรีวิวแบบพื้นหลังโปร่งใส (RGBA) เพิ่มเติม และส่งคืนเป็น alpha_thumbnail_url ในการตอบกลับ GET ฟิลด์ thumbnail_url ที่มีอยู่เดิมจะไม่เปลี่ยนแปลง
Name
auto_size
Type
boolean
ค่าเริ่มต้น false
Description
เมื่อตั้งค่าเป็น true บริการจะใช้ AI vision เพื่อประมาณความสูงของวัตถุในโลกจริงโดยอัตโนมัติ และปรับขนาดโมเดลให้สอดคล้องกัน จุดกำเนิดจะเป็น bottom โดยค่าเริ่มต้น เว้นแต่จะมีการตั้งค่า origin_at อย่างชัดเจน

ใช้เฉพาะเมื่อ auto_size = true

Name
origin_at
Type
string
ค่าเริ่มต้น bottom
Description
ตำแหน่งของจุดกำเนิดเมื่อเปิดใช้งาน auto_size
ค่าที่ใช้ได้: bottom, center

ผลลัพธ์ที่ส่งคืน

พร็อพเพอร์ตี้ result ของการตอบกลับจะมี id ของ task ข้อความเป็น 3D ที่สร้างขึ้นใหม่

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

Name
400 - Bad Request
Description
คำขอไม่สามารถยอมรับได้ สาเหตุที่พบบ่อย:
- task ID ไม่ถูกต้อง: preview_task_id ไม่ถูกต้องหรือไม่มีอยู่
- task ยังไม่พร้อม: preview task ยังไม่สำเร็จ
- โมเดลไม่ตรงกัน: โมเดล AI ของ preview task ไม่เข้ากันกับโมเดล refine ที่ร้องขอ
- โมเดลไม่รองรับ remove_lighting: มีการตั้งค่า remove_lighting ร่วมกับ ai_model: "meshy-6-lite"
Name
401 - Unauthorized
Description
การยืนยันตัวตนล้มเหลว โปรดตรวจสอบ API คีย์ของคุณ
Name
402 - Payment Required
Description
เครดิตไม่เพียงพอสำหรับการทำงานนี้
Name
404 - Not Found
Description
ไม่พบ preview task ที่ระบุโดย preview_task_id
Name
429 - Too Many Requests
Description
คุณเกินขีดจำกัดการจำกัดอัตราของคุณแล้ว

Request

POST

/openapi/v2/text-to-3d

# Basic refine task
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "enable_pbr": true
}'

# Refine with auto-size and GLB format
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "target_formats": ["glb"],
  "auto_size": true
}'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

GET/openapi/v2/text-to-3d/:id

ดึงข้อมูลงานข้อความเป็น 3D

เอนด์พอยต์นี้ช่วยให้คุณสามารถดึงข้อมูลงานข้อความเป็น 3D โดยใช้ id ของงานที่ถูกต้อง ดูรายละเอียดเพิ่มเติมได้ที่ The Text to 3D Task Object เพื่อดูว่า มีพร็อพเพอร์ตี้ใดบ้างที่รวมอยู่ในอ็อบเจ็กต์งานข้อความเป็น 3D

เอนด์พอยต์นี้ใช้งานได้กับทั้งงาน preview และงาน refine

พารามิเตอร์

Name
id
Type
path
Description
ตัวระบุเฉพาะสำหรับงานข้อความเป็น 3D ที่ต้องการดึงข้อมูล

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

การตอบกลับประกอบด้วยอ็อบเจ็กต์งานข้อความเป็น 3D ดูรายละเอียดเพิ่มเติมได้ที่ส่วน The Text to 3D Task Object

ตัวอย่าง

Mode	Sample Model
Preview
Refine

Request

GET

/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "prompt": "a monster mask",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 20
}

DELETE/openapi/v2/text-to-3d/:id

ลบงานข้อความเป็น 3D

เอนด์พอยต์นี้ใช้ลบงานข้อความเป็น 3D อย่างถาวร รวมถึงโมเดลและข้อมูลทั้งหมดที่เกี่ยวข้อง การดำเนินการนี้ไม่สามารถย้อนกลับได้

พารามิเตอร์ของพาธ

Name
id
Type
path
Description
ID ของงานข้อความเป็น 3D ที่ต้องการลบ

สถานะของงาน

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

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

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

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

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

Request

DELETE

/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -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/v2/text-to-3d

List Text to 3D Tasks

เอนด์พอยต์นี้ช่วยให้คุณสามารถดึงรายการงาน ข้อความเป็น 3D ได้

พารามิเตอร์

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 Text to 3D Task Objects

Request

GET

/openapi/v2/text-to-3d

curl https://api.meshy.ai/openapi/v2/text-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "text-to-3d-preview",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
      "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "prompt": "a monster mask",
    "progress": 100,
    "started_at": 1692771667037,
    "created_at": 1692771650657,
    "finished_at": 1692771669037,
    "status": "SUCCEEDED",
    "texture_urls": [
      {
        "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
      }
    ],
    "preceding_tasks": 0,
    "task_error": {

      "message": ""

    },

    "consumed_credits": 20
  }
]

GET/openapi/v2/text-to-3d/:id/stream

Stream a Text to 3D Task

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

พารามิเตอร์

Name
id
Type
path
Description
ตัวระบุเฉพาะสำหรับงาน Text to 3D ที่ต้องการสตรีม

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

ส่งกลับสตรีมของ อ็อบเจกต์งาน Text to 3D ในรูปแบบ Server-Sent Events

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

Request

GET

/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"model_urls": {
  "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
},
"texture_urls": [
  {
    "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
    "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
    "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
    "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
    "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
  }
],
"preceding_tasks": 0,
"task_error": {

  "message": ""

},

"consumed_credits": 20
}

The Text to 3D Task Object

Text to 3D Task object เป็นหน่วยงานที่ Meshy ใช้ติดตามเพื่อสร้างโมเดล 3D จากอินพุตที่เป็น ข้อความ มีสองขั้นตอนใน Text to 3D API คือ preview และ refine ขั้นตอน preview ใช้สำหรับสร้างโมเดล 3D ที่มีเฉพาะเมชเท่านั้น และขั้นตอน refine ใช้สำหรับสร้างโมเดล 3D ที่มีเท็กซ์เจอร์โดยอิงจากผลลัพธ์ของขั้นตอน preview

ออบเจ็กต์นี้มีคุณสมบัติดังต่อไปนี้:

Properties

Name
id
Type
string
Description
ตัวระบุเฉพาะสำหรับ task แม้ว่าเราจะใช้ k-sortable UUID สำหรับ task id เป็นรายละเอียดการใช้งานจริง แต่คุณ ไม่ควร ตั้งสมมติฐานใดๆ เกี่ยวกับรูปแบบของ id
Name
type
Type
string
Description
ประเภทของ Text to 3D task ค่าที่เป็นไปได้คือ text-to-3d-preview สำหรับ task ในขั้นตอน preview และ text-to-3d-refine สำหรับ task ในขั้นตอน refine
Name
model_urls
Type
object
Description
URL สำหรับดาวน์โหลดไฟล์โมเดล 3D ที่มีเท็กซ์เจอร์ซึ่งสร้างโดย Meshy คุณสมบัติสำหรับรูปแบบใดรูปแบบหนึ่งจะถูกละไว้หากไม่มีการสร้างรูปแบบนั้น แทนที่จะคืนค่าเป็นสตริงว่าง
- Name
  glb
  Type
  string
  Description
  URL สำหรับดาวน์โหลดไฟล์ GLB
- Name
  fbx
  Type
  string
  Description
  URL สำหรับดาวน์โหลดไฟล์ FBX
- Name
  usdz
  Type
  string
  Description
  URL สำหรับดาวน์โหลดไฟล์ USDZ
- Name
  obj
  Type
  string
  Description
  URL สำหรับดาวน์โหลดไฟล์ OBJ
- Name
  mtl
  Type
  string
  Description
  URL สำหรับดาวน์โหลดไฟล์ MTL
- Name
  stl
  Type
  string
  Description
  URL สำหรับดาวน์โหลดไฟล์ STL
- Name
  3mf
  Type
  string
  Description
  URL สำหรับดาวน์โหลดไฟล์ 3MF จะปรากฏเฉพาะเมื่อมีการร้องขอ 3mf ผ่าน target_formats
Name
prompt
Type
string
Description
นี่คือ prompt ที่ไม่ถูกแก้ไขซึ่งใช้ในการสร้าง task
Name
negative_prompt
Type
string
⚠ เลิกใช้แล้ว
Description
คงไว้เพื่อความเข้ากันได้ย้อนหลัง ฟิลด์นี้ไม่มีผลต่อการทำงานของโมเดลที่สร้างขึ้น
Name
art_style
Type
string
⚠ เลิกใช้แล้ว
Description
art_style ที่ไม่ถูกแก้ไขซึ่งใช้ในการสร้าง preview task ไม่รองรับใน Meshy-6
Name
texture_richness
Type
string
⚠ เลิกใช้แล้ว
Description
คงไว้เพื่อความเข้ากันได้ย้อนหลัง ฟิลด์นี้ไม่มีผลต่อการทำงานของโมเดลที่สร้างขึ้น
Name
texture_prompt
Type
string
Description
ข้อความ prompt เพิ่มเติมที่ให้มาเพื่อแนะแนวทางกระบวนการสร้างเท็กซ์เจอร์ในระหว่างขั้นตอน refine
Name
ultra_mode
Type
boolean
⚠ เลิกใช้แล้ว
Description
เลิกใช้แล้ว โปรดอ่าน geometry_resolution แทน
Name
geometry_resolution
Type
string
Description
ระดับ Ultra ที่ preview task ทำงาน (2k หรือ 4k) จะถูกละไว้สำหรับ standard
Name
texture_image_url
Type
string
Description
URL สำหรับดาวน์โหลดภาพเท็กซ์เจอร์ที่ใช้เพื่อแนะแนวทางกระบวนการสร้างเท็กซ์เจอร์
Name
thumbnail_url
Type
string
Description
URL สำหรับดาวน์โหลดภาพย่อของไฟล์โมเดล
Name
alpha_thumbnail_url
Type
string
Description
URL สำหรับดาวน์โหลดเวอร์ชันพื้นหลังโปร่งใส (RGBA) ของ thumbnail_url จะปรากฏเฉพาะเมื่อ task ถูกสร้างด้วย alpha_thumbnail: true และการพรีวิวแบบโปร่งใสถูกเรนเดอร์สำเร็จ มิฉะนั้นฟิลด์นี้จะถูกละไว้
Name
video_url
Type
string
⚠ เลิกใช้แล้ว
Description
URL สำหรับดาวน์โหลดวิดีโอพรีวิว จะถูกลบออกในรุ่นถัดไปในอนาคต
Name
progress
Type
integer
Description
ความคืบหน้าของ task หาก task ยังไม่เริ่มทำงาน คุณสมบัตินี้จะเป็น 0 เมื่อ task สำเร็จแล้ว ค่านี้จะกลายเป็น 100
Name
started_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่ task เริ่มทำงาน มีหน่วยเป็นมิลลิวินาที หาก task ยังไม่เริ่มทำงาน คุณสมบัตินี้จะเป็น 0
ไทม์สแตมป์แสดงถึงจำนวนมิลลิวินาทีที่ผ่านไปนับตั้งแต่วันที่ 1 มกราคม 1970 UTC ตามมาตรฐาน RFC 3339 ตัวอย่างเช่น วันศุกร์ที่ 1 กันยายน 2023 เวลา 12:00:00 น. GMT จะแสดงเป็น 1693569600000 สิ่งนี้ใช้กับ ไทม์สแตมป์ ทั้งหมด ใน Meshy API
Name
created_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่ task ถูกสร้าง มีหน่วยเป็นมิลลิวินาที
Name
finished_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่ task เสร็จสิ้น มีหน่วยเป็นมิลลิวินาที หาก task ยังไม่เสร็จสิ้น คุณสมบัตินี้จะเป็น 0
Name
status
Type
string
Description
สถานะของ task ค่าที่เป็นไปได้คือค่าใดค่าหนึ่งจาก PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED
Name
texture_urls
Type
array
Description
อาร์เรย์ของอ็อบเจกต์ URL เท็กซ์เจอร์ที่สร้างขึ้นจาก task โดยปกติแล้วจะมีอ็อบเจกต์ URL เท็กซ์เจอร์เพียง หนึ่ง รายการเท่านั้น URL เท็กซ์เจอร์แต่ละรายการมีคุณสมบัติดังต่อไปนี้:
- Name
  base_color
  Type
  string
  Description
  URL สำหรับดาวน์โหลดภาพแมปสีพื้นฐาน
- Name
  metallic
  Type
  string
  Description
  URL สำหรับดาวน์โหลดภาพแมปความเป็นโลหะ
  หาก task ถูกสร้างด้วย enable_pbr: false คุณสมบัตินี้จะถูกละไว้
- Name
  normal
  Type
  string
  Description
  URL สำหรับดาวน์โหลดภาพนอร์มัลแมป
  หาก task ถูกสร้างด้วย enable_pbr: false คุณสมบัตินี้จะถูกละไว้
- Name
  roughness
  Type
  string
  Description
  URL สำหรับดาวน์โหลดภาพแมปความขรุขระ
  หาก task ถูกสร้างด้วย enable_pbr: false คุณสมบัตินี้จะถูกละไว้
- Name
  emission
  Type
  string
  Description
  URL สำหรับดาวน์โหลดภาพแมปการเปล่งแสง
  หาก task ถูกสร้างด้วย enable_pbr: false, หาก ai_model เป็น meshy-6-lite, meshy-7.1, หรือ latest, หรือหาก task เป็นการ refine ของ meshy-t2 preview โดยไม่ได้กำหนด ai_model คุณสมบัตินี้จะถูกละไว้
Name
preceding_tasks
Type
integer
Description
จำนวนของ task ที่อยู่ก่อนหน้า
ค่าของฟิลด์นี้มีความหมายก็ต่อเมื่อสถานะของ task เป็น PENDING
Name
task_error
Type
object
Description
รายละเอียดข้อผิดพลาดสำหรับ task ที่ล้มเหลว ดู ข้อผิดพลาด สำหรับข้อมูลอ้างอิงฉบับสมบูรณ์ของอ็อบเจกต์ task_error
Name
consumed_credits
Type
integer
Description
จำนวนเครดิตที่ task นี้ใช้ไป จะปรากฏเมื่อสถานะของ task เป็น PENDING, IN_PROGRESS, หรือ SUCCEEDED จะคืนค่าเป็น 0 สำหรับ task ที่เป็น FAILED (เครดิตจะถูกคืนเมื่อเกิดความล้มเหลว)

Example Text to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  },
  "prompt": "a monster mask",
  "texture_prompt": "green slimy skin with scales and warts",
  "texture_image_url": "",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 20
}