Creative Lab — 方块小人 API

分两个阶段将一张源照片转换为方块风格的可收藏 3D 小人 Figure： 原型（prototype） 阶段会根据你的输入照片生成一张风格化的概念图，然后 构建（build） 阶段会将该概念图转换为带贴图的 3D 模型。这两个阶段通过 input_task_id 关联在一起。

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

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

Create a Brick Figure Prototype Task

根据源照片生成单张方块风格的概念图。返回的任务 ID 即为传递给构建 endpoint 的 input_task_id。响应结构请参阅方块小人原型任务对象。

参数

Name
image_url
Type
string
必选
Description
Meshy 用于风格化为方块小人的源照片。目前支持 .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 时，原型图像将以去除背景的透明 RGBA PNG 形式返回，方便你将主体合成到任意背景中。

返回值

响应中的 result 属性包含新创建的方块小人原型任务的 id。轮询获取任务 endpoint 或订阅 stream，直到任务状态变为 SUCCEEDED，然后将该 ID 作为 input_task_id 传递给构建 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
Authentication 失败。请检查你的 API key。
Name
402 - Payment Required
Description
credits 不足，无法执行此任务。
Name
403 - Forbidden
Description
输入图片因涉嫌知识产权侵权被标记。
Name
429 - Too Many Requests
Description
你已超出速率限制。

Request

POST

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

# Stage 1: generate a brick-style concept image
curl https://api.meshy.ai/openapi/creative-lab/brick-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"
}

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

创建方块小人构建任务

从一个已成功的原型任务生成最终的带纹理 3D 方块小人。构建过程运行与 Image to 3D 相同的图生 3D 流水线，因此响应对象格式和输出 URL 列表完全一致。响应结构请参考方块小人构建任务对象。

参数

Name
input_task_id
Type
string
必选
Description
通过同一个 OpenAPI endpoint 创建的原型任务的任务 ID。该原型任务必须使用相同的 API key 创建，必须已达到 SUCCEEDED 状态，并且必须恰好生成了一张候选图片。
通过 webapp 创建的原型任务不被接受——构建 endpoint 仅接受由 POST /openapi/creative-lab/brick-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
所引用的原型任务不存在、属于其他用户，或是通过 webapp 创建的（只有 API 模式下创建的原型任务才能链接到构建任务）。
Name
429 - Too Many Requests
Description
你已超出速率限制。

Request

POST

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

# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/brick-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"
}

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

获取方块小人任务

通过有效的任务 id 获取原型或构建任务。URL 路径必须与任务所处的阶段匹配 —— 若通过 /prototype/:id 获取构建任务，将返回 404，反之亦然。

有关响应结构，请参阅方块小人原型任务对象和方块小人构建任务对象。

参数

Name
id
Type
path
Description
要获取的方块小人任务的唯一标识符。

返回值

响应包含方块小人任务对象。其结构取决于请求的是哪个阶段。

Request

GET

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

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

# Build
curl https://api.meshy.ai/openapi/creative-lab/brick-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-brick-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-brick-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=***"
    }
  ]
}

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

删除方块小人任务

取消一个方块小人任务。如果任务仍处于 PENDING 状态，创建时消耗的 credits 将被退还。已处于 IN_PROGRESS 状态的任务会被取消但不会退款（worker 可能已经在消耗资源）。已经到达终止状态（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

DELETE

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

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/brick-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/brick-figure/v1/(prototype|build)/:id/stream

流式获取方块小人任务

通过 Server-Sent Events（SSE）实时流式获取方块小人任务的更新。 URL 路径必须与任务所处的阶段一致——在 /prototype/:buildId/stream 处开启流会发出一条 status_code: 404 的 event: error payload，并关闭该流。

参数

Name
id
Type
path
Description
要进行流式获取的方块小人任务的唯一标识符。

返回值

以 Server-Sent Events 的形式返回一个由 Brick Figure Prototype 或 Brick Figure Build 任务对象组成的流。每一帧都携带该阶段的完整任务对象——与 Get endpoint 返回的结构相同—— 因此当任务处于 PENDING 或 IN_PROGRESS 状态时，输出字段只是尚未被填充（为 null、[] 或 {}），且 finished_at 为 null。

Request

GET

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

curl -N https://api.meshy.ai/openapi/creative-lab/brick-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-brick-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=***"
    }
  ]
}

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

获取方块小人任务列表

获取单个阶段的方块小人任务的分页列表。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

GET

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

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

# List build tasks
curl https://api.meshy.ai/openapi/creative-lab/brick-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-brick-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=***"
    ]
  }
]

Brick Figure 原型任务对象

Brick Figure 原型任务对象是 Meshy 用来跟踪的一个工作单元，用于从源照片生成方块风格的概念图。此阶段的输出会通过 input_task_id 链接到构建阶段。

属性

Name
id
Type
string
Description
任务的唯一标识符。虽然我们在实现细节上使用 k-可排序 UUID 作为任务 id，但你不应对 id 的格式做任何假设。
Name
type
Type
string
Description
任务的类型。该值为 creative-lab-brick-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
任务创建时间的 timestamp，以毫秒为单位。
timestamp 表示自 1970 年 1 月 1 日 UTC 起经过的毫秒数，遵循 RFC 3339 标准。例如，2023 年 9 月 1 日星期五 GMT 时间下午 12:00:00 表示为 1693569600000。这适用于 Meshy API 中的所有 timestamp。
Name
started_at
Type
timestamp
Description
任务开始时间的 timestamp，以毫秒为单位。如果任务尚未开始，此属性将为 null。
Name
finished_at
Type
timestamp
Description
任务完成时间的 timestamp，以毫秒为单位。如果任务尚未完成，此属性将为 null。
Name
expires_at
Type
timestamp
Description
任务结果过期时间的 timestamp，以毫秒为单位。
Name
preceding_tasks
Type
integer
Description
前置任务的数量。
此字段的值仅在任务状态为 PENDING 时才有意义。
Name
task_error
Type
object
Description
失败任务的错误详情。有关完整的 task_error 对象参考，请参阅 Errors。
Name
consumed_credits
Type
integer
Description
此任务消耗的 credits 数量。当任务状态为 PENDING、IN_PROGRESS 或 SUCCEEDED 时会显示该值。对于 FAILED 任务，返回 0（失败时 credits 会退还）。
Name
image_urls
Type
array of strings
Description
此原型任务生成的概念图候选项的可下载 URL。目前 API 始终只返回一个候选项；该字段是数组的原因是为了让未来版本能够在不产生破坏性变更的情况下呈现多个候选项。

Example Brick Figure Prototype Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-brick-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=***"
  ]
}

Brick Figure Build 任务对象

Brick Figure Build 任务对象是 Meshy 用来跟踪工作进度的一个工作单元，用于从已成功的原型任务生成带贴图的3D 方块小人。它运行的是 Image to 3D 所使用的相同图生3D流程，因此输出字段与该 endpoint 的任务对象一致。

属性

Name
id
Type
string
Description
任务的唯一标识符。
Name
type
Type
string
Description
任务的类型。取值为 creative-lab-brick-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
对于 brick figure build 始终为空。此字段的存在是为了与 Image to 3D 所使用的共享 V2ImageTo3DTaskResponse 结构保持跨 endpoint 兼容。
Name
negative_prompt
Type
string
Description
对于 brick figure build 始终为空。此字段的存在是为了跨 endpoint 兼容。
Name
texture_prompt
Type
string
Description
对于 brick figure build 始终为空。此字段的存在是为了跨 endpoint 兼容。
Name
texture_image_url
Type
string
Description
对于 brick figure build 始终为空。此字段的存在是为了跨 endpoint 兼容。
Name
model_urls
Type
object
Description
生成的 3D 模型的可下载 URL。brick figure 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 文件（geometry + UV）的可下载 URL。
- Name
  mtl
  Type
  string
  Description
  指向 OBJ 配套的 MTL material 文件的可下载 URL。请将其与 obj 以及 texture_urls[0].base_color 中的条目配合使用。
Name
thumbnail_url
Type
string
Description
指向模型文件缩略图（thumbnail）图像的可下载 URL。
Name
texture_urls
Type
array
Description
该任务生成的 texture URL 对象数组。目前仅包含一个带有基础颜色贴图的对象。
- Name
  base_color
  Type
  string
  Description
  指向基础颜色贴图图像的可下载 URL。

Example Brick Figure Build Task Object

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-brick-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=***"
    }
  ]
}