Creative Lab 可折叠指尖玩具 API

通过一次任务将照片转换为可直接打印、无需组装的可折叠指尖玩具。主体的轮廓会变成层层嵌套的同心圆环，可以压扁收起，也可以拉伸展开。该玩具一次性打印成型，无需组装。

POST /openapi/creative-lab/fidget-collapsible/v1

与其他 Creative Lab endpoint 不同，此 endpoint 没有单独的原型阶段和构建阶段。没有可供选择的候选图像，因此一次任务就能将照片转换为 3D 模型。

该请求也没有 geometry 设置。Web App 允许你设置尺寸、层数、间隙宽度、壁厚、挤出深度和凸起程度。每个 API 任务都对这些参数使用相同的默认值。

POST/openapi/creative-lab/fidget-collapsible/v1

创建一个 Collapsible Fidget 任务

根据一张照片生成一个可折叠（collapsible）的减压玩具（fidget）模型。关于该任务的字段，参见 The Collapsible Fidget task object。

每个任务消耗 6 个积分，且需要付费套餐。

Request

POST

/openapi/creative-lab/fidget-collapsible/v1

curl https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1 \
  -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
要转换为可折叠减压玩具的照片，可以是公开可访问的 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 字段中返回，Meshy 不会将其雕刻到模型上。名称过长会返回 400。

返回值

result 字段保存新任务的 ID。获取该任务或对其进行流式获取，直到 status 变为 SUCCEEDED。然后从 model_urls.stl 下载可打印的 STL 文件。若想先预览模型，可在 model_urls.glb 存在时从中下载 GLB 文件。

失败情形

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
以下情况之一适用：
- 账户没有足够的积分。
- 该 API key、workspace 或成员已达到其积分限额。
- 该账户处于免费套餐。
请检查你的积分和套餐，然后重试。
Name
403 - Forbidden
Description
你的团队开启了 IP Filtering（IP 过滤） 功能，Meshy 将该图片标记为涉及第三方知识产权。请发送你拥有使用权的图片。
Name
429 - Too Many Requests
Description
达到了以下限制之一：
- 你发送的请求数超过了速率限制所允许的数量。请等待几秒后重试。参见速率限制。
- 你排队或正在运行的任务过多。请等待部分任务完成后重试。
- 在没有积分的无限套餐下，你达到了无需积分即可运行的任务数量上限。请等待某个任务完成，或添加积分。
Name
500 - Internal Server Error
Description
Meshy 发生了服务器错误，例如无法对图片执行知识产权检查。Meshy 不会创建该任务，并会退还已扣除的任何积分。请重试该请求。

GET/openapi/creative-lab/fidget-collapsible/v1/:id

获取 Collapsible Fidget 任务

返回一个 Collapsible Fidget 任务。仅返回通过此 endpoint 创建的任务。来自其他 Creative Lab endpoint 或在 Web App 中创建的任务会返回 404。

有关字段说明，请参阅Collapsible Fidget 任务对象。

Request

GET

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}

参数

Name
id
Type
path
Description
创建响应中的任务 ID。

返回值

Collapsible Fidget 任务对象。

失败模式

Name
400 - Bad Request
Description
id 不是有效的任务 ID。请发送创建响应中的 result ID。
Name
403 - Forbidden
Description
您的团队已开启 IP Filtering，且 Meshy 将该任务的图像标记为涉及第三方知识产权。企业版（Enterprise）计划的团队不会遇到此错误。请使用您拥有使用权的图像创建任务。
Name
404 - Not Found
Description
您的账户下没有此 ID 对应的 Collapsible Fidget 任务，或该任务并非通过此 endpoint 创建。请检查该 ID。
Name
500 - Internal Server Error
Description
Meshy 无法运行知识产权检查。请重试该请求。

DELETE/openapi/creative-lab/fidget-collapsible/v1/:id

删除 Collapsible Fidget 任务

取消一个 Collapsible Fidget 任务。取消处于 PENDING 状态的任务会退还其积分。处于 IN_PROGRESS 状态的任务被取消时不会退款，因为已有工作进程开始处理该任务。处于最终状态（SUCCEEDED、FAILED 或 CANCELED）的任务无法取消。

Request

DELETE

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1/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。请发送创建响应中的 result ID。
- 该任务已处于最终状态（SUCCEEDED、FAILED 或 CANCELED），因此无法取消。
Name
404 - Not Found
Description
你的账户下没有此 ID 对应的 Collapsible Fidget 任务，或者该任务并非通过此 endpoint 创建。请检查该 ID。

GET/openapi/creative-lab/fidget-collapsible/v1/:id/stream

流式获取可折叠玩具任务

以服务器发送事件（SSE）的形式流式获取可折叠玩具任务的更新。如果任务不存在，或者不是通过此 endpoint 创建的，流会发送一个 status_code: 404 的 error 事件，然后关闭。

Request

GET

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example (task not found, or not created through this endpoint)
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": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}

参数

Name
id
Type
path
Description
创建响应中返回的任务 ID。

返回值

一个可折叠玩具任务对象的流。每个事件都包含完整的任务对象,与获取可折叠玩具任务返回的内容一致。当任务处于 PENDING 或 IN_PROGRESS 状态时,其输出字段仍为空(null、[] 或 {}),且 finished_at 为 null。

如果 IP 过滤阻止了任务结果的返回,流会在该位置发送一个 error 事件,其中的 status_code 与通过 get 请求会返回的状态码相同。

GET/openapi/creative-lab/fidget-collapsible/v1

获取 Collapsible Fidget 任务列表

分页返回你的 Collapsible Fidget 任务。仅包含通过此 endpoint 创建的任务。

Request

GET

/openapi/creative-lab/fidget-collapsible/v1

curl https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-fidget-collapsible",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729123456000,
    "started_at": 1729123460000,
    "finished_at": 1729123512000,
    "expires_at": 1729382712000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
    }
  }
]

查询参数

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：最旧的排在最前

返回值

一个 Collapsible Fidget 任务对象数组。

可折叠指尖陀螺（Collapsible Fidget）任务对象

Collapsible Fidget 任务会将一张照片转换为可直接打印、无需组装的可折叠指尖玩具模型。这是一个单阶段任务，因此没有可衔接的原型（prototype）任务。响应中不包含 Meshy 在生成过程中制作的轮廓（silhouette）。

属性

Example Collapsible Fidget Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}

Name
id
Type
string
Description
任务 ID。请不要依赖其格式。
Name
type
Type
string
Description
任务类型，始终为 creative-lab-fidget-collapsible。
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 结果的 Enterprise 账户，该时间约为之后 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
任务扣除的积分数量（扣除任何退款后）。返回错误的请求不会被扣费。失败的任务为 0，因为 Meshy 会退还费用。取消操作仅在任务处于 PENDING 状态时才会退款。如果 Meshy 无法读取扣费信息，get 或 stream 响应会省略该字段，而 list 请求会返回 500。遇到这种情况，请重试该请求。
Name
model_urls
Type
object
Description
3D 模型的下载链接，在任务成功之前为空。成功的任务始终包含 stl，仅当 Meshy 渲染了预览时才包含 glb。
- Name
  stl
  Type
  string
  Description
  STL 文件的下载链接，即用于打印的文件。你可以直接在 slicer 中打开它。
- Name
  glb
  Type
  string
  Description
  用于在 3D 查看器中预览模型的 GLB 文件下载链接。其颜色仅用于预览。STL 文件没有颜色，因此打印出的指尖玩具的颜色由耗材决定。
  如果 Meshy 无法渲染预览，model_urls 中就不会有 glb 键，因此在读取之前请先检查该键是否存在。SUCCEEDED 状态的任务始终包含 stl。