Creative Lab — Figure API

将源照片转换为两阶段的Q版风格收藏3D Figure：原型从输入照片生成风格化概念图像，然后构建将该概念图像转化为带贴图的3D模型。这两个阶段通过 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 原型任务

从源照片生成单个 chibi 风格的概念图像。返回的任务 ID 是您传递给构建 endpoint 的 input_task_id。请参阅 Figure 原型任务对象 以了解响应结构。

参数

  • Name
    image_url
    Type
    string
    必选
    Description

    Meshy 用于将其风格化为 chibi figure 的源照片。我们目前支持 .jpg、.jpeg、.png 和 .webp 格式。

    提供图像有两种方式：

    • 公开可访问的 URL：一个可以从公共互联网访问的 URL。
    • Data URI：图像的 base64 编码数据 URI。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 属性包含新创建的 figure 原型任务的任务 id。轮询 获取任务 endpoint 或订阅 流 直到任务达到 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

    积分不足以执行此任务。

  • 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
从源肖像开始，然后生成构建阶段使用的原型图像。
作为 Creative Lab Figure 输入使用的源肖像
Prototype input
从源照片生成的 chibi 风格人偶原型图像
Prototype output
POST/openapi/creative-lab/figure/v1/build

创建 Figure 构建任务

从成功的原型任务生成最终的贴图 3D Figure。构建运行与Image to 3D相同的图像到 3D 管道，因此响应对象格式和输出 URL 列表完全匹配。请参阅Figure 构建任务对象以了解响应结构。

参数

  • Name
    input_task_id
    Type
    string
    必选
    Description

    通过相同 OpenAPI endpoint 创建的原型任务的任务 ID。原型必须使用相同的 API key 创建，必须达到 SUCCEEDED，并且必须生成一个候选图像。

    通过 webapp 创建的原型任务不被接受——构建 endpoint 仅接受由 POST /openapi/creative-lab/figure/v1/prototype 生成的原型任务，并拒绝任何其他来源，返回 404。

  • Name
    name
    Type
    string
    Description

    用于显示的可选任务名称。最多 100 个字符。

返回

响应的 result 属性包含新创建的 Figure 构建任务的任务 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

    Authentication 失败。请检查您的 API key。

  • Name
    402 - Payment Required
    Description

    积分不足以执行此任务。

  • Name
    404 - Not Found
    Description

    引用的原型任务不存在，属于不同用户，或通过 webapp 创建（仅 API 模式原型任务可链接到构建）。

  • 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"
}
构建示例
构建任务将选定的原型图像转换为可下载的贴图 3D 模型。
Creative Lab Figure 构建模型预览
构建模型预览
GET/openapi/creative-lab/figure/v1/(prototype|build)/:id

检索 Figure 任务

给定一个有效的任务 id，检索一个原型或构建任务。URL 路径必须匹配任务的阶段——通过 /prototype/:id 获取构建任务会返回 404，反之亦然。

请参阅 Figure 原型任务对象 和 Figure 构建任务对象 以获取响应结构。

参数

  • Name
    id
    Type
    path
    Description

    要检索的 Figure 任务的唯一标识符。

返回

响应包含 Figure 任务对象。形状取决于请求的阶段。

请求

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}"

原型响应

{
  "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=***"
  ]
}

构建响应

{
  "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 状态的任务将被取消且不退款（工作者可能已经在消耗 Resources）。已经达到终止状态（SUCCEEDED、FAILED、CANCELED）的任务无法取消。

URL 路径必须与任务的阶段匹配 — 在 /prototype/:buildId 上执行 DELETE 将返回 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

流式传输 Figure 任务

通过服务器发送事件 (SSE) 流式传输 Figure 任务的实时更新。 URL 路径必须与任务的阶段匹配——在 /prototype/:buildId/stream 打开流会发出一个 event: error payload，包含 status_code: 404，并关闭流。

参数

  • Name
    id
    Type
    path
    Description

    要流式传输的 Figure 任务的唯一标识符。

返回

返回 Figure Prototype 或 Figure Build 任务对象的流作为服务器发送事件。 对于 PENDING 或 IN_PROGRESS 任务，响应流将仅包含必要的 progress 和 status 字段。

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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
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)

列出 Figure 任务

检索单个阶段的 Figure 任务的分页列表。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

    页大小限制。最大允许为 50 项。

  • Name
    sort_by
    Type
    string
    默认值 -created_at
    Description

    排序字段。可用值：

    • +created_at: 按创建时间升序排序。
    • -created_at: 按创建时间降序排序。

返回

返回每阶段任务对象的分页列表 — 列出 /prototype 时为 Figure 原型任务对象，列出 /build 时为 Figure 构建任务对象。

请求

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}"

响应（列出原型任务）

[
  {
    "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=***"
    ]
  }
]

Figure 原型任务对象

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

属性

  • Name
    id
    Type
    string
    Description

    任务的唯一标识符。虽然我们使用 k-sortable UUID 作为任务 ID 的实现细节，但您不应对 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 日星期五 12:00:00 PM GMT 表示为 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 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=***"
  ]
}

Figure Build 任务对象

Figure Build 任务对象是 Meshy 用于跟踪生成带贴图的3D 图形的工作单元，该图形来自成功的原型任务。它运行与 Image to 3D 相同的图像到 3D 管道，因此输出字段与该 endpoint 的 任务对象 相对应。

属性

  • 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

    对于 figure build 始终为空。为了与 Image to 3D 使用的共享 V2ImageTo3DTaskResponse 形状的跨 endpoint 兼容性而存在。

  • Name
    negative_prompt
    Type
    string
    Description

    对于 figure build 始终为空。为了跨 endpoint 兼容性而存在。

  • Name
    texture_prompt
    Type
    string
    Description

    对于 figure build 始终为空。为了跨 endpoint 兼容性而存在。

  • Name
    texture_image_url
    Type
    string
    Description

    对于 figure build 始终为空。为了跨 endpoint 兼容性而存在。

  • Name
    model_urls
    Type
    object
    Description

    生成的 3D 模型的可下载 URL。figure build 发出带贴图的 GLB 以及 OBJ + MTL 对于偏好 Wavefront OBJ 的管道。字段形状与 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 对象数组。目前包含一个带有基础颜色贴图的对象。

    • Name
      base_color
      Type
      string
      Description

      基础颜色贴图图像的可下载 URL。

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=***"
    }
  ]
}