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

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

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

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

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

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

พารามิเตอร์

Name
mode
Type
string
จำเป็น
Description
ค่านี้ควรตั้งไว้ที่ "preview" เมื่อสร้างงานพรีวิว
Name
prompt
Type
string
จำเป็น
Description
อธิบายว่าควรจะเป็นวัตถุอะไรในโมเดล 3D ขีดสูงสุด 600 ตัวอักษร
Name
model_type
Type
string
ค่าเริ่มต้น standard
Description
ระบุประเภทของการสร้างโมเดล 3D เมช
ค่าใช้ได้:
- standard: การสร้างโมเดล 3D เมชแบบละเอียด
- smart-topology: เลือกรุ่น Smart Topology กับ ai_model (meshy-t2)
- lowpoly (เลิกใช้): สร้างเมชแบบโลว์โพลีที่เพิ่มประสิทธิภาพให้โพลิกอนสะอาดขึ้น เราแนะนำให้ใช้ smart-topology
เมื่อเลือก smart-topology ค่าของ should_remesh และ decimation_mode จะถูกละเลย และแค่ topology: triangle ที่ยอมรับ
เมื่อเลือก lowpoly ค่าของ ai_model, topology, target_polycount และ should_remesh จะถูกละเลย
Name
ai_model
Type
string
ค่าเริ่มต้น latest
Description
ไอดีของโมเดลที่ใช้ ค่าใช้ได้ขึ้นกับ model_type
การสร้างแบบมาตรฐาน (model_type: standard):
- meshy-5, meshy-6, meshy-7, latest (Meshy 7)
การสร้าง Smart Topology (model_type: smart-topology):
- meshy-t2 (default): โมเดล Smart Topology — topology ที่สะอาดขึ้น, แยกส่วนออกมาได้เอง, ส่งออกแบบ triangle และคุณสามารถตั้งค่าจำนวนหน้าได้ด้วย target_polycount.
Name
ultra_mode
Type
boolean
ค่าเริ่มต้น false
Description
เปิดใช้งานการสร้าง Ultra สำหรับจีออเมทรีที่มีรายละเอียดสูงขึ้นพร้อมรายละเอียดพื้นผิวที่ละเอียดขึ้น การสร้างใช้เวลานานขึ้นและเพิ่ม 5 เครดิต
สนับสนุนแค่เมื่อ ai_model เป็น meshy-7 (หรือ latest) และเฉพาะใน mode preview
Name
should_remesh
Type
boolean
ค่าเริ่มต้น false (meshy-6, meshy-7), true (others)
Description
ควบคุมว่าจะเปิดใช้งานเฟส remesh หรือไม่ สำหรับโมเดลคุณภาพสูงสุดเราแนะนำให้ตั้ง should_remesh เป็น false

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

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

Name
target_polycount
Type
integer
Description
เป้าหมายจำนวนโพลิกอน (ด้านหน้า) ในผลลัพธ์ จำนวนจริงอาจเบี่ยงเบนจากเป้าหมายขึ้นอยู่กับจีออเมทรี
target_polycount มีผลในสองกรณีอิสระ:
- Remesh — กับ should_remesh: true บนโมเดล standard เมชจะถูก remesh (ลดลง) ให้อยู่ในจำนวนนี้ ประมาณจาก 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
ระบุโหมดท่าทางของโมเดลที่สร้าง
ค่าใช้ได้:
- 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) ของพรีวิวเพิ่มขึ้นและส่งคืนเป็น 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 ของการตอบกลับประกอบด้วย Task ID ของงานข้อความเป็น 3D ที่สร้างขึ้นใหม่

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

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

Request

POST

/openapi/v2/text-to-3d

# พรีวิวง่าย ๆ ที่มีแค่พารามิเตอร์ที่จำเป็น
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"
}'

# พรีวิวที่มี remesh และ 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",
  "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

สร้างงานการปรับแต่ง ข้อความเป็น 3D

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

พารามิเตอร์

Name
mode
Type
string
จำเป็น
Description
ค่านี้ควรตั้งไว้ที่ "refine" เมื่อสร้างงานปรับแต่ง
Name
preview_task_id
Type
string
จำเป็น
Description
ไอดีงานพรีวิวที่สอดคล้องกัน
สถานะของงานพรีวิวที่ให้ต้องเป็น SUCCEEDED
Name
enable_pbr
Type
boolean
ค่าเริ่มต้น false
Description
สร้าง PBR Maps (เงาโลหะ, ความหยาบ, นอร์มัล) นอกเหนือจากสีพื้นฐานแล้ว แผนที่การส่งแสงออกยังถูกรวมเมื่อ ai_model คือ meshy-6, ยกเว้นที่ texture_resolution: 8k (ไม่มีแผนที่การส่งแสงออกถูกสร้าง) meshy-7 (และ latest) ไม่ได้สร้างแผนที่การส่งแสงออก
Name
texture_resolution
Type
string
ค่าเริ่มต้น 2k
Description
ความละเอียดของเท็กซ์เจอร์สีพื้นฐาน หนึ่งใน 2k (2048×2048), 4k (4096×4096), หรือ 8k (8192×8192) ความละเอียดที่สูงกว่าจะจับรายละเอียดพื้นผิวมากขึ้น ใช้ได้เฉพาะใน mode refine
4k และ 8k ต้องใช้ ai_model ของ meshy-6, meshy-7, หรือ latest เมื่อ 8k ไม่มีแผนที่การส่งแสงออกถูกสร้าง
Name
hd_texture
Type
boolean
⚠ เลิกใช้แล้ว
ค่าเริ่มต้น false
Description
ใช้ texture_resolution แทน — เทียบเท่ากับ texture_resolution: "4k" เมื่อทั้งสองถูกตั้งค่า texture_resolution จะมีความสำคัญมากกว่า
Name
texture_prompt
Type
string
Description
ให้ prompt ข้อความเพิ่มที่จะใช้ในการนำกระบวนการใส่เท็กซ์เจอร์ ขีดสูงสุด 600 ตัวอักษร
Name
texture_image_url
Type
string
Description
ให้ภาพ 2 มิติที่จะใช้ในการนำกระบวนการใส่เท็กซ์เจอร์ ปัจจุบันสนับสนุนรูปแบบ .jpg, .jpeg, และ .png
มีสองวิธีในการให้ภาพ:
- URL ที่เข้าถึงได้โดยสาธารณชน: URL ที่สามารถเข้าถึงได้จากอินเทอร์เน็ตทั่วไป
- Data URI: Data URI ที่เข้ารหัส base64 ของภาพ ตัวอย่างของ Data URI: data:image/jpeg;base64,<ข้อมูลภาพเข้ารหัส base64 ของคุณ>
การใส่เท็กซ์เจอร์ด้วยภาพอาจไม่ทำงานอย่างสมบูรณ์แบบหากมีความแตกต่างของจีออเมทรีที่สำคัญระหว่าง asset เดิมและภาพที่อัปโหลด มีเพียง texture_image_url หรือ texture_prompt เท่านั้นที่สามารถใช้ในการนำกระบวนการใส่เท็กซ์เจอร์ได้ หากระบุทั้งสองพารามิเตอร์ texture_prompt จะถูกใช้ใส่เท็กซ์เจอร์ในโมเดลโดยอุปนิสัย
Name
ai_model
Type
string
ค่าเริ่มต้น latest
Description
ไอดีของโมเดลที่ใช้สำหรับการปรับแต่ง ค่าใช้ได้: meshy-5, meshy-6, meshy-7, latest (Meshy 7)
latest เป็นการกำหนดที่นี่เช่นเดียวกับที่มันเป็นบนงานพรีวิว (ปัจจุบันคือ Meshy 7) ดังนั้นพรีวิว latest และการปรับแต่ง latest จะหล่นอยู่ที่โมเดลเนื้อเดียวกันเสมอ
Name
moderation
Type
boolean
ค่าเริ่มต้น false
Description
เมื่อถูกตั้งเป็น true เนื้อหาที่ป้อนจะถูกตรวจสอบอย่างอัตโนมัติสำหรับเนื้อหาที่อาจเป็นอันตราย หากตรวจพบเนื้อหาที่เป็นอันตราย งานจะไม่ดำเนินไปสู่การสร้าง
ทั้งข้อความจาก texture_prompt และภาพจาก texture_image_url จะถูกตรวจสอบ
Name
remove_lighting
Type
boolean
ค่าเริ่มต้น true
Description
ลบรอยแสงเงาออกจากเท็กซ์เจอร์สีพื้นฐาน ผลลัพธ์ที่ได้จะสะอาดกว่าที่ใช้งานกับการตั้งค่าการให้แสงเฉพาะได้ดียิ่งขึ้น
ใช้ผลเมื่อ ai_model เป็น meshy-6 เท่านั้น บน meshy-7 (และ latest) พารามิเตอร์นี้ได้รับการยอมรับแต่ถูกละเลย
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.

การส่งคืน

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

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

Request

POST

/openapi/v2/text-to-3d

# งานปรับแต่งพื้นฐาน
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
}'

# ปรับแต่งด้วยขนาดอัตโนมัติและรูปแบบ GLB
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 ให้ไอดีงานที่ถูกต้อง ดูที่ วัตถุงาน ข้อความเป็น 3D เพื่อดูว่าคุณสมบัติใดที่รวมอยู่ในวัตถุงาน ข้อความเป็น 3D

เอนด์พอยต์นี้ทำงานสำหรับทั้งงานพรีวิวและปรับแต่ง

พารามิเตอร์

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

การส่งคืน

การตอบกลับประกอบด้วยวัตถุงาน ข้อความเป็น 3D ตรวจสอบ วัตถุงาน ข้อความเป็น 3D สำหรับรายละเอียด

ตัวอย่าง

โหมด	โมเดลตัวอย่าง
พรีวิว
ปรับแต่ง

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
ไอดีของงาน ข้อความเป็น 3D ที่จะลบ

การส่งคืน

ส่งคืน 200 OK ในกรณีที่สำเร็จ

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

// Returns 200 Ok on success.

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

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

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

พารามิเตอร์

Name
page_num
Type
integer
ค่าเริ่มต้น 1
Description
หมายเลขหน้าสำหรับการแบ่งหน้า
Name
page_size
Type
integer
ค่าเริ่มต้น 10
Description
ขีดจำกัดขนาดหน้า ขีดสูงสุดที่อนุญาตคือ 50 รายการ
Name
sort_by
Type
string
Description
ช่องที่จะใช้ในการจัดเรียง
ค่าใช้ได้:
- +created_at: เรียงตามเวลาสร้างในลำดับเพิ่มขึ้น
- -created_at: เรียงตามเวลาสร้างในลำดับลดลง

การส่งคืน

จะส่งคืนรายการที่ถูกแบ่งหน้าใน วัตถุงาน ข้อความเป็น 3D

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

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

เอนด์พอยต์นี้สตรีมการอัปเดตเรียลไทม์สำหรับงาน ข้อความเป็น 3D ด้วยการถ่ายทอดเหตุการณ์จากเซิร์ฟเวอร์ (SSE)

พารามิเตอร์

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

การส่งคืน

ส่งคืนสตรีมของ วัตถุงาน ข้อความเป็น 3D เป็นการถ่ายทอดเหตุการณ์จากเซิร์ฟเวอร์

สำหรับงานที่มีสถานะ 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

// ตัวอย่างเหตุการณ์ข้อผิดพลาด
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// ตัวอย่างเหตุการณ์ข้อความแสดงถึงความก้าวหน้าของงาน
// สำหรับงานที่มีสถานะ PENDING หรือ IN_PROGRESS สตรีมการตอบกลับจะไม่รวมทุกฟิลด์
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
}

วัตถุงาน ข้อความเป็น 3D

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

วัตถุมีคุณสมบัติต่อไปนี้:

คุณสมบัติ

Name
id
Type
string
Description
ตัวระบุที่ไม่ซ้ำกันสำหรับงาน. ถึงแม้ว่าเราจะใช้ UUID ที่สามารถเรียงตาม K ได้สำหรับ task ids ตามรายละเอียดการทำงานภายใน, คุณควร ไม่ คาดเดารูปแบบของไอดี
Name
type
Type
string
Description
ประเภทของงาน ข้อความเป็น 3D ค่าใช้ได้คือ text-to-3d-preview สำหรับงานขั้นตอนพรีวิวและ text-to-3d-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 ที่ไม่ได้แก้ไขที่ถูกใช้สร้างงาน
Name
negative_prompt
Type
string
⚠ เลิกใช้แล้ว
Description
รักษาไว้เพื่อความเข้ากันย้อนหลัง ฟิลด์นี้ไม่มีผลกระทบต่อโมเดลที่สร้างขึ้น
Name
art_style
Type
string
⚠ เลิกใช้แล้ว
Description
art_style ที่ไม่ได้แก้ไขที่ถูกใช้สร้างงานพรีวิว ไม่สนับสนุนโดย Meshy-6
Name
texture_richness
Type
string
⚠ เลิกใช้แล้ว
Description
รักษาไว้เพื่อความเข้ากันย้อนหลัง ฟิลด์นี้ไม่มีผลกระทบต่อโมเดลที่สร้างขึ้น
Name
texture_prompt
Type
string
Description
prompt ข้อความเพิ่มเติมที่ให้เพื่อใช้นำกระบวนการใส่เท็กซ์เจอร์ในระหว่างขั้นตอนปรับแต่ง
Name
ultra_mode
Type
boolean
Description
สะท้อนค่าของ ultra_mode ที่งานพรีวิวถูกสร้างขึ้น จะมีเฉพาะสำหรับงานพรีวิว meshy-7 (หรือ latest) ที่ตั้งค่า ultra_mode อย่างชัดเจน ถูกละออกในกรณีอื่น
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 จะมีเฉพาะเมื่อสร้างงานด้วย alpha_thumbnail: true และพรีวิวโปร่งใสถูกเร็นเดอร์สำเร็จ มิฉะนั้นฟิลด์นี้จะถูกละออก
Name
video_url
Type
string
⚠ เลิกใช้แล้ว
Description
URL สำหรับดาวน์โหลดวิดีโอพรีวิว จะถูกลบในรุ่นต่อไป
Name
progress
Type
integer
Description
ความคืบหน้าของงาน ถ้างานยังไม่เริ่มต้น คุณสมบัตินี้จะเป็น 0 เมื่องานสำเร็จแล้ว จะเปลี่ยนเป็น 100
Name
started_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่งานถูกเริ่มต้นใน milliseconds ถ้างานยังไม่เริ่มต้น คุณสมบัตินี้จะเป็น 0
ไทม์สแตมป์เป็นจำนวน milliseconds ที่ผ่านไปตั้งแต่วันที่ 1 มกราคม 1970 UTC ตามมาตรฐาน RFC 3339 ตัวอย่างเช่น วันศุกร์ที่ 1 กันยายน 2023 12:00:00 PM GMT เป็น 1693569600000 ซึ่งใช้ได้กับ ทุก ไทม์สแตมป์ใน Meshy API
Name
created_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่งานถูกสร้างใน milliseconds
Name
finished_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่งานเสร็จสิ้นใน milliseconds ถ้างานยังไม่เสร็จสิ้น คุณสมบัตินี้จะเป็น 0
Name
status
Type
string
Description
สถานะของงาน ค่าใช้ได้คือหนึ่งใน PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED
Name
texture_urls
Type
array
Description
อาเรย์ของวัตถุ URL ของเท็กซ์เจอร์ที่ถูกสร้างจากงาน โดยปกติแล้วจะมีเพียง หนึ่ง วัตถุ URL ของเท็กซ์เจอร์ แต่ละ URL ของเท็กซ์เจอร์มีคุณสมบัติดังต่อไปนี้:
- Name
  base_color
  Type
  string
  Description
  URL สำหรับดาวน์โหลดรูปภาพแผนที่สีพื้นฐาน
- Name
  metallic
  Type
  string
  Description
  URL สำหรับดาวน์โหลดรูปภาพแผนที่เงาโลหะ
  ถ้างานถูกสร้างด้วย enable_pbr: false คุณสมบัตินี้จะถูกละออก
- Name
  normal
  Type
  string
  Description
  URL สำหรับดาวน์โหลดรูปภาพแผนที่นอร์มัล
  ถ้างานถูกสร้างด้วย enable_pbr: false คุณสมบัตินี้จะถูกละออก
- Name
  roughness
  Type
  string
  Description
  URL สำหรับดาวน์โหลดรูปภาพแผนที่ความหยาบ
  ถ้างานถูกสร้างด้วย enable_pbr: false คุณสมบัตินี้จะถูกละออก
- Name
  emission
  Type
  string
  Description
  URL สำหรับดาวน์โหลดรูปภาพแผนที่การส่งแสงออก
  ถ้างานถูกสร้างด้วย enable_pbr: false, หรือ ai_model คือ meshy-5 คุณสมบัตินี้จะถูกละออก
Name
preceding_tasks
Type
integer
Description
จำนวนงานที่มาก่อนหน้า
ค่าในฟิลด์นี้มีความหมายเฉพาะถ้าสถานะของงานคือ PENDING
Name
task_error
Type
object
Description
รายละเอียดข้อผิดพลาดสำหรับงานที่ล้มเหลว ดู ข้อผิดพลาด สำหรับการอ้างอิงวัตถุ task_error ทั้งหมด
Name
consumed_credits
Type
integer
Description
จำนวนเครดิตที่ถูกรวมรับใช้โดยงานนี้ ปรากฏเมื่อสถานะงานคือ PENDING, IN_PROGRESS, หรือ SUCCEEDED ส่งคืน 0 เมื่อ 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
}