多色プリント API

3Dモデルを、3Dプリント向けの多色3MF形式に変換します。最大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
style
Type
string
デフォルト realistic
Description
生成される3MFファイルの視覚的なカラースタイルです。
利用可能な値：
- realistic：モデルのテクスチャから直接色をサンプリングし、フォトリアリスティックで精細なディテールを実現します。ファイルサイズは大きくなります。
- cartoon：色を均一な領域にフラット化し、スタイライズされた見た目にします。ファイルサイズは小さくなります。
入力には色情報が含まれている必要があります：realistic では、すべてのメッシュパーツにUV座標を持つ単一のベースカラーテクスチャが必要です。cartoon では、頂点カラーも受け付けられます。テクスチャのない（白色の）モデルは拒否されます — model_missing_texture を参照してください。

返り値

レスポンスの 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の間である必要があります。
- 無効な style：値は realistic または cartoon である必要があります。
- カラーソースなし：入力モデルにベースカラーテクスチャがなく（realistic の場合、すべてのメッシュパーツにUV付きの単一テクスチャが必要）、頂点カラーもありません（cartoon はいずれも受け付けます）。まずモデルにテクスチャを適用するか、頂点カラー付きモデルには cartoon を使用してください。.fbx のアップロードは、タスクが正規化した後にチェックされ、代わりに model_missing_texture で失敗します。
Name
401 - Unauthorized
Description
認証に失敗しました。APIキーを確認してください。
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
  }'

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。

タスクステータス

まだ PENDING 状態のタスクは削除され、作成時に消費されたクレジットが払い戻されます。

すでに IN_PROGRESS のタスクは削除できません。リクエストは 409 Conflict で拒否され、タスクは実行され続けます。ワーカーがすでに処理を開始したタスクのクレジットは払い戻し対象外のため、実行中に削除するとクレジットと結果の両方を失うことになります。SUCCEEDED、FAILED、または CANCELED になるまで待ってから削除してください。

終端状態（SUCCEEDED、FAILED、または CANCELED）にあるタスクは、払い戻しなしで削除されます。

返り値

成功時には 200 OK を返し、タスクが IN_PROGRESS の場合は 409 Conflict を返します。

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

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS — the task is left running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

GET/openapi/v1/print/multi-color

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

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

パラメータ

任意の属性

Name
page_num
Type
integer
Description
ページネーション用のページ番号。1 から始まり、デフォルトも 1 です。
Name
page_size
Type
integer
Description
ページサイズの上限。デフォルトは 10 件です。最大で 100 件まで指定できます。
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プリントタスクをストリーミングする

このエンドポイントは、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 Print タスクオブジェクト

Name
id
Type
string
Description
タスクの一意の識別子です。実装の詳細としてタスク ID には k-sortable な UUID を使用していますが、id のフォーマットについて何らかの前提を置くべきではありません。
Name
type
Type
string
Description
3D Print タスクのタイプです。値は print-multi-color です。
Name
model_urls
Type
object
Description
Meshy によって生成された 3D モデルファイルへのダウンロード可能な URL です。あるフォーマットが生成されなかった場合、そのフォーマットのプロパティは空文字列を返す代わりに省略されます。
- Name
  3mf
  Type
  string
  Description
  マルチカラーの3MF ファイルへのダウンロード可能な URL です。
Name
progress
Type
integer
Description
タスクの progress です。タスクがまだ開始されていない場合、このプロパティは 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
}