プリント適性解析 API

3DモデルのFDMプリント適性（水密性、体積、穴、非多様体エッジ、縮退面）を解析します。

POST/openapi/v1/print/analyze

印刷適性解析タスクを作成

このendpointは、新しい印刷適性解析タスクを作成します。このタスクは3Dモデルを評価し、その印刷適性メトリクスを報告します。

入力タスクにキャッシュ済みの印刷適性情報がすでにある場合、返されるタスクはすぐに準備完了となり、最初の GET でワーカーを経由せずに解析結果が返されます。

パラメータ

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

Name
input_task_id
Type
string
必須
Description
あなたが所有する成功済みタスクのIDです。対応しているタスクタイプ: 画像から3D、複数画像から3D、テキストから3D、リメッシュ、および再テクスチャ。タスクはMeshy 6（または任意のPreviewモデル）を使用している必要があり、ステータスは SUCCEEDED である必要があります。

Name
model_url
Type
string
必須
Description
解析する3DモデルのURLです。対応形式: .glb、.gltf、.obj、.fbx、.stl。最大ファイルサイズ: 100 MB。http、https、または data: URLを使用する必要があります（data URLは拡張子チェックをバイパスします）。

戻り値

レスポンスの result プロパティには、新しく作成された印刷適性解析タスクの id が含まれます。

失敗モード

Name
400 - Bad Request
Description
リクエストは受け入れられませんでした。一般的な原因:
- パラメータ不足: input_task_id と model_url のどちらも指定されていません。
- 無効なUUID: input_task_id が有効なUUIDではありません。
- 無効なモデルURL: model_url の形式が不正、未対応のスキームを使用している、または未対応のファイル拡張子です。
- モデルファイルが大きすぎる: model_url の本文が100 MBを超えています。
- タスクが成功していない: 参照されたタスクがまだ保留中、進行中、または失敗しています。
Name
401 - Unauthorized
Description
認証に失敗しました。API keyを確認してください。
Name
403 - Forbidden
Description
タスクは存在しますが、別のユーザーが所有しています。
Name
404 - Not Found
Description
一般的な原因:
- タスクが存在しない、または削除されています。
- タスクがMeshy 6より古いモデルを使用している、またはそのモードが3Dアセットを生成しません。
- 基盤となるモデルファイルがストレージで利用できなくなっています。
Name
429 - Too Many Requests
Description
保留中タスクのクォータまたはレート制限を超過しています。

Request

POST

/openapi/v1/print/analyze

# Analyze an existing task
curl https://api.meshy.ai/openapi/v1/print/analyze \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
  }'

# Or analyze a model URL directly
curl https://api.meshy.ai/openapi/v1/print/analyze \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "model_url": "https://example.com/model.glb"
  }'

Response

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

GET/openapi/v1/print/analyze/:id

印刷可能性分析タスクを取得

この endpoint は、ID によって analyze-printability タスクを取得します。

パラメータ

Name
id
Type
path
Description
取得する analyze-printability タスクの ID。

戻り値

Analyze Printability Task Object。printability フィールドは、タスクが SUCCEEDED に達するまで null です。

Request

GET

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

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "expires_at": 1715725401000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "warning",
    "issue_count": 1,
    "error_count": 0,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "evaluated_at": 1700000001000
  },
  "consumed_credits": 0
}

DELETE/openapi/v1/print/analyze/:id

Analyze Printability タスクを削除

この endpoint は、analyze-printability タスクとそのキャッシュ済み結果を完全に削除します。この操作は取り消せません。

パスパラメータ

Name
id
Type
path
Description
削除する analyze-printability タスクの ID。

戻り値

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

Request

DELETE

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

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

Response

// Returns 200 Ok on success.

GET/openapi/v1/print/analyze

印刷可能性解析タスクを一覧表示

この endpoint では、印刷可能性解析タスクの一覧を取得できます。

パラメータ

任意属性

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: 作成時刻の降順でソートします。

戻り値

印刷可能性解析タスクオブジェクトのページ分割された一覧を返します。

Request

GET

/openapi/v1/print/analyze

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-analyze",
    "status": "SUCCEEDED",
    "progress": 100,
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "expires_at": 1715725401000,
    "task_error": null,
    "printability": {
      "_version": "v1",
      "status": "warning",
      "issue_count": 1,
      "error_count": 0,
      "warning_count": 1,
      "metrics": {
        "is_watertight": true,
        "volume": 1.316167354292668,
        "non_manifold_edges": 0,
        "degenerate_faces": 43242,
        "holes": 0
      },
      "evaluated_at": 1700000001000
    },
    "consumed_credits": 0
  }
]

GET/openapi/v1/print/analyze/:id/stream

印刷適性分析タスクをストリーミングする

この endpoint は、Server-Sent Events (SSE) を使用して印刷適性分析タスクのリアルタイム更新をストリーミングします。

パラメータ

Name
id
Type
path
Description
ストリーミングする印刷適性分析タスクの一意の識別子。

戻り値

Server-Sent Events として印刷適性分析タスクオブジェクトのストリームを返します。

PENDING または IN_PROGRESS のタスクの場合、レスポンスストリームには必要な progress と status フィールドのみが含まれます。printability ブロックは、タスクが SUCCEEDED に達した後にのみ送信されます。

Request

GET

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

curl -N https://api.meshy.ai/openapi/v1/print/analyze/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-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "expires_at": 1715725401000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "warning",
    "issue_count": 1,
    "error_count": 0,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "evaluated_at": 1700000001000
  },
  "consumed_credits": 0
}

印刷可能性分析タスクオブジェクト

Name
id
Type
string
Description
タスクの一意の識別子。実装の詳細として、タスク ID には k ソート可能な UUID を使用していますが、 id の形式については、いかなる仮定も行わないでください。
Name
type
Type
string
Description
analyze-printability タスクのタイプ。値は print-analyze です。
Name
status
Type
string
Description
タスクのステータス。使用可能な値は PENDING、IN_PROGRESS、SUCCEEDED、FAILED、CANCELED のいずれかです。
Name
progress
Type
integer
Description
タスクの進行状況。タスクがまだ開始されていない場合、このプロパティは 0 になります。タスクが成功すると、これは 100 になります。
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
expires_at
Type
timestamp
Description
タスク結果がシステムから期限切れになる時刻のタイムスタンプ（ミリ秒）。タスクがまだ完了していない場合は 0 です。
Name
task_error
Type
object
Description
タスクが失敗した場合のエラー情報。タスクが失敗していない場合、このプロパティは null です。詳細については、エラーを参照してください。
- Name
  message
  Type
  string
  Description
  何が問題だったかを説明するエラーメッセージ。
Name
printability
Type
object
Description
印刷可能性の評価結果。タスクが SUCCEEDED に達するまでは null です。
- Name
  _version
  Type
  string
  Description
  印刷可能性結果のスキーマバージョン。現在は v1 です。
- Name
  status
  Type
  string
  Description
  全体のステータス。次のいずれかです。
  
  healthy: エラーも警告もありません。
  
  warning: 少なくとも 1 つの警告があり、エラーはありません。
  
  error: 少なくとも 1 つのエラーがあります。
  
  unknown: モデルを分析できませんでした。
- Name
  issue_count
  Type
  integer
  Description
  問題の総数。error_count + warning_count と等しい値です。
- Name
  error_count
  Type
  integer
  Description
  エラーレベルの問題の数。モデルが 水密でない、正の体積を持たない、または 非多様体エッジ を持つ場合にエラーが発生します。
- Name
  warning_count
  Type
  integer
  Description
  警告レベルの問題の数。モデルに 縮退面 または穴が含まれる場合に警告が発生します。
- Name
  metrics
  Type
  object
  Description
  評価器によって返される生のジオメトリ指標。
  Name
  is_watertight
  Type
  boolean
  Description
  メッシュに境界エッジがない（つまり閉じている）場合は true です。
  Name
  volume
  Type
  number
  Description
  モデルの体積（立方メートル）。
  Name
  non_manifold_edges
  Type
  integer
  Description
  非多様体エッジの数。
  Name
  degenerate_faces
  Type
  integer
  Description
  縮退面（面積がゼロまたは無効な面）の数。
  Name
  holes
  Type
  integer
  Description
  メッシュ内の穴（境界ループ）の数。
- Name
  evaluated_at
  Type
  timestamp
  Description
  分析が計算された時刻のタイムスタンプ（エポックからのミリ秒）。
Name
consumed_credits
Type
integer
Description
常に 0 です。この endpoint は無料です。

The Analyze Printability Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "expires_at": 1715725401000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "warning",
    "issue_count": 1,
    "error_count": 0,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "evaluated_at": 1700000001000
  },
  "consumed_credits": 0
}