Creative Lab Vinyl Figure API

แปลงรูปถ่ายให้เป็นฟิกเกอร์ไวนิลหัวโตแบบ 3 มิติผ่านสองขั้นตอน งานสร้างต้นแบบจะสร้างภาพแนวคิดจากรูปถ่าย ส่วนงานสร้างโมเดลจะแปลงภาพนั้นให้เป็นโมเดล 3 มิติที่มี texture โดยใช้ ID ของงานสร้างต้นแบบเป็น input_task_id

POST /openapi/creative-lab/vinyl-figure/v1/prototype
POST /openapi/creative-lab/vinyl-figure/v1/build

POST/openapi/creative-lab/vinyl-figure/v1/prototype

สร้างงาน Vinyl Figure prototype

สร้างภาพคอนเซ็ปต์สไตล์ vinyl figure หนึ่งภาพจากรูปถ่าย เพื่อสร้างโมเดล 3D ให้ส่ง ID ของงานนี้ไปยัง build endpoint ในชื่อ input_task_id สำหรับฟิลด์ต่าง ๆ ของงาน ดูที่ The Vinyl Figure prototype task object

Request

POST

/openapi/creative-lab/vinyl-figure/v1/prototype

# Stage 1: generate a vinyl-figure-style concept image
curl https://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/prototype \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>"
  }'

Response

{
  "result": "019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de"
}

Prototype example

Start with a source photo, then generate the prototype image used by the build stage.

Source photo used as the Creative Lab Vinyl Figure input — Prototype input

Big-head vinyl figure prototype image generated from the source photo — Prototype output

พารามิเตอร์

Name
image_url
Type
string
จำเป็น
Description
รูปถ่ายที่จะเปลี่ยนเป็นฟิกเกอร์หัวโตแบบ vinyl figure ในรูปแบบ URL สาธารณะหรือ data URI (data:image/jpeg;base64,<your base64-encoded image data>)
รูปภาพต้องเป็นไฟล์ JPG, JPEG, PNG หรือ WebP ขนาดไม่เกิน 20 MB
Name
name
Type
string
Description
ชื่อสำหรับงาน ความยาวไม่เกิน 100 ตัวอักษร ชื่อนี้จะถูกส่งกลับมาในฟิลด์ name ของงาน หากชื่อยาวเกินไปจะได้รับ 400
Name
remove_background
Type
boolean
ค่าเริ่มต้น false
Description
กำหนดว่าจะลบพื้นหลังออกจากภาพ prototype หรือไม่ true จะส่งคืนไฟล์ PNG แบบ RGBA ที่มีความโปร่งใส เพื่อให้คุณสามารถวางซับเจกต์ลงบนพื้นหลังใดก็ได้ การสร้างโมเดล (build) ก็จะเริ่มต้นจากภาพที่ไม่มีพื้นหลังเช่นกัน หาก Meshy ไม่สามารถลบพื้นหลังได้ ระบบจะส่งคืนภาพพร้อมพื้นหลังเดิม และงานยังคงสำเร็จ

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

ฟิลด์ result เก็บ ID ของงาน prototype ใหม่ ดึงข้อมูลงาน หรือ สตรีมข้อมูลงาน จนกว่า status จะเป็น SUCCEEDED จากนั้นส่ง ID ไปยัง build endpoint ในชื่อ input_task_id

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

Name
400 - Bad Request
Description
คำขอนี้ไม่สามารถทำงานได้ ตัวอย่างเช่น:
- ไม่มี image_url
- รูปภาพไม่ใช่ไฟล์ JPG, JPEG, PNG หรือ WebP
- รูปภาพเล็กเกินไป มีขนาดเกิน 20 MB หรือเกินจำนวนพิกเซลสูงสุดที่กำหนด
- Meshy ไม่สามารถดาวน์โหลดรูปภาพได้ เช่น เพราะ URL ส่งคืน 404 หรือหมดเวลา
- data URI ไม่ใช่ base64 ที่ถูกต้อง
- รูปภาพถูกตั้งค่าสถานะว่าเป็น NSFW
ข้อความแสดงข้อผิดพลาดจะระบุปัญหาที่พบ แก้ไขคำขอแล้วส่งอีกครั้ง
Name
401 - Unauthorized
Description
ไม่มี API คีย์หรือ API คีย์ไม่ถูกต้อง ตรวจสอบเฮดเดอร์ Authorization
Name
402 - Payment Required
Description
อาจเกิดจากสาเหตุใดสาเหตุหนึ่งต่อไปนี้:
- บัญชีมีเครดิตไม่เพียงพอ
- API คีย์ พื้นที่ทำงาน หรือสมาชิกถึงขีดจำกัดเครดิตแล้ว
- บัญชีอยู่ในแผนฟรี
ตรวจสอบเครดิตและแผนของคุณ แล้วลองใหม่อีกครั้ง
Name
403 - Forbidden
Description
ทีมของคุณเปิดใช้งาน IP Filtering และ Meshy ตรวจพบว่ารูปภาพนี้เข้าข่ายทรัพย์สินทางปัญญาของบุคคลที่สาม โปรดส่งรูปภาพที่คุณมีสิทธิ์ใช้งาน
Name
429 - Too Many Requests
Description
มีข้อจำกัดข้อใดข้อหนึ่งต่อไปนี้ที่ถึงขีดจำกัด:
- คุณส่งคำขอมากกว่าที่การจำกัดอัตราของคุณอนุญาต รอสักครู่แล้วลองใหม่อีกครั้ง ดู Rate limits
- มีงานของคุณที่อยู่ในคิวหรือกำลังทำงานมากเกินไป รอให้บางงานเสร็จสิ้นก่อนแล้วลองใหม่อีกครั้ง
- หากอยู่ในแผนแบบไม่จำกัดแต่ไม่มีเครดิตเหลือ คุณถึงจำนวนงานสูงสุดที่สามารถรันได้โดยไม่ใช้เครดิตแล้ว รอให้งานเสร็จสิ้น หรือเติมเครดิต
Name
500 - Internal Server Error
Description
Meshy พบข้อผิดพลาดของเซิร์ฟเวอร์ เช่น ไม่สามารถตรวจสอบทรัพย์สินทางปัญญาของรูปภาพได้ Meshy จะไม่สร้างงานนี้ และจะคืนเครดิตที่เรียกเก็บไปแล้ว ลองส่งคำขออีกครั้ง

POST/openapi/creative-lab/vinyl-figure/v1/build

สร้างงานสร้าง Vinyl Figure

สร้างฟิกเกอร์ไวนิล 3 มิติที่มีแมททีเรียลแล้วจากงานต้นแบบ (prototype) ที่สำเร็จ สำหรับฟิลด์ต่าง ๆ ดูที่ The Vinyl Figure build task object

Request

POST

/openapi/creative-lab/vinyl-figure/v1/build

# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de"
  }'

Response

{
  "result": "019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef"
}

พารามิเตอร์

Name
input_task_id
Type
string
จำเป็น
Description
ID ของงานต้นแบบที่จะนำมาสร้าง จะต้องเป็นงานที่บัญชีของคุณสร้างด้วย POST /openapi/creative-lab/vinyl-figure/v1/prototype และมีสถานะ SUCCEEDED
ID ที่ไม่ใช่งานต้นแบบ Vinyl Figure ของคุณจาก API จะคืนค่า 404 รวมถึงต้นแบบที่สร้างในเว็บแอปด้วย
Name
name
Type
string
Description
ชื่อสำหรับงาน ความยาวไม่เกิน 100 ตัวอักษร ชื่อนี้จะถูกส่งกลับมาในฟิลด์ name ของงาน หากชื่อยาวเกินไปจะคืนค่า 400

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

ฟิลด์ result เก็บ ID ของงานสร้างใหม่ ดึงข้อมูลงาน หรือ สตรีมข้อมูลงาน จนกว่า status จะเป็น SUCCEEDED จากนั้นดาวน์โหลดไฟล์ GLB ที่มีแมททีเรียลจาก model_urls.glb หากต้องการเป็น OBJ แทน ให้ดาวน์โหลด model_urls.obj พร้อมไฟล์แมททีเรียลจาก model_urls.mtl

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

Name
400 - Bad Request
Description
คำขอนี้ไม่สามารถทำงานได้ ตัวอย่างเช่น:
- input_task_id หายไปหรือไม่ใช่ ID งานที่ถูกต้อง
- สถานะของงานต้นแบบไม่ใช่ SUCCEEDED หากยังทำงานอยู่ ให้รอแล้วลองใหม่ หากล้มเหลวหรือถูกยกเลิก ให้สร้างงานต้นแบบใหม่
- งานต้นแบบสำเร็จแล้วแต่ไม่มีภาพ ให้สร้างงานต้นแบบใหม่
ข้อความแสดงข้อผิดพลาดจะระบุว่าพบปัญหาใด
Name
401 - Unauthorized
Description
API คีย์หายไปหรือไม่ถูกต้อง ตรวจสอบส่วนหัว Authorization
Name
402 - Payment Required
Description
มีกรณีใดกรณีหนึ่งต่อไปนี้เกิดขึ้น:
- บัญชีมีเครดิตไม่เพียงพอ
- API คีย์ พื้นที่ทำงาน หรือสมาชิกถึงขีดจำกัดเครดิตแล้ว
- บัญชีอยู่ในแผนฟรี
ตรวจสอบเครดิตและแผนของคุณ แล้วลองใหม่
Name
404 - Not Found
Description
input_task_id ไม่ตรงกับงานต้นแบบ Vinyl Figure ใด ๆ ที่บัญชีของคุณสร้างด้วย API ต้นแบบที่สร้างในเว็บแอปก็จะคืนค่า 404 เช่นกัน ให้ส่ง ID result จากการตอบกลับของการสร้างต้นแบบ
Name
429 - Too Many Requests
Description
มีขีดจำกัดอย่างใดอย่างหนึ่งต่อไปนี้ที่ถูกแตะถึง:
- คุณส่งคำขอมากกว่าที่การจำกัดอัตราของคุณอนุญาต ให้รอสักครู่แล้วลองใหม่ ดูที่ Rate limits
- มีงานของคุณที่อยู่ในคิวหรือกำลังทำงานมากเกินไป ให้รอจนกว่าบางงานจะเสร็จสิ้น แล้วลองใหม่
- บนแผนไม่จำกัดที่ไม่มีเครดิตเหลือ คุณถึงจำนวนงานสูงสุดที่สามารถทำงานได้โดยไม่ใช้เครดิตแล้ว ให้รอให้งานเสร็จสิ้น หรือเพิ่มเครดิต

GET/openapi/creative-lab/vinyl-figure/v1/(prototype|build)/:id

รับงาน Vinyl Figure

คืนค่างาน prototype หรือ build หนึ่งงาน path ที่ใช้ต้องตรงกับขั้นตอน (stage) ของงานนั้น หากส่งคำขอถึงงาน build ผ่าน /prototype/:id จะได้รับ 404 และในทางกลับกัน หากส่งคำขอถึงงาน prototype ผ่าน /build/:id ก็จะได้รับ 404 เช่นกัน

สำหรับฟิลด์ต่าง ๆ โปรดดูที่ The Vinyl Figure prototype task object และ The Vinyl Figure build task object

Request

GET

/openapi/creative-lab/vinyl-figure/v1/prototype/019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de

# Prototype
curl https://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/prototype/019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/build/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de",
  "type": "creative-lab-vinyl-figure-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1752969600000,
  "started_at": 1752969604000,
  "finished_at": 1752969630000,
  "expires_at": 1753228830000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Build Response

{
  "id": "019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef",
  "type": "creative-lab-vinyl-figure-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1752969700000,
  "started_at": 1752969710000,
  "finished_at": 1752969735000,
  "expires_at": 1753228935000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "prompt": "",
  "negative_prompt": "",
  "texture_prompt": "",
  "texture_image_url": "",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.mtl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/preview.png?Expires=***",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/texture_0.png?Expires=***"
    }
  ]
}

พารามิเตอร์

Name
id
Type
path
Description
รหัสงาน (task ID) จากการตอบกลับของการสร้าง

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

prototype task object หรือ build task object ขึ้นอยู่กับขั้นตอน (stage) ที่ตรงกับ path

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

Name
400 - Bad Request
Description
id ไม่ใช่รหัสงานที่ถูกต้อง โปรดส่งรหัส result จากการตอบกลับของการสร้าง
Name
403 - Forbidden
Description
ทีมของคุณเปิดใช้งาน IP Filtering และ Meshy ตรวจพบว่ารูปภาพของงานนี้ละเมิดทรัพย์สินทางปัญญาของบุคคลที่สาม ทีมที่ใช้แพ็กเกจ Enterprise จะไม่พบข้อผิดพลาดนี้ โปรดสร้างงาน prototype จากรูปภาพที่คุณมีสิทธิ์ใช้งาน
Name
404 - Not Found
Description
ไม่พบงาน Vinyl Figure ที่มีรหัสนี้อยู่ในบัญชีของคุณ หรือขั้นตอน (stage) ของงานไม่ตรงกับ path โปรดตรวจสอบรหัสงาน และใช้ /prototype หรือ /build ให้ตรงกับงานนั้น
Name
500 - Internal Server Error
Description
Meshy ไม่สามารถตรวจสอบทรัพย์สินทางปัญญาได้ โปรดลองส่งคำขออีกครั้ง

DELETE/openapi/creative-lab/vinyl-figure/v1/(prototype|build)/:id

ลบงาน Vinyl Figure

ยกเลิกงาน Vinyl Figure การยกเลิกงานที่มีสถานะ PENDING จะคืนเครดิตที่ใช้ไป ส่วนงานที่มีสถานะ IN_PROGRESS จะถูกยกเลิกโดยไม่มีการคืนเครดิต เนื่องจาก worker ได้เริ่มดำเนินการไปแล้ว งานที่มีสถานะสุดท้าย (SUCCEEDED, FAILED, หรือ CANCELED) ไม่สามารถยกเลิกได้

พาธต้องตรงกับขั้นตอน (stage) ของงานนั้น ๆ ตัวอย่างเช่น การเรียก DELETE ที่ /prototype/:id โดยใช้ ID ของงาน build จะได้รับผลลัพธ์ 404

Request

DELETE

/openapi/creative-lab/vinyl-figure/v1/prototype/019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/prototype/019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 204 No Content on success (empty body).

พารามิเตอร์พาธ (Path parameters)

Name
id
Type
path
Description
ID ของงานที่ต้องการยกเลิก

ผลลัพธ์ที่ได้

204 No Content พร้อม body ที่ว่างเปล่า

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

Name
400 - Bad Request
Description
หนึ่งในกรณีต่อไปนี้:
- id ไม่ใช่ ID งานที่ถูกต้อง โปรดส่ง ID จากฟิลด์ result ของการตอบกลับตอนสร้างงาน
- งานนี้มีสถานะสุดท้ายแล้ว (SUCCEEDED, FAILED, หรือ CANCELED) จึงไม่สามารถยกเลิกได้
Name
404 - Not Found
Description
ไม่พบงาน Vinyl Figure ที่มี ID นี้อยู่ในบัญชีของคุณ หรือขั้นตอน (stage) ของงานไม่ตรงกับพาธที่ระบุ โปรดตรวจสอบ ID และใช้ /prototype หรือ /build ให้ตรงกับงานนั้น

GET/openapi/creative-lab/vinyl-figure/v1/(prototype|build)/:id/stream

สตรีมงาน Vinyl Figure

สตรีมการอัปเดตของงาน Vinyl Figure ในรูปแบบ Server-Sent Events (SSE) พาธที่ใช้ต้องตรงกับขั้นตอนของงานนั้น หากไม่ตรงกัน เช่น ใช้ ID ของงาน build ที่ /prototype/:id/stream สตรีมจะส่งอีเวนต์ error หนึ่งครั้งพร้อม status_code: 404 แล้วปิดการเชื่อมต่อ

Request

GET

/openapi/creative-lab/vinyl-figure/v1/build/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/stream

curl -N https://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/build/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example (wrong stage or task not found)
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// Every frame is the full task object; fields not yet populated are null / empty.
// The following PENDING frame is shortened to the fields that change.
event: message
data: {
  "id": "019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef",
  "type": "creative-lab-vinyl-figure-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1752969700000,
  "started_at": 1752969710000,
  "finished_at": 1752969735000,
  "expires_at": 1753228935000,
  "task_error": null,
  "consumed_credits": 30,
  "prompt": "",
  "negative_prompt": "",
  "texture_prompt": "",
  "texture_image_url": "",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.mtl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/preview.png?Expires=***",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/texture_0.png?Expires=***"
    }
  ]
}

พารามิเตอร์

Name
id
Type
path
Description
ID ของงานจากการตอบกลับตอนสร้าง

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

สตรีมของอ็อบเจ็กต์งาน prototype หรือ build แต่ละอีเวนต์จะมีอ็อบเจ็กต์งานฉบับเต็ม เช่นเดียวกับที่ ดึงข้อมูลงาน Vinyl Figure ส่งกลับ ในขณะที่งานยังอยู่ในสถานะ PENDING หรือ IN_PROGRESS ฟิลด์เอาต์พุตของงานจะยังว่างอยู่ (null, [], หรือ {}) และ finished_at จะเป็น null

หากฟีเจอร์ IP Filtering บล็อกผลลัพธ์ของงาน สตรีมจะส่งอีเวนต์ error หนึ่งครั้งแทน โดยมี status_code เดียวกับที่คำขอแบบ get จะส่งกลับ

GET/openapi/creative-lab/vinyl-figure/v1/(prototype|build)

List Vinyl Figure tasks

ส่งคืนงาน Vinyl Figure ของคุณในสเตจเดียว ครั้งละหนึ่งหน้า พาธจะเป็นตัวกำหนดสเตจ /prototype จะส่งคืนเฉพาะงานต้นแบบ (prototype) และ /build จะส่งคืนเฉพาะงานสร้าง (build)

Request

GET

/openapi/creative-lab/vinyl-figure/v1/prototype

# List prototype tasks
curl https://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/prototype?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# List build tasks
curl https://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/build?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response (List Prototype Tasks)

[
  {
    "id": "019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de",
    "type": "creative-lab-vinyl-figure-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1752969600000,
    "started_at": 1752969604000,
    "finished_at": 1752969630000,
    "expires_at": 1753228830000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "image_urls": [
      "https://assets.meshy.ai/***/concept.png?Expires=***"
    ]
  }
]

Path parameters

Name
stage
Type
path
จำเป็น
Description
สเตจที่ต้องการแสดงรายการ prototype หรือ build

Query parameters

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

Returns

อาร์เรย์ของ อ็อบเจ็กต์งานต้นแบบ (prototype) หรือ อ็อบเจ็กต์งานสร้าง (build) ตามสเตจในพาธ

The Vinyl Figure prototype task object

งานต้นแบบ (prototype task) จะสร้างภาพคอนเซปต์สไตล์ฟิกเกอร์ไวนิลจากภาพถ่าย หากต้องการแปลงภาพให้เป็นโมเดล 3D ให้ส่ง ID ของงานนี้ไปยัง build endpoint ในชื่อ input_task_id

คุณสมบัติ

Example Vinyl Figure Prototype Task Object

{
  "id": "019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de",
  "type": "creative-lab-vinyl-figure-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1752969600000,
  "started_at": 1752969604000,
  "finished_at": 1752969630000,
  "expires_at": 1753228830000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Name
id
Type
string
Description
ID ของงาน อย่าอ้างอิงจากรูปแบบของมัน
Name
type
Type
string
Description
ประเภทของงาน ซึ่งจะเป็น creative-lab-vinyl-figure-prototype เสมอ
Name
name
Type
string
Description
ค่า name ที่คุณส่งมาตอนสร้างงาน หรือ "" หากคุณไม่ได้ส่งค่านี้มา
Name
status
Type
string
Description
สถานะของงาน
ค่าที่เป็นไปได้:
- PENDING: กำลังรอในคิว
- IN_PROGRESS: กำลังสร้างผลลัพธ์
- SUCCEEDED: สถานะสุดท้าย พร้อมผลลัพธ์
- FAILED: สถานะสุดท้าย พร้อมเหตุผลใน task_error
- CANCELED: สถานะสุดท้าย โดยไม่มีผลลัพธ์
Name
progress
Type
integer
Description
เปอร์เซ็นต์ของงานที่เสร็จสิ้น ตั้งแต่ 0 ถึง 100 ค่านี้จะเป็น 0 จนกว่างานจะเริ่มทำงาน และเป็น 100 เมื่องานสำเร็จ
Name
created_at
Type
timestamp
Description
เวลาที่สร้างงาน หน่วยเป็นมิลลิวินาทีแบบ Unix
Name
started_at
Type
timestamp
Description
เวลาที่ worker เริ่มทำงานนี้ หน่วยเป็นมิลลิวินาทีแบบ Unix ค่าจะเป็น null จนกว่าจะถึงเวลานั้น
Name
finished_at
Type
timestamp
Description
เวลาที่งานไปถึงสถานะสุดท้าย หน่วยเป็นมิลลิวินาทีแบบ Unix ค่าจะเป็น null จนกว่าจะถึงเวลานั้น
Name
expires_at
Type
timestamp
Description
เวลาที่ผลลัพธ์ของงานจะหมดอายุ หน่วยเป็นมิลลิวินาทีแบบ Unix ค่านี้คือ 3 วันหลังจาก finished_at หรือ 3 วันหลังจาก created_at จนกว่างานจะเสร็จสิ้น สำหรับบัญชี Enterprise ซึ่งเก็บผลลัพธ์ของ API ไว้อย่างไม่มีกำหนด ค่านี้จะอยู่ที่ประมาณ 100 ปีถัดไป ดู Asset retention
Name
preceding_tasks
Type
integer
Description
ตำแหน่งของงานในคิวขณะที่สถานะเป็น PENDING ค่า 1 หมายความว่างานนี้จะเริ่มถัดไป และเป็น 0 หลังจากงานออกจากคิว และเป็น 0 เสมอในผลลัพธ์แบบรายการ
Name
task_error
Type
object
Description
เหตุผลที่งานล้มเหลว ค่าจะเป็น null ยกเว้นเมื่อ status เป็น FAILED ดู ข้อผิดพลาด
Name
consumed_credits
Type
integer
Description
จำนวนเครดิตที่ถูกเรียกเก็บสำหรับงานนี้ หลังจากหักการคืนเงินใด ๆ แล้ว คำขอที่ส่งคืนข้อผิดพลาดจะไม่ถูกเรียกเก็บเครดิต งานที่ล้มเหลวจะมีค่าเป็น 0 เนื่องจาก Meshy จะคืนเครดิตให้ การยกเลิกจะคืนเครดิตให้เฉพาะขณะที่งานยังอยู่ในสถานะ PENDING เท่านั้น หาก Meshy ไม่สามารถอ่านค่าการเรียกเก็บเงินได้ การตอบกลับแบบ get หรือ stream จะไม่มีฟิลด์นี้ และคำขอแบบรายการจะส่งคืน 500 ในกรณีนั้น ให้ลองส่งคำขอใหม่อีกครั้ง
Name
image_urls
Type
array of strings
Description
URL สำหรับดาวน์โหลดภาพคอนเซปต์ อาร์เรย์นี้จะมี URL หนึ่งรายการหลังจากงานสำเร็จ และจะว่างเปล่าจนกว่าจะถึงเวลานั้น

อ็อบเจ็กต์ task ของการสร้างฟิกเกอร์ Vinyl

build task จะสร้างฟิกเกอร์ Vinyl 3D ที่มีเท็กซ์เจอร์จาก prototype task ที่สำเร็จแล้ว ฟิลด์ model_urls, thumbnail_url และ texture_urls มีรูปแบบเดียวกับใน อ็อบเจ็กต์ task ของรูปภาพเป็น 3D

คุณสมบัติ

Example Vinyl Figure Build Task Object

{
  "id": "019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef",
  "type": "creative-lab-vinyl-figure-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1752969700000,
  "started_at": 1752969710000,
  "finished_at": 1752969735000,
  "expires_at": 1753228935000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "prompt": "",
  "negative_prompt": "",
  "texture_prompt": "",
  "texture_image_url": "",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.mtl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/preview.png?Expires=***",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/texture_0.png?Expires=***"
    }
  ]
}

Name
id
Type
string
Description
รหัส task อย่าอ้างอิงตามรูปแบบของมัน
Name
type
Type
string
Description
ประเภทของ task เป็น creative-lab-vinyl-figure-build เสมอ
Name
name
Type
string
Description
name ที่คุณส่งมาตอนสร้าง task หรือ "" ถ้าคุณไม่ได้ส่งมา
Name
status
Type
string
Description
สถานะของ task
ค่าที่เป็นไปได้:
- PENDING: กำลังรอในคิว
- IN_PROGRESS: กำลังสร้างผลลัพธ์
- SUCCEEDED: สถานะสุดท้าย พร้อมผลลัพธ์
- FAILED: สถานะสุดท้าย พร้อมเหตุผลใน task_error
- CANCELED: สถานะสุดท้าย ไม่มีผลลัพธ์
Name
progress
Type
integer
Description
เปอร์เซ็นต์ของงานที่เสร็จแล้ว ตั้งแต่ 0 ถึง 100 โดยจะเป็น 0 จนกว่า task จะเริ่ม และเป็น 100 เมื่อสำเร็จ
Name
created_at
Type
timestamp
Description
เวลาที่สร้าง task ในหน่วยมิลลิวินาทีแบบ Unix
Name
started_at
Type
timestamp
Description
เวลาที่ worker เริ่ม task ในหน่วยมิลลิวินาทีแบบ Unix โดยจะเป็น null จนกว่าจะเริ่ม
Name
finished_at
Type
timestamp
Description
เวลาที่ task ถึงสถานะสุดท้าย ในหน่วยมิลลิวินาทีแบบ Unix โดยจะเป็น null จนกว่าจะถึง
Name
expires_at
Type
timestamp
Description
เวลาที่ผลลัพธ์ของ task จะหมดอายุ ในหน่วยมิลลิวินาทีแบบ Unix ซึ่งคือ 3 วันหลังจาก finished_at หรือ 3 วันหลังจาก created_at จนกว่า task จะเสร็จสิ้น สำหรับบัญชี Enterprise ซึ่งเก็บผลลัพธ์ของ API ไว้ไม่มีกำหนด จะอยู่ที่ประมาณ 100 ปีถัดไป ดูที่ การเก็บรักษาแอสเซ็ต
Name
preceding_tasks
Type
integer
Description
ตำแหน่งของ task ในคิวขณะที่เป็น PENDING โดย 1 หมายถึงจะเริ่มต่อไป และเป็น 0 หลังจาก task ออกจากคิวแล้ว และจะเป็น 0 เสมอในผลลัพธ์แบบรายการ
Name
task_error
Type
object
Description
เหตุผลที่ task ล้มเหลว โดยจะเป็น null ยกเว้นในกรณีที่ status เป็น FAILED ดูที่ ข้อผิดพลาด
Name
consumed_credits
Type
integer
Description
จำนวนเครดิตที่ถูกเรียกเก็บสำหรับ task นี้ หลังจากการคืนเงินใดๆ คำขอที่คืนค่าข้อผิดพลาดจะไม่ถูกเรียกเก็บเงิน task ที่ล้มเหลวจะเป็น 0 เนื่องจาก Meshy จะคืนเครดิตให้ การยกเลิกจะคืนเครดิตให้ task ก็ต่อเมื่อยังอยู่ในสถานะ PENDING เท่านั้น หาก Meshy ไม่สามารถอ่านค่าธรรมเนียมที่เรียกเก็บได้ การตอบกลับแบบ get หรือ stream จะไม่มีฟิลด์นี้ และคำขอแบบ list จะคืนค่า 500 ในกรณีนี้ ให้ลองส่งคำขอใหม่อีกครั้ง
Name
prompt
Type
string
Description
เป็น "" เสมอสำหรับ task การสร้างฟิกเกอร์ Vinyl
Name
negative_prompt
Type
string
Description
เป็น "" เสมอสำหรับ task การสร้างฟิกเกอร์ Vinyl เช่นเดียวกับ prompt
Name
texture_prompt
Type
string
Description
เป็น "" เสมอสำหรับ task การสร้างฟิกเกอร์ Vinyl เช่นเดียวกับ prompt
Name
texture_image_url
Type
string
Description
เป็น "" เสมอสำหรับ task การสร้างฟิกเกอร์ Vinyl เช่นเดียวกับ prompt
Name
model_urls
Type
object
Description
URL สำหรับดาวน์โหลดโมเดล 3D ในรูปแบบ GLB ที่มีเท็กซ์เจอร์ และในรูปแบบไฟล์ OBJ พร้อมไฟล์ MTL
- Name
  glb
  Type
  string
  Description
  URL สำหรับดาวน์โหลดไฟล์ GLB ที่มีเท็กซ์เจอร์
- Name
  obj
  Type
  string
  Description
  URL สำหรับดาวน์โหลดไฟล์ OBJ ซึ่งมีจีออเมทรีและ UV
- Name
  mtl
  Type
  string
  Description
  URL สำหรับดาวน์โหลดไฟล์แมททีเรียล MTL ที่ใช้คู่กับ obj ใช้ร่วมกับ obj และเท็กซ์เจอร์ใน texture_urls[0].base_color
Name
thumbnail_url
Type
string
Description
URL สำหรับดาวน์โหลดภาพตัวอย่างของโมเดล
Name
texture_urls
Type
array
Description
แผนที่เท็กซ์เจอร์ ในรูปแบบอาร์เรย์ที่มีหนึ่งอ็อบเจ็กต์ซึ่งเก็บแผนที่สีพื้นฐาน (base color)
- Name
  base_color
  Type
  string
  Description
  URL สำหรับดาวน์โหลดแผนที่สีพื้นฐาน