Creative Lab Figure API
通过两个阶段将照片转换为Q版收藏级3D手办。原型任务会根据照片生成一张概念图像。构建任务会将该图像转换为带纹理的3D模型,并将原型任务的ID作为 input_task_id 传入。
POST /openapi/creative-lab/figure/v1/prototypePOST /openapi/creative-lab/figure/v1/build
创建 Figure prototype 任务
根据一张照片生成一张 Q 版风格的概念图。要构建 3D 模型,请将此任务的 ID 作为 input_task_id 传递给 build endpoint。有关该任务字段的说明,请参阅 The Figure prototype task object。
Request
# 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"
}


参数
- Name
- image_url
- Type
- string
- 必选
- Description
要转换为 Q 版手办的照片,可以是公开可访问的 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会返回一张透明的 RGBA PNG,这样你可以将主体放置在任意背景上。构建过程也会从去除背景后的图片开始。如果 Meshy 无法移除背景,它会返回带有背景的图片,任务仍然会成功。
返回值
result 字段保存新 prototype 任务的 ID。获取该任务或对其进行流式获取,直到 status 为 SUCCEEDED。然后将该 ID 作为 input_task_id 传递给 build endpoint。
失败情形
- 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 key 缺失或无效。请检查
Authorization请求头。
- Name
402 - Payment Required- Description
以下情形之一适用:
- 账户的 credits 不足。
- API key、workspace 或成员已达到其 credit 限额。
- 该账户使用的是免费套餐。
请检查你的 credits 和套餐,然后重试。
- Name
403 - Forbidden- Description
你的团队开启了 IP Filtering,Meshy 将该图片标记为涉及第三方知识产权。请发送你拥有使用权的图片。
- Name
429 - Too Many Requests- Description
达到了以下限制之一:
- 你发送的请求超过了速率限制所允许的数量。请等待几秒钟后重试。参见 Rate limits。
- 你排队或正在运行的任务过多。请等待部分任务完成后重试。
- 在没有 credits 的无限套餐下,你已达到可在无 credits 情况下运行的任务数量上限。请等待某个任务完成,或添加 credits。
- Name
500 - Internal Server Error- Description
Meshy 遇到了服务器错误,例如无法对该图片执行知识产权检查。Meshy 不会创建该任务,并会退还已扣除的所有 credits。请重试该请求。
创建 Figure 构建任务
从一个成功的原型任务生成带贴图的 3D figure。有关其字段,请参阅 Figure 构建任务对象。
Request
# 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"
}

参数
- Name
- input_task_id
- Type
- string
- 必选
- Description
要构建的原型任务的 ID。它必须是你的账户通过
POST /openapi/creative-lab/figure/v1/prototype创建的任务,且状态为SUCCEEDED。如果该 ID 不是你通过 API 创建的 Figure 原型任务之一,将返回
404,这也包括在 Web App 中制作的原型。
- Name
- name
- Type
- string
- Description
任务的名称,最多 100 个字符。它会出现在任务的
name字段中。名称过长会返回400。
返回值
result 字段保存新构建任务的 ID。获取该任务或流式获取它,直到 status 变为 SUCCEEDED。然后从 model_urls.glb 下载带贴图的 GLB。如果想改为下载 OBJ,请从 model_urls.obj 下载,并从 model_urls.mtl 下载其 material 文件。
失败模式
- Name
400 - Bad Request- Description
请求无法执行。例如:
input_task_id缺失或不是有效的任务 ID。- 原型任务的状态不是
SUCCEEDED。如果它仍在运行,请等待后重试。如果它已失败或被取消,请创建一个新的原型任务。 - 原型任务已成功,但没有图片。请创建一个新的原型任务。
错误消息会说明发现的具体问题。
- Name
401 - Unauthorized- Description
API key 缺失或无效。请检查
Authorization请求头。
- Name
402 - Payment Required- Description
以下情况之一适用:
- 账户没有足够的 credits。
- API key、workspace 或成员已达到其 credit 限制。
- 账户处于免费计划。
请检查你的 credits 和计划,然后重试。
- Name
404 - Not Found- Description
input_task_id与你的账户通过 API 创建的任何 Figure 原型任务都不匹配。在 Web App 中制作的原型也会返回404。请发送原型创建响应中的resultID。
- Name
429 - Too Many Requests- Description
达到了以下限制之一:
- 你发送的请求超过了速率限制允许的数量。请等待几秒后重试。参见速率限制。
- 你排队或正在运行的任务过多。请等待部分任务完成后重试。
- 在无限制计划下且没有剩余 credits 时,你已达到可在没有 credits 的情况下运行的任务数量上限。请等待某个任务完成,或添加 credits。
获取 Figure 任务
返回一个 prototype 或 build 任务。路径必须与任务所处的阶段匹配。通过 /prototype/:id 请求 build 任务会返回 404,通过 /build/:id 请求 prototype 任务同样会返回 404。
字段说明请参阅 The Figure prototype task object 和 The Figure build task object。
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": 30,
"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=***"
}
]
}
参数
- Name
- id
- Type
- path
- Description
创建响应中返回的任务 ID。
返回值
与路径中阶段相匹配的 prototype task object 或 build task object。
失败情况
- Name
400 - Bad Request- Description
id不是有效的任务 ID。请发送创建响应中返回的resultID。
- Name
403 - Forbidden- Description
你的团队开启了 IP Filtering(知识产权过滤),且 Meshy 将该任务的图片标记为涉及第三方知识产权。Enterprise 方案的团队不会收到此错误。请使用你拥有使用权的图片创建 prototype 任务。
- Name
404 - Not Found- Description
你的账户下没有该 ID 对应的 Figure 任务,或任务所处阶段与路径不匹配。请检查 ID,并使用
/prototype或/build与任务相匹配。
- Name
500 - Internal Server Error- Description
Meshy 无法运行知识产权检查。请重试该请求。
删除 Figure 任务
取消一个 Figure 任务。取消 PENDING 状态的任务会退还其 credits。IN_PROGRESS 状态的任务会被取消但不退款,因为已经有工作节点开始处理该任务。处于最终状态(SUCCEEDED、FAILED 或 CANCELED)的任务无法取消。
路径必须与任务所处的阶段匹配。例如,对一个 build 任务的 ID 使用 /prototype/:id 路径执行 DELETE 会返回 404。
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
// Returns 204 No Content on success (empty body).
路径参数
- Name
- id
- Type
- path
- Description
要取消的任务的 ID。
返回值
204 No Content,响应体为空。
失败情况
- Name
400 - Bad Request- Description
以下情况之一:
id不是有效的任务 ID。请发送创建响应中的resultID。- 任务已处于最终状态(
SUCCEEDED、FAILED或CANCELED),因此无法取消。
- Name
404 - Not Found- Description
没有属于你账户的、具有此 ID 的 Figure 任务,或者该任务所处的阶段与路径不匹配。请检查 ID,并使用
/prototype或/build以匹配对应任务。
流式获取 Figure 任务
以服务器发送事件(SSE)的形式流式返回 Figure 任务的更新。路径必须与任务所处的阶段匹配。如果不匹配,例如在 /prototype/:id/stream 上使用 build 任务的 ID,流会发送一个 status_code: 404 的 error 事件,然后关闭。
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
// 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": "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": 30,
"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=***"
}
]
}
参数
- Name
- id
- Type
- path
- Description
创建响应中返回的任务 ID。
返回值
一个由 prototype 或 build 任务对象组成的流。每个事件都包含完整的任务对象,与 获取 Figure 任务 返回的内容一致。当任务处于 PENDING 或 IN_PROGRESS 状态时,其输出字段仍为空(null、[] 或 {}),且 finished_at 为 null。
如果 IP 过滤 功能阻止了任务的结果,流会改为发送一个 error 事件,其中的 status_code 与 get 请求所返回的一致。
获取 Figure 任务列表
返回某一阶段的 Figure 任务,每次返回一页。路径决定了阶段:/prototype 仅返回 prototype 任务,/build 仅返回 build 任务。
Request
# 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=***"
]
}
]
路径参数
- Name
- stage
- Type
- path
- 必选
- Description
要列出的阶段,
prototype或build。
查询参数
- 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:最早的排在最前
返回值
一个数组,包含与路径中阶段相对应的 prototype 任务对象 或 build 任务对象。
The Figure prototype task object
Prototype 任务根据一张照片生成 Q 版风格的概念图。要将该图片转换为 3D 模型,请将该任务的 ID 作为 input_task_id 传递给构建 endpoint。
Properties
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=***"
]
}
- Name
- id
- Type
- string
- Description
任务 ID。不要依赖其具体格式。
- Name
- type
- Type
- string
- Description
任务类型,始终为
creative-lab-figure-prototype。
- Name
- name
- Type
- string
- Description
你在创建任务时发送的
name,如果你没有发送,则为""。
- Name
- status
- Type
- string
- Description
任务的状态。
可选值:
PENDING:在队列中等待IN_PROGRESS:正在生成结果SUCCEEDED:最终状态,已获得结果FAILED:最终状态,失败原因见task_errorCANCELED:最终状态,没有结果
- Name
- progress
- Type
- integer
- Description
已完成工作的百分比,取值从
0到100。任务开始前为0,成功后为100。
- Name
- created_at
- Type
- timestamp
- Description
任务创建的时间,单位为 Unix 毫秒。
- Name
- started_at
- Type
- timestamp
- Description
工作进程开始处理该任务的时间,单位为 Unix 毫秒。在此之前为
null。
- Name
- finished_at
- Type
- timestamp
- Description
任务到达最终状态的时间,单位为 Unix 毫秒。在此之前为
null。
- Name
- expires_at
- Type
- timestamp
- Description
任务结果的过期时间,单位为 Unix 毫秒。该时间为
finished_at之后 3 天,在任务完成之前则为created_at之后 3 天。对于可无限期保留 API 结果的企业账户,该时间约为 100 年后。请参阅资产保留期。
- Name
- preceding_tasks
- Type
- integer
- Description
任务处于
PENDING状态时在队列中的位置。1表示该任务是下一个要开始的任务。任务离开队列后为0,在列表结果中则始终为0。
- Name
- task_error
- Type
- object
- Description
任务失败的原因。除非
status为FAILED,否则为null。请参阅 Errors。
- Name
- consumed_credits
- Type
- integer
- Description
该任务在扣除任何退款后所扣的 credits 数量。返回错误的请求不会被扣费。失败的任务为
0,因为 Meshy 会对其退款。只有在任务处于PENDING状态时取消,才会退还 credits。如果 Meshy 无法读取扣费信息,get 或 stream 响应会省略该字段,而 list 请求会返回500。在这种情况下,请重试该请求。
- Name
- image_urls
- Type
- array of strings
- Description
概念图的下载 URL。任务成功后,该数组包含一个 URL;在此之前为空。
Figure 构建任务对象
构建任务会根据成功的原型任务生成带纹理的 3D Figure。其 model_urls、thumbnail_url 和 texture_urls 字段的格式与Image to 3D 任务对象中的相同。
属性
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": 30,
"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=***"
}
]
}
- Name
- id
- Type
- string
- Description
任务 ID。请勿依赖其格式。
- Name
- type
- Type
- string
- Description
任务类型,始终为
creative-lab-figure-build。
- 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
工作进程开始处理任务的时间,以 Unix 毫秒表示。在此之前为
null。
- Name
- finished_at
- Type
- timestamp
- Description
任务达到最终状态的时间,以 Unix 毫秒表示。在此之前为
null。
- Name
- expires_at
- Type
- timestamp
- Description
任务结果过期的时间,以 Unix 毫秒表示。它是
finished_at之后 3 天,或在任务完成之前为created_at之后 3 天。对于无限期保留 API 结果的企业账户,该时间大约是 100 年之后。请参阅资产保留期。
- Name
- preceding_tasks
- Type
- integer
- Description
任务处于
PENDING状态时在队列中的位置。1表示接下来即将开始。任务离开队列后为0,在列表结果中始终为0。
- Name
- task_error
- Type
- object
- Description
任务失败的原因。除非
status为FAILED,否则为null。请参阅错误。
- Name
- consumed_credits
- Type
- integer
- Description
该任务扣除的 credits 数量,已计入任何退款。返回错误的请求不会被扣费。失败的任务为
0,因为 Meshy 会退还费用。仅在任务处于PENDING状态时取消才会退款。如果 Meshy 无法读取扣费信息,获取或流式响应会省略该字段,而列表请求会返回500。在这种情况下,请重试请求。
- Name
- prompt
- Type
- string
- Description
对于 Figure 构建任务,始终为
""。
- Name
- negative_prompt
- Type
- string
- Description
对于 Figure 构建任务,与
prompt一样始终为""。
- Name
- texture_prompt
- Type
- string
- Description
对于 Figure 构建任务,与
prompt一样始终为""。
- Name
- texture_image_url
- Type
- string
- Description
对于 Figure 构建任务,与
prompt一样始终为""。
- Name
- model_urls
- Type
- object
- Description
3D 模型的下载链接,包括带纹理的 GLB,以及带有 MTL 文件的 OBJ 文件。
- Name
glb- Type
- string
- Description
带纹理的 GLB 文件的下载链接。
- Name
obj- Type
- string
- Description
OBJ 文件的下载链接,包含几何体(geometry)和 UV。
- Name
mtl- Type
- string
- Description
与
obj配套的 MTL 材质文件的下载链接。请将其与obj以及texture_urls[0].base_color中的纹理一起使用。
- Name
- thumbnail_url
- Type
- string
- Description
模型预览图片的下载链接。
- Name
- texture_urls
- Type
- array
- Description
纹理贴图,是一个包含一个对象的数组,该对象保存基础颜色贴图。
- Name
base_color- Type
- string
- Description
基础颜色贴图的下载链接。