プリント可能性を分析 API

3Dモデルの FDM プリント可能性 — 水密性、体積、穴、非多様体の辺、縮退面を分析します。

POST/openapi/v1/print/analyze

Create an Analyze Printability Task

このエンドポイントは、新しいプリント可能性を分析タスクを作成します。このタスクは3Dモデルを評価し、そのプリント可能性の指標を報告します。

入力タスクにすでにキャッシュされたプリント可能性がある場合、返されたタスクは即座に準備完了となり、それに対する最初のGETはワーカーを経由せずに分析結果を返します。

パラメータ

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

  • Name
    model_url
    Type
    string
    必須
    Description

    分析対象の3Dモデルの URLです。サポートされている形式：.glb、.gltf、.obj、.fbx、.stl。最大ファイルサイズ：100 MB。http、https、またはdata: URLを使用する必要があります（データ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キーを確認してください。

  • Name
    403 - Forbidden
    Description

    タスクは存在しますが、別のユーザーが所有しています。

  • Name
    404 - Not Found
    Description

    よくある原因：

    • タスクが存在しない、または削除されています。
    • タスクがMeshy 6より古いモデルを使用している、またはそのmodeが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

プリント可能性を分析タスクを取得

このエンドポイントは、IDを指定してプリント可能性を分析タスクを取得します。

パラメータ

  • Name
    id
    Type
    path
    Description

    取得するプリント可能性を分析タスクの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

プリント可能性を分析タスクを削除

このエンドポイントは、プリント可能性を分析タスクとそのキャッシュされた結果を完全に削除します。この操作は取り消せません。

パスパラメータ

  • Name
    id
    Type
    path
    Description

    削除するプリント可能性を分析タスクのID。

タスクステータス

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

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

最終状態（SUCCEEDED、FAILED、CANCELED）にあるタスクは、 返金なしで削除されます。

戻り値

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

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

// 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/analyze

プリント可能性を分析タスクのリスト取得

このエンドポイントを使用すると、プリント可能性を分析タスクのリストを取得できます。

パラメータ

オプション属性

  • 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: 作成時刻の降順で並び替えます。

戻り値

ページネーションされた プリント可能性を分析タスクオブジェクト のリストを返します。

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

プリント可能性を分析タスクをストリーム

このエンドポイントは、Server-Sent Events (SSE) を使用してプリント可能性を分析タスクのリアルタイムの更新をストリームします。

パラメータ

  • Name
    id
    Type
    path
    Description

    ストリームするプリント可能性を分析タスクの一意の識別子です。

戻り値

プリント可能性を分析タスクオブジェクトのストリームを Server-Sent Events として返します。

各フレームには、そのステージにおける完全なタスクオブジェクトが含まれます — これは Get エンドポイントが返すものと同じ形式です — そのため、タスクが PENDING または IN_PROGRESS の間は、 出力フィールドはまだ入力されておらず（null、[] または {}）、 finished_at は null です。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.
// Every frame is the full task object; fields not yet populated are null / empty.
// The PENDING frame below is abbreviated to the fields that change.
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-sortableなUUIDを使用していますが、このidのフォーマットについて何らかの前提を置くべきではありません。

  • Name
    type
    Type
    string
    Description

    プリント可能性を分析タスクのタイプです。値はprint-analyzeです。

  • Name
    status
    Type
    string
    Description

    タスクのステータスです。可能な値はPENDING、IN_PROGRESS、SUCCEEDED、FAILED、CANCELEDのいずれかです。

  • Name
    progress
    Type
    integer
    Description

    タスクのprogressです。タスクがまだ開始されていない場合、このプロパティは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です。このエンドポイントは無料です。

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
}