Creative Lab — Q 版手辦 API
分兩個階段將一張原始照片轉變為大頭 Q 版手辦收藏級 3D 玩偶:prototype(原型)
階段會根據你輸入的照片生成一張風格化的概念圖,隨後 build(構建)
階段會將該概念圖轉變為帶貼圖的 3D 模型。這兩個階段透過 input_task_id
互相關聯。
POST /openapi/creative-lab/vinyl-figure/v1/prototypePOST /openapi/creative-lab/vinyl-figure/v1/build
創建盲盒手辦原型任務
根據來源照片生成一張盲盒手辦風格的概念圖。返回的任務 ID 就是你在呼叫構建 endpoint 時傳入的 input_task_id。返回體的結構請參閱
The Vinyl Figure Prototype Task Object。
參數
- Name
- image_url
- Type
- string
- 必選
- Description
供 Meshy 風格化為大頭盲盒手辦的來源照片。目前支援
.jpg、.jpeg、.png和.webp格式。提供圖片有兩種方式:
- 公開可存取的 URL:可從公共網際網路存取的 URL。
- Data URI:圖片的 base64 編碼資料 URI。資料 URI 範例:
data:image/jpeg;base64,<your base64-encoded image data>。
- Name
- name
- Type
- string
- Description
用於顯示的可選任務名稱。最多 100 個字元。
- Name
- remove_background
- Type
- boolean
- 預設值 false
- Description
設為
true時,原型圖會以去除背景的透明 RGBA PNG 形式返回,方便你將主體合成到任意背景上。
返回值
回應中的 result 屬性包含新建立的盲盒手辦原型任務的任務 id。輪詢 Get a Task endpoint 或訂閱 stream,直到任務達到 SUCCEEDED 狀態,然後將該 ID 作為 input_task_id 傳給 build endpoint。
失敗模式
- Name
400 - Bad Request- Description
請求無法被接受。常見原因:
- 缺少參數:
image_url為必填項。 - 圖片格式無效:提供的
image_url不是受支援的格式(.jpg、.jpeg、.png、.webp)。 - 圖片尺寸超出範圍:圖片過小、超出最大檔案大小或超出最大像素數。
- URL 不可存取:無法下載
image_url(404 或 timeout)。 - Data URI 無效:base64 字串格式錯誤。
- 內容被標記:輸入圖片被 NSFW 或智慧財產權 moderation 標記。
- 缺少參數:
- Name
401 - Unauthorized- Description
身份驗證失敗。請檢查你的 API key。
- Name
402 - Payment Required- Description
積分不足,無法執行此任務。
- Name
429 - Too Many Requests- Description
你已超出速率限制。
Request
# 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"
}


建立盲盒手辦構建任務
根據一個成功的原型任務,生成最終的帶貼圖 3D 盲盒手辦。構建過程運行與 Image to 3D 相同的影象生成 3D 流水線,因此回應物件格式與輸出 URL 清單完全一致。回應結構請參考 盲盒手辦構建任務物件。
參數
- Name
- input_task_id
- Type
- string
- 必選
- Description
透過同一個 OpenAPI 端點建立的原型任務的任務 ID。該原型任務必須使用同一個 API key 建立,必須已達到
SUCCEEDED狀態,並且必須只生成了一張候選圖片。透過網頁應用建立的原型任務不被接受——構建 endpoint 只接受由
POST /openapi/creative-lab/vinyl-figure/v1/prototype生成的原型任務,其他來源一律回傳404拒絕。
- Name
- name
- Type
- string
- Description
用於顯示的可選任務名稱。最多 100 個字元。
回傳值
回應的 result 屬性包含新建立的盲盒手辦構建任務的任務 id。輪詢 取得任務 endpoint 或訂閱 串流介面,直到任務達到 SUCCEEDED 狀態,然後從 model_urls.glb 下載帶貼圖的 GLB(如果你的下游流水線更適合使用 OBJ,也可以從 model_urls.obj 和 model_urls.mtl 下載對應的 OBJ + MTL 檔案對)。
失敗模式
- Name
400 - Bad Request- Description
請求不可接受。常見原因:
- 缺少參數:需要提供
input_task_id。 - 無效的 UUID:
input_task_id不是有效的 UUID。 - 父任務未成功:所引用的原型任務尚未達到
SUCCEEDED狀態。 - 無候選圖片:原型任務已成功,但未生成任何候選圖片。
- 缺少參數:需要提供
- Name
401 - Unauthorized- Description
身份驗證失敗。請檢查你的 API key。
- Name
402 - Payment Required- Description
credits 不足,無法執行此任務。
- Name
404 - Not Found- Description
所引用的原型任務不存在、屬於其他使用者,或是透過網頁應用建立的(只有 API 模式建立的原型任務才能串聯進入構建階段)。
- Name
429 - Too Many Requests- Description
你已超出速率限制。
Request
# 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"
}
檢索一個手辦公仔任務
根據有效的任務 id 檢索一個原型或構建任務。URL 路徑必須與任務所處的
階段相匹配——透過 /prototype/:id 取得構建任務會回傳 404,反之亦然。
回應結構請參閱 手辦公仔原型任務物件 和 手辦公仔構建任務物件。
參數
- Name
- id
- Type
- path
- Description
要檢索的手辦公仔任務的唯一識別碼。
回傳值
回應中包含手辦公仔任務物件。其結構取決於所請求的階段。
Request
# 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=***"
}
]
}
刪除盲盒手辦任務
取消一個盲盒手辦任務。如果任務仍處於 PENDING 狀態,建立時消耗的
積分將被退還。已處於 IN_PROGRESS 狀態的任務會被取消但不予退款
(因為工作處理程序可能已經在消耗資源)。已經達到終止狀態
(SUCCEEDED、FAILED、CANCELED)的任務無法被取消。
URL 路徑必須與任務所處的階段相匹配 —— 對
/prototype/:buildId 執行 DELETE 會回傳 404。
路徑參數
- Name
- id
- Type
- path
- Description
要取消的盲盒手辦任務的唯一識別碼。
回傳值
成功時回傳 204 No Content,回應內容為空。
失敗模式
- Name
400 - Bad Request- Description
該任務已處於終止狀態,無法取消。
- Name
404 - Not Found- Description
該任務不存在、屬於其他使用者,或其所處階段與 URL 路徑不匹配。
Request
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).
流式取得黏土人手辦任務
透過 Server-Sent Events(SSE)流式取得黏土人手辦任務的即時更新。URL 路徑必須與任務所處的階段相符——在
/prototype/:buildId/stream 處開啟串流會發出一個 status_code: 404 的
event: error 請求體,並關閉該串流。
參數
- Name
- id
- Type
- path
- Description
要進行串流傳輸的黏土人手辦任務的唯一識別碼。
回傳
以 Server-Sent Events 的形式回傳一系列黏土人手辦原型
或黏土人手辦成品任務物件。每一幀都攜帶該階段的完整任務物件——與
Get endpoint 回傳的形狀相同——因此當任務處於 PENDING 或 IN_PROGRESS
狀態時,輸出欄位只是尚未被填入(為 null、[] 或 {}),且
finished_at 為 null。
Request
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 PENDING frame below is abbreviated 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=***"
}
]
}
列出手辦立像任務
取得你在單一階段中的手辦立像任務的分頁清單。
URL 路徑決定階段——/prototype 回傳原型任務;
/build 回傳建構任務。另一階段的任務不會包含在任一回應中。
路徑參數
- Name
- stage
- Type
- path
- 必選
- Description
prototype或build二選一。此集合只會回傳階段與 URL 相符的任務——取得/prototype絕不會回傳 建構任務,反之亦然。
查詢參數
- 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:依建立時間降冪排序。
回傳
回傳該階段對應任務物件的分頁清單——列出 /prototype 時為
手辦立像原型任務物件,
列出 /build 時為
手辦立像建構任務物件。
Request
# 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=***"
]
}
]
花式手辦原型任務物件
花式手辦原型任務物件是 Meshy 用於追蹤從來源照片產生花式手辦風格概念圖的工作單元。此階段的輸出會透過 input_task_id 串聯到建構階段。
屬性
- Name
- id
- Type
- string
- Description
任務的唯一識別碼。雖然我們在實作細節中使用 k 可排序的 UUID 作為任務 id,但你不應對 id 的格式做任何假設。
- Name
- type
- Type
- string
- Description
任務的類型。該值為
creative-lab-vinyl-figure-prototype。
- Name
- name
- Type
- string
- Description
建立任務時提供的任務名稱。如果未提供名稱,則為空字串。
- Name
- status
- Type
- string
- Description
任務的狀態。可能的值為
PENDING、IN_PROGRESS、SUCCEEDED、FAILED、CANCELED之一。
- Name
- progress
- Type
- integer
- Description
任務的 progress。如果任務尚未開始,此屬性將為
0。一旦任務成功,該值將變為100。
- Name
- created_at
- Type
- timestamp
- Description
任務建立時的時間戳,以毫秒為單位。
時間戳表示自 1970 年 1 月 1 日 UTC 起經過的毫秒數,遵循 RFC 3339
標準。 例如,2023 年 9 月 1 日星期五格林威治標準時間中午 12:00:00 表示為1693569600000。這適用於 Meshy API 中的所有時間戳。
- Name
- started_at
- Type
- timestamp
- Description
任務開始時的時間戳,以毫秒為單位。如果任務尚未開始,此屬性將為
0。
- Name
- finished_at
- Type
- timestamp
- Description
任務完成時的時間戳,以毫秒為單位。如果任務尚未完成,此屬性將為
0。
- Name
- expires_at
- Type
- timestamp
- Description
任務結果過期時的時間戳,以毫秒為單位。
- 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時會出現該欄位。對於FAILED的任務,返回0(失敗時會退還積分)。
- Name
- image_urls
- Type
- array of strings
- Description
此原型任務產生的概念圖候選項的可下載 URL。目前 API 始終僅返回一個候選項;該欄位設計為陣列,以便未來版本可以在不引入破壞性變更的情況下展示多個候選項。
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=***"
]
}
潮玩手辦構建任務物件
潮玩手辦構建任務物件是 Meshy 用於追蹤從成功的原型任務生成帶貼圖的 3D 潮玩手辦 的工作單元。 它運行的是與 Image to 3D 相同的圖生 3D 流水線, 因此輸出欄位與該 endpoint 的 任務物件 相同。
屬性
- Name
- id
- Type
- string
- Description
任務的唯一識別碼。
- Name
- type
- Type
- string
- Description
任務的類型。值為
creative-lab-vinyl-figure-build。
- Name
- name
- Type
- string
- Description
建立任務時提供的任務名稱。如果未提供名稱,則為空字串。
- Name
- status
- Type
- string
- Description
任務的狀態。可能的值為
PENDING、IN_PROGRESS、SUCCEEDED、FAILED、CANCELED之一。
- Name
- progress
- Type
- integer
- Description
任務的進度。如果任務尚未開始,此屬性將為
0。一旦任務成功,此值將變為100。
- Name
- created_at
- Type
- timestamp
- Description
任務建立時間的時間戳,單位為毫秒。
- Name
- started_at
- Type
- timestamp
- Description
任務開始時間的時間戳,單位為毫秒。
- Name
- finished_at
- Type
- timestamp
- Description
任務完成時間的時間戳,單位為毫秒。
- Name
- expires_at
- Type
- timestamp
- Description
任務結果過期時間的時間戳,單位為毫秒。
- Name
- preceding_tasks
- Type
- integer
- Description
排在前面的任務數量。僅在狀態為
PENDING時有意義。
- Name
- task_error
- Type
- object
- Description
失敗任務的錯誤詳情。有關完整的
task_error物件參考,請參見 Errors。
- Name
- consumed_credits
- Type
- integer
- Description
此任務消耗的 credits 數量。對於
FAILED任務回傳0(失敗時會退還 credits)。
- Name
- prompt
- Type
- string
- Description
潮玩手辦構建始終為空。為了與 Image to 3D 所使用的共享
V2ImageTo3DTaskResponse結構實現跨 endpoint 相容而保留。
- Name
- negative_prompt
- Type
- string
- Description
潮玩手辦構建始終為空。為跨 endpoint 相容而保留。
- Name
- texture_prompt
- Type
- string
- Description
潮玩手辦構建始終為空。為跨 endpoint 相容而保留。
- Name
- texture_image_url
- Type
- string
- Description
潮玩手辦構建始終為空。為跨 endpoint 相容而保留。
- Name
- model_urls
- Type
- object
- Description
生成的 3D 模型的可下載 URL。潮玩手辦構建會生成一個帶貼圖的 GLB,以及適用於偏好 Wavefront OBJ 的流水線的 OBJ + MTL 檔案對。該欄位的結構與 Image to 3D 的 model_urls 物件一致,因此未來新增格式時不會造成破壞性變更。
- Name
glb- Type
- string
- Description
帶貼圖 GLB 檔案的可下載 URL。
- Name
obj- Type
- string
- Description
Wavefront OBJ 檔案(geometry + UV)的可下載 URL。
- Name
mtl- Type
- string
- Description
OBJ 配套 MTL 材質檔案的可下載 URL。請與
obj及texture_urls[0].base_color中的條目配合使用。
- Name
- thumbnail_url
- Type
- string
- Description
模型檔案縮圖的可下載 URL。
- Name
- texture_urls
- Type
- array
- Description
此任務生成的 texture URL 物件陣列。目前僅包含一個帶有基礎色貼圖的物件。
- Name
base_color- Type
- string
- Description
基礎色貼圖影像的可下載 URL。
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=***"
}
]
}