Creative Lab — ฟิกเกอร์ API

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

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

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

สร้างงาน Figure Prototype

สร้างภาพคอนเซปต์สไตล์ chibi เพียงภาพเดียวจากภาพถ่ายต้นฉบับ ID ของงานที่ได้รับกลับมาคือสิ่งที่คุณจะส่งเป็น input_task_id ไปยัง build endpoint โปรดดู The Figure Prototype Task Object สำหรับรูปแบบของการตอบกลับ

พารามิเตอร์

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

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

พร็อพเพอร์ตี้ result ของการตอบกลับจะมี id ของงาน figure prototype ที่สร้างขึ้นใหม่ ให้ทำการ poll เอนด์พอยต์ Get a Task หรือสมัครรับ stream จนกว่างานจะมีสถานะเป็น SUCCEEDED จากนั้นส่ง ID นั้นไปยัง build endpoint ในรูปแบบ input_task_id

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

Name
400 - Bad Request
Description
คำขอไม่สามารถยอมรับได้ สาเหตุที่พบบ่อย:
- ไม่มีพารามิเตอร์: จำเป็นต้องมี image_url
- รูปแบบภาพไม่ถูกต้อง: image_url ที่ระบุไม่ใช่รูปแบบที่รองรับ (.jpg, .jpeg, .png, .webp)
- ขนาดภาพอยู่นอกช่วงที่กำหนด: ภาพมีขนาดเล็กเกินไป เกินขนาดไฟล์สูงสุด หรือเกินจำนวนพิกเซลสูงสุด
- URL ไม่สามารถเข้าถึงได้: ไม่สามารถดาวน์โหลด image_url ได้ (404 หรือ timeout)
- Data URI ไม่ถูกต้อง: สตริง base64 มีรูปแบบไม่ถูกต้อง
- เนื้อหาถูกตั้งค่าสถานะ: ภาพที่นำเข้าถูกตั้งค่าสถานะโดยระบบ moderation ด้าน NSFW หรือทรัพย์สินทางปัญญา
Name
401 - Unauthorized
Description
การยืนยันตัวตนล้มเหลว โปรดตรวจสอบ API คีย์ของคุณ
Name
402 - Payment Required
Description
เครดิตไม่เพียงพอสำหรับการทำงานนี้
Name
429 - Too Many Requests
Description
คุณได้เกินการจำกัดอัตราที่กำหนดไว้แล้ว

Request

POST

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

# Stage 1: generate a chibi-style concept image
curl https://api.meshy.ai/openapi/creative-lab/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": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

Prototype example

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

Source portrait used as the Creative Lab Figure input — Prototype input

Chibi-style figurine prototype image generated from the source photo — Prototype output

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

สร้าง Figure Build Task

สร้างฟิกเกอร์ 3D ที่มีพื้นผิวสมบูรณ์จาก prototype task ที่สำเร็จแล้ว การ build จะทำงานผ่านไปป์ไลน์ image-to-3D แบบเดียวกับ รูปภาพเป็น 3D ดังนั้นรูปแบบของ response object และ รายการ output URLs จึงตรงกันทุกประการ ดูรูปแบบของ response ได้ที่ The Figure Build Task Object

พารามิเตอร์

Name
input_task_id
Type
string
จำเป็น
Description
รหัส task ของ prototype task ที่สร้างผ่านเอนด์พอยต์ OpenAPI นี้ prototype จะต้องถูกสร้างด้วย API คีย์เดียวกัน ต้องมีสถานะถึง SUCCEEDED แล้ว และต้องผลิตภาพตัวเลือกออกมาเพียงหนึ่งภาพเท่านั้น
prototype task ที่สร้างผ่านเว็บแอป จะไม่ ได้รับการยอมรับ — เอนด์พอยต์ build จะยอมรับเฉพาะ prototype task ที่ถูกผลิตขึ้นโดย POST /openapi/creative-lab/figure/v1/prototype เท่านั้น และจะปฏิเสธแหล่งที่มาอื่น ๆ ทั้งหมดด้วย 404
Name
name
Type
string
Description
ชื่อ task ที่ไม่บังคับ ใช้เพื่อการแสดงผล สูงสุด 100 ตัวอักษร

สิ่งที่ได้รับกลับมา

พร็อพเพอร์ตี้ result ของ response จะมี id ของ task ของ figure build task ที่สร้างขึ้นใหม่ ให้ทำการ poll เอนด์พอยต์ Get a Task หรือสมัครรับ stream จนกว่า task จะมีสถานะถึง SUCCEEDED จากนั้นดาวน์โหลดไฟล์ GLB ที่มีพื้นผิวสมบูรณ์จาก model_urls.glb (หรือคู่ไฟล์ OBJ + MTL จาก model_urls.obj และ model_urls.mtl หากไปป์ไลน์ downstream ของคุณต้องการใช้ OBJ)

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

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

Request

POST

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

# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
  }'

Response

{
  "result": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"
}

Build example

build task จะเปลี่ยนภาพ prototype ที่เลือกไว้ให้กลายเป็นโมเดล 3D ที่มีพื้นผิวสมบูรณ์และสามารถดาวน์โหลดได้

ตัวอย่างพรีวิวโมเดล Creative Lab Figure build — ตัวอย่างพรีวิวโมเดล build

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

เรียกดูงานสร้างฟิกเกอร์

เรียกดูงาน prototype หรือ build โดยใช้ id ของงานที่ถูกต้อง URL path จะต้องตรงกับขั้นตอนของงานนั้น ๆ — หากเรียกดูงาน build ผ่าน /prototype/:id จะได้รับ 404 และในทางกลับกันก็เช่นเดียวกัน

ดู The Figure Prototype Task Object และ The Figure Build Task Object สำหรับ รูปแบบของการตอบกลับ

พารามิเตอร์

Name
id
Type
path
Description
ตัวระบุเฉพาะของงานฟิกเกอร์ที่ต้องการเรียกดู

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

การตอบกลับจะประกอบด้วยอ็อบเจ็กต์งานฟิกเกอร์ โดยรูปแบบจะขึ้นอยู่กับ ขั้นตอนที่ร้องขอ

Request

GET

/openapi/creative-lab/figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578

# Prototype
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-figure-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Build Response

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-figure-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 20,
  "prompt": "",
  "negative_prompt": "",
  "texture_prompt": "",
  "texture_image_url": "",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.mtl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/preview.png?Expires=***",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/texture_0.png?Expires=***"
    }
  ]
}

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

ลบงาน Figure

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

เส้นทาง URL ต้องตรงกับขั้นตอนของงาน — การเรียก DELETE ที่ /prototype/:buildId จะคืนค่า 404

พารามิเตอร์เส้นทาง

Name
id
Type
path
Description
ตัวระบุเฉพาะสำหรับงาน Figure ที่ต้องการยกเลิก

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

ส่งคืน 204 No Content เมื่อสำเร็จ พร้อมเนื้อหาว่างเปล่า

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

Name
400 - Bad Request
Description
งานอยู่ในสถานะสิ้นสุดแล้วและไม่สามารถยกเลิกได้
Name
404 - Not Found
Description
ไม่พบงานนี้ เป็นของผู้ใช้รายอื่น หรือขั้นตอนของงานไม่ตรงกับเส้นทาง URL

Request

DELETE

/openapi/creative-lab/figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

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

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

สตรีมงานฟิกเกอร์

สตรีมข้อมูลอัปเดตแบบเรียลไทม์สำหรับงานฟิกเกอร์ผ่าน Server-Sent Events (SSE) URL path ต้องตรงกับขั้นตอนของงาน — การเปิดสตรีมที่ /prototype/:buildId/stream จะส่งเพย์โหลด event: error เพียงรายการเดียวที่มี status_code: 404 แล้วปิดสตรีม

พารามิเตอร์

Name
id
Type
path
Description
ตัวระบุเฉพาะสำหรับงานฟิกเกอร์ที่จะสตรีม

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

ส่งคืนสตรีมของอ็อบเจกต์งาน Figure Prototype หรือ Figure Build ในรูปแบบ Server-Sent Events ทุกเฟรมจะบรรจุอ็อบเจกต์งานฉบับเต็มของขั้นตอนนั้น ๆ — รูปแบบเดียวกับที่ เอนด์พอยต์ Get ส่งคืน — ดังนั้นในขณะที่งานยังอยู่ในสถานะ PENDING หรือ IN_PROGRESS ฟิลด์เอาต์พุตจะยังไม่ถูกกรอกข้อมูล (null, [] หรือ {}) และ finished_at จะเป็น null

Request

GET

/openapi/creative-lab/figure/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream

curl -N https://api.meshy.ai/openapi/creative-lab/figure/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/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 PENDING frame below is abbreviated to the fields that change.
event: message
data: {
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-figure-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "task_error": null,
  "consumed_credits": 20,
  "prompt": "",
  "negative_prompt": "",
  "texture_prompt": "",
  "texture_image_url": "",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.mtl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/preview.png?Expires=***",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/texture_0.png?Expires=***"
    }
  ]
}

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

List Figure Tasks

ดึงรายการงานฟิกเกอร์ของคุณแบบแบ่งหน้าสำหรับสเตจเดียว พาธ URL จะเลือกสเตจ — /prototype จะคืนงานต้นแบบ (prototype); /build จะคืนงานสร้าง (build) งานจากอีกสเตจหนึ่งจะไม่ถูกรวมอยู่ในการตอบกลับใด ๆ

Path Parameters

Name
stage
Type
path
จำเป็น
Description
เป็นได้ทั้ง prototype หรือ build คอลเลกชันจะคืนเฉพาะงาน ที่มีสเตจตรงกับ URL — การดึงข้อมูลจาก /prototype จะไม่คืนงาน build และในทางกลับกันก็เช่นกัน

Query Parameters

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

Returns

คืนค่ารายการแบบแบ่งหน้าของอ็อบเจกต์งานเฉพาะสเตจ — อาจเป็น อ็อบเจกต์งานต้นแบบฟิกเกอร์ เมื่อเรียกดูรายการ /prototype หรือ อ็อบเจกต์งานสร้างฟิกเกอร์ เมื่อ เรียกดูรายการ /build

Request

GET

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

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

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

Response (List Prototype Tasks)

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-figure-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729123456000,
    "started_at": 1729123460000,
    "finished_at": 1729123486000,
    "expires_at": 1729382686000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "image_urls": [
      "https://assets.meshy.ai/***/concept.png?Expires=***"
    ]
  }
]

The Figure Prototype Task Object

Figure Prototype Task object คือหน่วยงานที่ Meshy คอยติดตามเพื่อสร้าง ภาพคอนเซปต์ สไตล์ชิบิ (chibi) จากภาพถ่ายต้นฉบับ ผลลัพธ์ของขั้นตอนนี้จะถูกส่งต่อไปยังขั้นตอนการสร้าง ผ่าน input_task_id

Properties

Name
id
Type
string
Description
ตัวระบุเฉพาะสำหรับ task นี้ แม้ว่าเราจะใช้ k-sortable UUID สำหรับ id ของ task เป็นรายละเอียดในการนำไปใช้งาน แต่คุณไม่ควรตั้งสมมติฐานใด ๆ เกี่ยวกับรูปแบบของ id
Name
type
Type
string
Description
ประเภทของ task ค่าคือ creative-lab-figure-prototype
Name
name
Type
string
Description
ชื่อ task ที่ระบุไว้ตอนสร้าง task เป็นสตริงว่างหากไม่ได้ระบุชื่อ
Name
status
Type
string
Description
สถานะของ task ค่าที่เป็นไปได้คือ PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED
Name
progress
Type
integer
Description
progress ของ task หาก task ยังไม่เริ่มดำเนินการ ค่าของ property นี้จะเป็น 0 เมื่อ task สำเร็จแล้ว ค่านี้จะกลายเป็น 100
Name
created_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่สร้าง task หน่วยเป็นมิลลิวินาที
ไทม์สแตมป์แสดงถึงจำนวนมิลลิวินาทีที่ผ่านไปนับตั้งแต่วันที่ 1 มกราคม 1970 UTC ตามมาตรฐาน RFC 3339 ตัวอย่างเช่น วันศุกร์ที่ 1 กันยายน 2023 เวลา 12:00:00 น. GMT จะแสดงเป็น 1693569600000 ซึ่งใช้กับ ไทม์สแตมป์ทั้งหมดใน Meshy API
Name
started_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่ task เริ่มดำเนินการ หน่วยเป็นมิลลิวินาที หาก task ยังไม่เริ่มดำเนินการ ค่าของ property นี้จะเป็น 0
Name
finished_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่ task เสร็จสิ้น หน่วยเป็นมิลลิวินาที หาก task ยังไม่เสร็จสิ้น ค่าของ property นี้จะเป็น 0
Name
expires_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่ผลลัพธ์ของ task จะหมดอายุ หน่วยเป็นมิลลิวินาที
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 (เครดิตจะถูกคืนเมื่อล้มเหลว)
Name
image_urls
Type
array of strings
Description
URL ที่ดาวน์โหลดได้สำหรับภาพคอนเซปต์ตัวเลือกที่สร้างโดย prototype task นี้ ปัจจุบัน API จะส่งคืนตัวเลือกเพียงหนึ่งรายการเสมอ ฟิลด์นี้เป็นอาร์เรย์เพื่อให้เวอร์ชันในอนาคตสามารถแสดงตัวเลือกได้หลายรายการโดยไม่ทำให้เกิดการเปลี่ยนแปลงที่ไม่รองรับย้อนหลัง

Example Figure Prototype Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-figure-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

The Figure Build Task Object

Figure Build Task object เป็นหน่วยงานที่ Meshy ใช้ติดตามเพื่อสร้าง ฟิกเกอร์ 3D ที่มีการลงเท็กซ์เจอร์จาก prototype task ที่สำเร็จแล้ว โดยจะรันไปป์ไลน์ image-to-3D แบบเดียวกับที่ รูปภาพเป็น 3D ใช้ ดังนั้นฟิลด์ผลลัพธ์จึงสอดคล้องกับ task object ของเอนด์พอยต์นั้น

คุณสมบัติ

Name
id
Type
string
Description
ตัวระบุที่ไม่ซ้ำกันสำหรับ task
Name
type
Type
string
Description
ประเภทของ task ค่าคือ creative-lab-figure-build
Name
name
Type
string
Description
ชื่อ task ที่ระบุตอนสร้าง task เป็นสตริงว่างหากไม่ได้ระบุชื่อ
Name
status
Type
string
Description
สถานะของ task ค่าที่เป็นไปได้คือ PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED
Name
progress
Type
integer
Description
progress ของ task หาก task ยังไม่เริ่ม คุณสมบัตินี้จะเป็น 0 เมื่อ task สำเร็จแล้ว ค่าจะกลายเป็น 100
Name
created_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่สร้าง task หน่วยเป็นมิลลิวินาที
Name
started_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่ task เริ่มทำงาน หน่วยเป็นมิลลิวินาที
Name
finished_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่ task เสร็จสิ้น หน่วยเป็นมิลลิวินาที
Name
expires_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่ผลลัพธ์ของ task จะหมดอายุ หน่วยเป็นมิลลิวินาที
Name
preceding_tasks
Type
integer
Description
จำนวน task ที่อยู่ก่อนหน้า มีความหมายเฉพาะเมื่อสถานะเป็น PENDING
Name
task_error
Type
object
Description
รายละเอียดข้อผิดพลาดสำหรับ task ที่ล้มเหลว ดู ข้อผิดพลาด สำหรับข้อมูลอ้างอิงฉบับเต็มของออบเจ็กต์ task_error
Name
consumed_credits
Type
integer
Description
จำนวนเครดิตที่ถูกใช้โดย task นี้ จะคืนค่า 0 สำหรับ task ที่ FAILED (เครดิตจะถูกคืนเมื่อล้มเหลว)
Name
prompt
Type
string
Description
ว่างเปล่าเสมอสำหรับ figure build มีไว้เพื่อความเข้ากันได้ข้ามเอนด์พอยต์กับรูปแบบ V2ImageTo3DTaskResponse ที่ใช้ร่วมกันโดย รูปภาพเป็น 3D
Name
negative_prompt
Type
string
Description
ว่างเปล่าเสมอสำหรับ figure build มีไว้เพื่อความเข้ากันได้ข้ามเอนด์พอยต์
Name
texture_prompt
Type
string
Description
ว่างเปล่าเสมอสำหรับ figure build มีไว้เพื่อความเข้ากันได้ข้ามเอนด์พอยต์
Name
texture_image_url
Type
string
Description
ว่างเปล่าเสมอสำหรับ figure build มีไว้เพื่อความเข้ากันได้ข้ามเอนด์พอยต์
Name
model_urls
Type
object
Description
URL สำหรับดาวน์โหลดโมเดล 3D ที่สร้างขึ้น figure build จะสร้างไฟล์ GLB ที่มีการลงเท็กซ์เจอร์ พร้อมคู่ไฟล์ OBJ + MTL สำหรับไปป์ไลน์ที่ต้องการใช้ Wavefront OBJ รูปแบบของฟิลด์นี้ตรงกับออบเจ็กต์ model_urls ของ Image to 3D เพื่อให้รองรับการเพิ่มรูปแบบไฟล์ในอนาคตได้โดยไม่กระทบต่อความเข้ากันได้
- Name
  glb
  Type
  string
  Description
  URL สำหรับดาวน์โหลดไฟล์ GLB ที่มีการลงเท็กซ์เจอร์
- Name
  obj
  Type
  string
  Description
  URL สำหรับดาวน์โหลดไฟล์ Wavefront 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
อาร์เรย์ของออบเจ็กต์ URL เท็กซ์เจอร์ที่สร้างโดย task นี้ ปัจจุบันมีออบเจ็กต์เดียวที่มีแมป base color
- Name
  base_color
  Type
  string
  Description
  URL สำหรับดาวน์โหลดรูปภาพแมป base color

Example Figure Build Task Object

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-figure-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 20,
  "prompt": "",
  "negative_prompt": "",
  "texture_prompt": "",
  "texture_image_url": "",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.mtl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/preview.png?Expires=***",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/texture_0.png?Expires=***"
    }
  ]
}