创意工坊 — 手办 API
把你的照片变成 Q 版风格的可收藏 3D 手办。整个流程分两段：
prototype 用源照片生成一张风格化概念图，build 再把概念图转成带贴图的
3D 模型。两段通过 input_task_id 串联。
POST /openapi/creative-lab/figure/v1/prototypePOST /openapi/creative-lab/figure/v1/build
创建手办 Prototype 任务
从源照片生成一张 Q 版风格的概念图。返回的任务 ID 即作为后续 build 端点的
input_task_id。响应结构详见
Prototype 任务对象。
参数
- Name
- image_url
- Type
- string
- 必选
- Description
提供给 Meshy 用于 Q 版手办风格化的源照片。目前支持
.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 个字符。
返回值
响应的 result 字段返回新创建的 figure prototype 任务的 id。轮询
查询任务 或订阅 流式更新
直到任务状态变为 SUCCEEDED，再把该 ID 作为
build 端点 的 input_task_id 传入。
失败场景
- Name
400 - Bad Request- Description
请求不合法，常见原因：
- 缺少参数：
image_url必传。 - 图片格式不支持：
image_url不是受支持的格式（.jpg、.jpeg、.png、.webp）。 - 图片尺寸不合法：图片过小、文件超过最大体积上限，或像素数超过上限。
- URL 无法访问：
image_url下载失败（404 或超时）。 - Data URI 不合法：base64 字符串格式错误。
- 内容被审核拦截：图片被 NSFW 或知识产权审核标记。
- 缺少参数：
- Name
401 - Unauthorized- Description
身份验证失败，请检查 API key。
- Name
402 - Payment Required- Description
积分不足，无法创建任务。
- Name
429 - Too Many Requests- Description
请求超出速率限制。
Request
# Stage 1：生成 Q 版风格的概念图
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"
}
创建手办 Build 任务
根据已成功的 prototype 任务，生成最终的带贴图 3D 手办。Build 走与 Image to 3D 相同的图生 3D 管线，因此响应字段与输出 URL 与之完全一致。响应结构详见 Build 任务对象。
参数
- Name
- input_task_id
- Type
- string
- 必选
- Description
通过同一个 OpenAPI 端点创建的 prototype 任务的 ID。该 prototype 必须由同一 API key 创建、状态已变为
SUCCEEDED，且产出恰好一张候选图。通过 webapp 创建的 prototype 任务不接受 —— build 端点只接受由
POST /openapi/creative-lab/figure/v1/prototype产生的任务，其它来源一律返回404。
- Name
- name
- Type
- string
- Description
可选的任务名称，仅用于展示。最长 100 个字符。
返回值
响应的 result 字段返回新创建的 figure build 任务的 id。轮询
查询任务 或订阅 流式更新
直到任务状态变为 SUCCEEDED，即可从 model_urls.glb 下载带贴图的 GLB；如果下游流程更习惯 Wavefront OBJ，可以同时从 model_urls.obj 与 model_urls.mtl 下载 OBJ + MTL 组合。
失败场景
- Name
400 - Bad Request- Description
请求不合法，常见原因：
- 缺少参数：
input_task_id必传。 - UUID 不合法：
input_task_id不是合法 UUID。 - 父任务未成功：引用的 prototype 任务尚未达到
SUCCEEDED。 - 没有候选图：prototype 任务虽然成功，但未产出任何候选图。
- 缺少参数：
- Name
401 - Unauthorized- Description
身份验证失败，请检查 API key。
- Name
402 - Payment Required- Description
积分不足，无法创建任务。
- Name
404 - Not Found- Description
引用的 prototype 任务不存在、属于其他用户，或是 webapp 创建的（只接受 API 模式的 prototype 任务）。
- Name
429 - Too Many Requests- Description
请求超出速率限制。
Request
# Stage 2：基于已成功的 prototype 任务串联 build
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"
}
查询手办任务
根据合法的任务 id 查询 prototype 或 build 任务。URL 路径必须与任务所属的 stage
一致 —— 通过 /prototype/:id 查询一个 build 任务会返回 404，反之亦然。
响应结构详见 手办 Prototype 任务对象 和 手办 Build 任务对象。
参数
- Name
- id
- Type
- path
- Description
要查询的 figure 任务的唯一标识。
返回值
返回 figure 任务对象，具体形状取决于请求的 stage。
Request
# 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=***"
}
]
}
删除手办任务
取消一个 figure 任务。如果任务仍处于 PENDING，创建时扣除的积分会自动退还。
已经进入 IN_PROGRESS 的任务可以取消但不退款（worker 可能已经在消耗算力）。
已经处于终态（SUCCEEDED、FAILED、CANCELED）的任务无法取消。
URL 路径必须与任务所属的 stage 一致 —— 用 /prototype/:buildId 发 DELETE 会返回 404。
路径参数
- Name
- id
- Type
- path
- Description
要取消的 figure 任务的唯一标识。
返回值
成功时返回 204 No Content，响应体为空。
失败场景
- Name
400 - Bad Request- Description
任务已经处于终态，无法取消。
- Name
404 - Not Found- Description
任务不存在、属于其他用户，或所属 stage 与 URL 路径不一致。
Request
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
// 成功时返回 204 No Content，响应体为空。
流式订阅手办任务
通过 Server-Sent Events（SSE）实时订阅 figure 任务更新。URL 路径必须与任务所属的
stage 一致 —— 在 /prototype/:buildId/stream 上打开 stream 会立刻返回一条
event: error、status_code: 404 的 SSE 事件并关闭连接。
参数
- Name
- id
- Type
- path
- Description
要订阅的 figure 任务的唯一标识。
返回值
返回一串 手办 Prototype 或
手办 Build 任务对象的 Server-Sent Events。
对 PENDING 或 IN_PROGRESS 状态的任务，事件流只会包含必要的 progress 与
status 字段。
Request
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
// 错误事件示例（stage 不匹配或任务不存在）
event: error
data: {
"status_code": 404,
"message": "Task not found"
}
// 消息事件示例：表示任务进度。
// PENDING / IN_PROGRESS 状态下，事件流不包含全部字段。
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=***"
}
]
}
列出手办任务
按阶段分页列出当前 API key 名下的手办任务。URL 路径决定阶段——
/prototype 返回 Prototype 任务；/build 返回 Build 任务。
跨阶段的任务不会出现在另一边的响应中。
路径参数
- Name
- stage
- Type
- path
- 必选
- Description
必须为
prototype或build。集合只返回与 URL 阶段一致的任务——/prototype永远不会返回 Build 任务，反之亦然。
查询参数
- Name
- page_num
- Type
- integer
- 默认值 1
- Description
分页页码。
- Name
- page_size
- Type
- integer
- 默认值 10
- Description
每页条目数。最大
50。
- Name
- sort_by
- Type
- string
- 默认值 -created_at
- Description
排序字段。可选值：
+created_at：按创建时间升序排序。-created_at：按创建时间降序排序。
返回值
返回按阶段过滤的任务对象分页列表 —— 列出 /prototype 时返回
手办 Prototype 任务对象，
列出 /build 时返回 手办 Build 任务对象。
请求
# 列出 Prototype 任务
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/prototype?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
# 列出 Build 任务
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/build?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
响应（列出 Prototype 任务）
[
{
"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=***"
]
}
]
手办 Prototype 任务对象
手办 Prototype 任务是 Meshy 用来跟踪「从源照片生成 Q 版概念图」这一阶段的工作单元。
该阶段的输出通过 input_task_id 链入
Build 阶段。
字段
- Name
- id
- Type
- string
- Description
任务的唯一标识。我们当前使用 k-sortable UUID 作为实现细节，但不应对 id 的格式做任何假设。
- Name
- type
- Type
- string
- Description
任务类型，值为
creative-lab-figure-prototype。
- 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
任务创建时间戳，单位毫秒。
时间戳是自 1970 年 1 月 1 日 UTC 起经过的毫秒数，遵循 RFC 3339 标准。 例如，2023 年 9 月 1 日（星期五）UTC 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对象的完整字段定义详情请参阅 Errors。
- Name
- consumed_credits
- Type
- integer
- Description
该任务消耗的积分数。状态为
PENDING、IN_PROGRESS、SUCCEEDED时存在；FAILED时返回0（失败任务会退款）。
- Name
- image_urls
- Type
- array of strings
- Description
该 prototype 任务产出的概念图候选 URL 数组。目前 API 始终只返回一张候选；保留数组形态，方便未来在不破坏兼容性的前提下扩展到多候选。
手办 Prototype 任务对象示例
{
"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 任务对象
手办 Build 任务是 Meshy 用来跟踪「从已成功的 prototype 任务生成带贴图 3D 手办」 这一阶段的工作单元。它内部走与 Image to 3D 相同的图生 3D 管线， 因此输出字段与该端点的 任务对象 形态一致。
字段
- Name
- id
- Type
- string
- Description
任务的唯一标识。
- Name
- type
- Type
- string
- Description
任务类型，值为
creative-lab-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
该任务消耗的积分数。
FAILED时返回0（失败任务会退款）。
- Name
- prompt
- Type
- string
- Description
手办 Build 始终为空字符串。保留该字段用于与 Image to 3D 共享的
V2ImageTo3DTaskResponse形态保持兼容。
- Name
- negative_prompt
- Type
- string
- Description
手办 Build 始终为空字符串。保留该字段用于跨端点兼容。
- Name
- texture_prompt
- Type
- string
- Description
手办 Build 始终为空字符串。保留该字段用于跨端点兼容。
- Name
- texture_image_url
- Type
- string
- Description
手办 Build 始终为空字符串。保留该字段用于跨端点兼容。
- Name
- model_urls
- Type
- object
- Description
生成的 3D 模型文件下载 URL。手办 Build 输出带贴图的 GLB，以及偏好 Wavefront OBJ 流程使用的 OBJ + MTL 组合；字段形态对齐 Image to 3D model_urls 对象，未来新增格式不会破坏兼容性。
- Name
glb- Type
- string
- Description
带贴图 GLB 文件的下载 URL。
- Name
obj- Type
- string
- Description
Wavefront OBJ 文件（包含几何与 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
该任务产出的贴图 URL 对象数组。目前只包含一个对象，仅含 base color。
- Name
base_color- Type
- string
- Description
基础颜色（base color）贴图的下载 URL。
手办 Build 任务对象示例
{
"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=***"
}
]
}