マルチカラー印刷 API

最大16色まで設定可能なカラーパレットを使用して、3Dモデルを3Dプリント用のマルチカラー3MF形式に変換します。

POST/openapi/v1/print/multi-color

マルチカラー 3D プリントタスクを作成

この endpoint は新しいマルチカラー 3D プリントタスクを作成します。このタスクは、3D モデルを 3D プリントに適したマルチカラー 3MF ファイルに変換します。

パラメータ

input_task_id または model_url のいずれか一方のみが 必須 です。両方が指定された場合、input_task_id が優先されます。

  • Name
    input_task_id
    Type
    string
    必須
    Description

    入力として使用する、成功したタスクの ID。対応しているタスクタイプ: Image to 3D、Multi-Image to 3D、Text to 3D、Remesh、および Retexture。タスクのステータスは 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

    リクエストは受け付けられませんでした。一般的な原因:

    • パラメータ不足: model_url または input_task_id のいずれかを指定する必要があります。
    • 無効なモデル形式: model_url が未対応の拡張子のファイルを指しています（.glb と .fbx のみ対応しています）。
    • 到達不能な URL: model_url をダウンロードできませんでした。
    • 無効な入力タスク: input_task_id は成功したタスクを参照している必要があります。
    • 無効な max_colors: 値は 1 から 16 の間である必要があります。
    • 無効な max_depth: 値は 3 から 6 の間である必要があります。
  • Name
    401 - Unauthorized
    Description

    認証に失敗しました。API key を確認してください。

  • Name
    402 - Payment Required
    Description

    このタスクを実行するにはクレジットが不足しています。

  • Name
    429 - Too Many Requests
    Description

    レート制限を超過しました。

Request

POST
/openapi/v1/print/multi-color
# Convert a 3D model to multi-color 3MF for printing
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プリントタスクを取得

このendpointは、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プリントタスクを削除

このendpointは、関連するすべてのモデルとデータを含むマルチカラー3Dプリントタスクを完全に削除します。この操作は元に戻せません。

パスパラメータ

  • Name
    id
    Type
    path
    Description

    削除するマルチカラー3DプリントタスクのID。

戻り値

成功時に 200 OK を返します。

Request

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

Response

// Returns 200 Ok on success.
GET/openapi/v1/print/multi-color

マルチカラー3Dプリントタスクの一覧取得

このendpointを使用すると、マルチカラー3Dプリントタスクの一覧を取得できます。

パラメータ

任意属性

  • Name
    page_num
    Type
    integer
    Description

    ページネーションのページ番号。1から始まり、デフォルトは1です。

  • Name
    page_size
    Type
    integer
    Description

    ページサイズの上限。デフォルトは10件です。許可される最大値は50件です。

  • Name
    sort_by
    Type
    string
    Description

    ソートに使用するフィールド。利用可能な値:

    • +created_at: 作成日時の昇順でソートします。
    • -created_at: 作成日時の降順でソートします。

戻り値

3Dプリントタスクオブジェクトのページネーションされた一覧を返します。

Request

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

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",
    "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プリントタスクをストリーミングする

このendpointは、Server-Sent Events（SSE）を使用して、マルチカラー3Dプリントタスクのリアルタイム更新をストリーミングします。

パラメータ

  • Name
    id
    Type
    path
    Description

    ストリーミングするマルチカラー3Dプリントタスクの一意の識別子。

戻り値

Server-Sent Eventsとして、3Dプリントタスクオブジェクトのストリームを返します。

PENDINGまたはIN_PROGRESSのタスクの場合、レスポンスストリームには必要なprogressおよびstatusフィールドのみが含まれます。

Request

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

Response Stream

// Error event example
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": "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

    タスクの一意の識別子。実装の詳細として、タスクIDにはkソート可能なUUIDを使用していますが、 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

    失敗したタスクのエラー詳細。完全なtask_errorオブジェクトのリファレンスについては、エラーを参照してください。

  • Name
    consumed_credits
    Type
    integer
    Description

    このタスクによって消費されたクレジット数。タスクのステータスがPENDING、IN_PROGRESS、またはSUCCEEDEDの場合に存在します。FAILEDタスクでは0を返します（失敗時にクレジットは返還されます）。

The 3D Print Task Object

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