Text to 3D API

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

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

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

สร้างงาน Preview ข้อความเป็น 3D

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

พารามิเตอร์

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
การสร้างแบบมาตรฐาน (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
รอบการสร้าง geometry 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
ควบคุมว่าจะเปิดใช้งานขั้นตอนรีเมชหรือไม่ สำหรับโมเดลคุณภาพสูงสุด เราแนะนำให้ตั้งค่า 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
เปิดใช้งานการลดจำนวนโพลิกอนแบบปรับตัว (adaptive decimation) โดยการตั้งค่าระดับจำนวนโพลิกอน เมื่อตั้งค่านี้แล้ว target_polycount จะถูกละเว้น
ค่าที่ใช้ได้:
- 1: ปรับตัว — จำนวนโพลิกอนระดับสูงสุด
- 2: ปรับตัว — จำนวนโพลิกอนระดับสูง
- 3: ปรับตัว — จำนวนโพลิกอนระดับกลาง
- 4: ปรับตัว — จำนวนโพลิกอนระดับต่ำ

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

Name
symmetry_mode
Type
string
⚠ เลิกใช้แล้ว
ค่าเริ่มต้น auto
Description
เลิกใช้แล้ว พารามิเตอร์นี้ไม่มีผลต่อเอาต์พุตอีกต่อไป
ฟิลด์ symmetry_mode ควบคุมพฤติกรรมของสมมาตรระหว่างกระบวนการสร้างโมเดล
ค่าที่ใช้ได้มีดังนี้:
- off: ปิดใช้งานสมมาตร
- auto: กำหนดและใช้สมมาตรโดยอัตโนมัติตาม geometry ที่ป้อนเข้ามา
- 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 งานจะเรนเดอร์ preview เวอร์ชันพื้นหลังโปร่งใส (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 ของงาน ข้อความเป็น 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

สร้าง Text to 3D Refine Task

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

พารามิเตอร์

Name
mode
Type
string
จำเป็น
Description
ฟิลด์นี้ควรตั้งค่าเป็น "refine" เมื่อสร้าง refine task
Name
preview_task_id
Type
string
จำเป็น
Description
ไอดีของ preview task ที่เกี่ยวข้อง
สถานะของ preview task ที่ระบุต้องเป็น SUCCEEDED
Name
enable_pbr
Type
boolean
ค่าเริ่มต้น false
Description
สร้าง PBR แมป (metallic, roughness, normal) เพิ่มเติมจาก base color เมื่อ ai_model เป็น meshy-6 จะมีการรวม emission map ให้ด้วย ยกเว้นที่ texture_resolution: 8k (จะไม่มีการสร้าง emission map) ส่วน meshy-6-lite, meshy-7.1 และ latest จะไม่สร้าง emission map
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
มีสองวิธีในการระบุภาพ:
- URL ที่เข้าถึงได้แบบสาธารณะ: URL ที่สามารถเข้าถึงได้จากอินเทอร์เน็ตสาธารณะ
- Data URI: ข้อมูล URI ของภาพที่เข้ารหัสแบบ base64 ตัวอย่างของ data URI: data:image/jpeg;base64,<your base64-encoded image data>
การทำเท็กซ์เจอร์ด้วยภาพอาจไม่ทำงานได้อย่างเหมาะสมที่สุด หากมีความแตกต่างของจีออเมทรีอย่างมากระหว่าง asset ต้นฉบับกับภาพที่อัปโหลด สามารถใช้ได้เพียงหนึ่งใน texture_image_url หรือ texture_prompt เพื่อกำหนดทิศทางการทำเท็กซ์เจอร์เท่านั้น หากระบุทั้งสองพารามิเตอร์ ระบบจะใช้ texture_prompt ในการทำเท็กซ์เจอร์ให้กับโมเดลโดยค่าเริ่มต้น
Name
ai_model
Type
string
ค่าเริ่มต้น inherited from the preview task
Description
ไอดีของโมเดลที่ใช้สำหรับการ refine
ค่าที่ใช้ได้:
- meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
- meshy-7 (เลิกใช้): ใช้ meshy-7.1 แทน
ไม่ระบุพารามิเตอร์นี้เพื่อรับค่าโมเดลที่ preview task ใช้มาโดยอัตโนมัติ ซึ่งจะทำให้ preview และการ refine ของมันใช้โมเดลเดียวกันตลอดทั้งกระบวนการ ระบุค่าอย่างชัดเจนเพื่อลบล้างการรับค่าอัตโนมัติดังกล่าว
การระบุ latest อย่างชัดเจนจะถูกตีความในลักษณะเดียวกันกับใน preview task (ปัจจุบันคือ Meshy 7.1) ดังนั้น preview ที่ใช้ latest และการ refine ของมันที่ใช้ latest จะลงที่โมเดลเท็กซ์เจอร์เดียวกันเสมอ
Name
moderation
Type
boolean
ค่าเริ่มต้น false
Description
เมื่อตั้งค่าเป็น true เนื้อหาที่ป้อนเข้ามาจะถูกตรวจกรองเนื้อหาที่อาจเป็นอันตรายโดยอัตโนมัติ หากตรวจพบเนื้อหาที่เป็นอันตราย งานจะไม่ดำเนินไปยังขั้นตอนการสร้าง
ทั้งข้อความจาก texture_prompt และภาพจาก texture_image_url จะถูกตรวจกรอง
Name
remove_lighting
Type
boolean
ค่าเริ่มต้น true
Description
ลบไฮไลต์และเงาออกจากเท็กซ์เจอร์ base color ทำให้ได้ผลลัพธ์ที่สะอาดขึ้นและทำงานได้ดีกว่าภายใต้การจัดแสงแบบกำหนดเอง
จะมีผลเฉพาะเมื่อ ai_model เป็น meshy-6 เท่านั้น ส่วนโมเดลอื่นจะไม่นำไปใช้
Name
target_formats
Type
string[]
Description
ระบุรูปแบบไฟล์ 3D ที่จะรวมไว้ในผลลัพธ์ จะสร้างและส่งกลับเฉพาะรูปแบบที่ระบุเท่านั้น ซึ่งสามารถลดเวลาในการทำงานให้เสร็จได้ หากไม่ระบุ จะรวมรูปแบบที่รองรับทั้งหมด
ค่าที่ใช้ได้: glb, obj, fbx, stl, usdz, 3mf
หากไม่ระบุ จะสร้างทุกรูปแบบยกเว้น 3mf โดย 3mf จะถูกรวมไว้เมื่อมีการระบุอย่างชัดเจนเท่านั้น
Name
alpha_thumbnail
Type
boolean
ค่าเริ่มต้น false
Description
เมื่อตั้งค่าเป็น true งานจะแสดงผลเวอร์ชันพื้นหลังโปร่งใส (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 ของ Text to 3D task ที่สร้างขึ้นใหม่

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

Name
400 - Bad Request
Description
คำขอไม่สามารถรับได้ สาเหตุที่พบบ่อย:
- ไอดีงานไม่ถูกต้อง: preview_task_id ไม่ถูกต้องหรือไม่มีอยู่
- งานยังไม่พร้อม: preview task ยังไม่สำเร็จ
- โมเดลไม่ตรงกัน: โมเดล AI ของ preview task ไม่รองรับกับโมเดล refine ที่ขอ
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 อย่างถาวร รวมถึงโมเดลและข้อมูลทั้งหมดที่เกี่ยวข้อง การกระทำนี้ไม่สามารถย้อนกลับได้

พารามิเตอร์เส้นทาง (Path Parameters)

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

สตรีมงาน Text to 3D

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

พารามิเตอร์

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

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

ส่งคืนสตรีมของ The Text to 3D Task Objects ในรูปแบบ 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
ประเภทของ task Text to 3D ค่าที่เป็นไปได้คือ 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 ที่ไม่มีการแก้ไข ซึ่งถูกใช้ในการสร้าง task preview ไม่รองรับโดย 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 ที่ task preview ทำงาน (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 คุณสมบัตินี้จะถูกละไว้
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
}