多色打印 API

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

POST/openapi/v1/print/multi-color

创建多色 3D 打印任务

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

参数

必需属性

可选属性

  • Name
    max_colors
    Type
    integer
    Description

    输出调色板中的最大颜色数量。

    有效范围：1 到 16。

    未指定时默认为 4。

  • Name
    max_depth
    Type
    integer
    Description

    四叉树深度，用于颜色精度。较高的值会产生更精细的颜色边界，但会增加文件大小。

    有效范围：3 到 6。

    未指定时默认为 4。

返回值

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

失败模式

  • Name
    400 - Bad Request
    Description

    请求不合法。常见原因：

    • 缺少参数：必须提供 input_task_id。
    • 无效输入任务：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
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
}

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。

    • Name
      message
      Type
      string
      Description

      描述出错原因的错误消息。

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
}