多色打印 API

将 3D 模型转换为多色 3MF 格式用于 3D 打印，支持最多 16 种颜色的可配置调色板。

POST/openapi/v1/print/multi-color

创建多色 3D 打印任务

此端点创建一个新的多色 3D 打印任务。该任务将 3D 模型转换为适合 3D 打印的多色 3MF 文件。

参数

只需提供 input_task_id 或 model_url 其中之一（必选）。如果两者都提供，input_task_id 优先。

Name
input_task_id
Type
string
必选
Description
用作输入的已成功任务的 ID。支持的任务类型：图像生成3D、多图像生成3D、文本生成3D、重建网格和重新贴图。该任务必须具有 SUCCEEDED 状态。

Name
model_url
Type
string
必选
Description
3D 模型的可公开访问 URL 或 Data URI。目前支持 .glb 和 .fbx 格式。

Name
max_colors
Type
integer
默认值 4
Description
输出调色板中的最大颜色数量。
有效范围：1 到 16。
Name
max_depth
Type
integer
默认值 4
Description
四叉树深度，用于颜色精度。较高的值会产生更精细的颜色边界，但会增加文件大小。
有效范围：3 到 6。

返回值

响应的 result 属性包含新创建的 3D 打印任务的 id。

失败模式

Name
400 - Bad Request
Description
请求不合法。常见原因：
- 缺少参数：必须提供 input_task_id 或 model_url 其中之一。
- 无效模型格式：model_url 指向的文件扩展名不支持（仅支持 .glb 和 .fbx）。
- URL 无法访问：model_url 无法下载。
- 无效输入任务：input_task_id 必须引用一个已成功的任务。
- 无效 max_colors：值必须在 1 到 16 之间。
- 无效 max_depth：值必须在 3 到 6 之间。
Name
401 - Unauthorized
Description
认证失败。请检查您的 API 密钥。
Name
402 - Payment Required
Description
积分不足，无法执行此任务。
Name
429 - Too Many Requests
Description
您已超出速率限制。

Request

POST

/openapi/v1/print/multi-color

# 将 3D 模型转换为多色 3MF 用于打印
curl https://api.meshy.ai/openapi/v1/print/multi-color \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "max_colors": 8,
    "max_depth": 5
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

GET/openapi/v1/print/multi-color/:id

检索多色 3D 打印任务

此端点通过 ID 检索多色 3D 打印任务。

参数

Name
id
Type
path
Description
要检索的 3D 打印任务的 ID。

返回值

3D 打印任务对象。

Request

GET

/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl https://api.meshy.ai/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-multi-color",
  "model_urls": {
      "3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
},
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}

DELETE/openapi/v1/print/multi-color/:id

删除多色 3D 打印任务

此端点将永久删除一个多色 3D 打印任务，包括所有相关的模型和数据。此操作不可逆。

路径参数

Name
id
Type
path
Description
要删除的多色 3D 打印任务的 ID。

返回值

成功则返回 200 OK。

请求

DELETE

/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

响应

// 成功则返回 200 Ok。

GET/openapi/v1/print/multi-color

多色 3D 打印任务列表

此端点允许您获取多色 3D 打印任务的列表。

参数

可选属性

Name
page_num
Type
integer
Description
分页的页码。起始值和默认值为 1。
Name
page_size
Type
integer
Description
每页返回的任务数量。默认为 10，最大允许为 50。
Name
sort_by
Type
string
Description
排序字段。可选值：
- +created_at：按创建时间升序排序。
- -created_at：按创建时间降序排序。

返回值

返回分页的 3D 打印任务对象列表。

请求

GET

/openapi/v1/print/multi-color

curl https://api.meshy.ai/openapi/v1/print/multi-color?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

响应

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-multi-color",
    "model_urls": {
      "3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null,
  "consumed_credits": 10
  }
]

GET/openapi/v1/print/multi-color/:id/stream

流式多色 3D 打印任务

此端点通过 Server-Sent Events (SSE) 流式返回多色 3D 打印任务的实时进度更新。

参数

Name
id
Type
path
Description
要流式获取的多色 3D 打印任务的唯一标识符。

返回值

返回 3D 打印任务对象的流式 Server-Sent Events。

对于 PENDING 或 IN_PROGRESS 状态的任务，响应流仅包含必要的 progress 和 status 字段。

请求

GET

/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream

curl -N https://api.meshy.ai/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

响应流

// 错误事件示例
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// 消息事件示例展示任务进度。
// 对于 PENDING 或 IN_PROGRESS 状态的任务，响应流不会包含所有字段。
event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "type": "print-multi-color",
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.3mf?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}

3D 打印任务对象

Name
id
Type
string
Description
任务的唯一标识符。虽然我们使用 k-sortable UUID 作为任务 ID 的实现细节，但您不应对 ID 的格式做任何假设。
Name
type
Type
string
Description
3D 打印任务的类型。值为 print-multi-color。
Name
model_urls
Type
object
Description
Meshy 生成的可下载 3D 模型文件的 URL。如果未生成某种格式，该格式的属性将被省略而不是返回空字符串。
- Name
  3mf
  Type
  string
  Description
  多色 3MF 文件的可下载 URL。
Name
progress
Type
integer
Description
任务的进度。如果任务尚未开始，此属性将为 0。一旦任务成功，这将变为 100。
Name
status
Type
string
Description
任务的状态。可能的值是 PENDING、IN_PROGRESS、SUCCEEDED、FAILED 之一。
Name
preceding_tasks
Type
integer
Description
前置任务的数量。
仅当任务状态为 PENDING 时，此字段的值才有意义。
Name
created_at
Type
timestamp
Description
任务创建时间的时间戳，以毫秒为单位。
Name
started_at
Type
timestamp
Description
任务开始时间的时间戳，以毫秒为单位。如果任务尚未开始，此属性将为 0。
Name
finished_at
Type
timestamp
Description
任务完成时间的时间戳，以毫秒为单位。如果任务尚未完成，此属性将为 0。
Name
task_error
Type
object
Description
如果任务失败，此属性包含错误信息。如果任务未失败，此属性为 null。详情请参阅 Errors。
- Name
  message
  Type
  string
  Description
  描述出错原因的错误消息。
- Name
  consumed_credits
  Type
  integer
  Description
  该任务消耗的积分数。当任务状态为 PENDING、IN_PROGRESS 或 SUCCEEDED 时返回。对于 FAILED 任务返回 0（失败时积分会被退还）。

3D 打印任务对象

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-multi-color",
  "model_urls": {
      "3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
},
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}