lowpoly は 2026/10/30 に廃止されます。 リクエストエラーを避けるため、これらの日付までにモデルを切り替えてください。

プリント可能性を分析 API

3Dモデルのプリント可能性 ― 水密性、体積、穴、非多様体の辺、縮退面 ― を分析します。オプションで、プリント予定のサイズにおける肉厚もチェックできます。

POST/openapi/v1/print/analyze

プリント可能性分析タスクを作成する

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

このタスクはバックグラウンドで実行されます。通常の所要時間については、処理時間を参照してください。

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

実際にプリントする予定のサイズで肉厚も確認したい場合は、printer_type、プリントサイズ、またはその両方を送信してください。結果はprintability.thin_wallsに返されます。肉厚の確認には時間がかかるため、以前にモデルが分析済みであっても、タスクは通常すぐにはレディ状態になりません。

パラメータ

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は拡張子チェックを回避します）。

    Meshyのダウンロード URL（assets.meshy.ai/…?Expires=…&Signature=…）は署名付きであり、タスクのexpires_atを過ぎると機能しなくなります。タスクを再度取得しても、これらは更新されません。Meshyで生成されたモデルの場合は、代わりにinput_task_idを渡してください。これは元のタスクが保持されている間は機能します（アセット保持期間を参照）。それ以降もモデルを再利用するには、expires_atより前にダウンロードし、自分自身のコピーを送信してください。

2つのプリントサイズフィールドのうち、送信できるのは最大1つです。サイズを指定せずにprinter_typeを送信した場合、デフォルトのサイズは以下のとおりです。

  • .glbおよび任意のinput_task_id：高さ150 mm。
  • .stl：ファイル自身の最長辺を、ミリメートルとして読み取った値。他の単位のSTLの場合は、intended_print_longest_side_mmを送信してください。
  • .obj、.fbx、.gltf：最長辺150 mm。
  • Name
    printer_type
    Type
    string
    Description

    使用予定のプリンターです。これにより、肉厚チェックの最小肉厚が設定されます。サイズを指定せずに送信した場合、デフォルトはfdmになります。

    利用可能な値：

    • fdm：フィラメント方式、最小肉厚1.0 mm。
    • sla：レジン方式、最小肉厚0.8 mm。
    • full_color：フルカラー方式、最小肉厚2.0 mm。
  • Name
    intended_print_height_mm
    Type
    number
    Description

    プリントの高さ（ミリメートル単位）。範囲：[1, 1000]。最も近いミリメートルに丸められます。GLB入力のみ対応。

  • Name
    intended_print_longest_side_mm
    Type
    number
    Description

    プリントの最長辺の長さ（ミリメートル単位）。範囲：[1, 1000]。最も近いミリメートルに丸められます。すべての入力形式で使用可能です。

返り値

レスポンスのresultプロパティには、新しく作成されたプリント可能性分析タスクのidが含まれます。

失敗モード

  • Name
    400 - Bad Request
    Description

    リクエストが受理できませんでした。よくある原因：

    • パラメータ不足：input_task_idとmodel_urlのどちらも指定されていません。
    • 無効なUUID：input_task_idが有効なUUIDではありません。
    • 無効なモデルURL：model_urlの形式が不正、サポートされていないスキームを使用している、またはサポートされていないファイル拡張子です。
    • モデルファイルが大きすぎる：model_urlの本体が100 MBを超えています。
    • モデルファイルをダウンロードできなかった：model_urlがエラーを返しました。最も多い原因は、署名付きMeshyダウンロードURLの期限切れです。タスクを再取得しても同じ有効期限の同じURLが返されるため、自分自身のファイルのコピーを送信するか、元のタスクがまだ保持されている間はinput_task_idを使用してください。
    • タスクが成功していない：参照先のタスクがまだ保留中、処理中、または失敗しています。
    • 無効なプリントサイズ：intended_print_height_mmまたはintended_print_longest_side_mmが[1, 1000]の範囲外、または両方が送信されました。
    • 不明なプリンタータイプ：printer_typeがfdm、sla、full_colorのいずれでもありません。
    • GLB以外のモデルに対する高さ指定：.glbではないmodel_urlに対してintended_print_height_mmが送信されました。代わりにintended_print_longest_side_mmを使用してください。
    • このモデルを高さでサイズ指定できない：指定された高さ（またはデフォルトの150 mm）では、モデルの最長辺が[1, 1000] mmの範囲外になる、モデルが平坦である、またはサイズを特定できません。代わりにintended_print_longest_side_mmを使用してください。.glbのmodel_urlおよび一部のinput_task_idタスクでは、これはタスクの開始後にのみ判明し、タスクはFAILEDで終了します。
    • STLのサイズが使用不可：サイズを指定せずにprinter_typeが送信され、.stl自身の最長辺が読み取れない、または[1, 1000] mmの範囲外です。intended_print_longest_side_mmを送信してください。
  • 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"
  }'

# Also check wall thickness for a 100 mm tall SLA print
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",
    "printer_type": "sla",
    "intended_print_height_mm": 100
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}
GET/openapi/v1/print/analyze/:id

Retrieve an Analyze Printability Task

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

Parameters

  • Name
    id
    Type
    path
    Description

    取得するプリント可能性分析タスクのID。

Returns

Analyze Printability Task Object。printability フィールドは、タスクが SUCCEEDED に達するまでは null です。肉厚のチェックが行われた場合、printability には intended_print と thin_walls も含まれます。

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
}

Response (wall thickness checked)

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000012000,
  "expires_at": 1715725412000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "error",
    "issue_count": 2,
    "error_count": 1,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "intended_print": {
      "printer_type": "sla",
      "height_mm": 100,
      "longest_side_mm": 118,
      "wall_thickness_mm": 0.8,
      "dimensions_mm": [118, 72.41, 99.87]
    },
    "thin_walls": {
      "thin_area_ratio": 0.083,
      "has_thin_walls": true,
      "status": "error"
    },
    "evaluated_at": 1700000012000
  },
  "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

    タスクの進行状況です。タスクがまだ開始されていない場合、このプロパティは 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: モデルを分析できませんでした。

      肉厚のチェックが行われた場合、これは上記のチェックと thin_walls.status のうち、より悪い方の値になります。悪い順から良い順に error、warning、unknown、healthy となります。

    • Name
      issue_count
      Type
      integer
      Description

      問題の総数で、error_count + warning_count と等しくなります。

    • Name
      error_count
      Type
      integer
      Description

      エラーレベルの問題の数です。モデルが水密（watertight）ではない場合、体積が非正の場合、または非多様体の辺がある場合にエラーが発生します。肉厚のチェックが行われた場合、薄すぎる壁（thin_walls.status が error）があると、さらにもう1つエラーとしてカウントされます。

    • 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
      intended_print
      Type
      object
      Description

      肉厚チェックで使用されたプリンターとサイズです。肉厚がチェックされた場合にのみ存在します。

      • Name
        printer_type
        Type
        string
        Description

        fdm、sla、または full_color です。

      • Name
        height_mm
        Type
        number
        Description

        プリントが高さでサイズ指定された場合の、プリントの高さ（ミリメートル）です。それ以外の場合は null です。

      • Name
        longest_side_mm
        Type
        number
        Description

        プリントの最長辺（ミリメートル）です。高さでサイズ指定された場合、これはモデルのプロポーションから計算されます。

      • Name
        wall_thickness_mm
        Type
        number
        Description

        printer_type に対する最小肉厚（ミリメートル）です。これより薄い壁は薄すぎると報告されます。

      • Name
        dimensions_mm
        Type
        array
        Description

        プリントの [幅, 奥行き, 高さ]（ミリメートル）です。高さは height_mm と1ミリメートル未満の端数分だけ異なる場合があります。GLB以外の入力の場合、またはモデルのサイズを判定できない場合は null です。

    • Name
      thin_walls
      Type
      object
      Description

      肉厚チェックの結果です。肉厚がチェックされた場合にのみ存在します。

      • Name
        thin_area_ratio
        Type
        number
        Description

        intended_print.wall_thickness_mm より薄い表面の割合（0 から 1）です。モデルを計測できなかった場合は null です。

      • Name
        has_thin_walls
        Type
        boolean
        Description

        表面のいずれかの部分が薄すぎる場合に true になります。鋭い角だけでもこれが設定されることがあるため、壁を厚くする必要があるかどうかは status を使って判断してください。モデルを計測できなかった場合は null です。

      • Name
        status
        Type
        string
        Description

        肉厚の判定結果です。以下のいずれかになります。

        • healthy: 表面の5%以下が薄すぎる状態です。
        • error: 表面の5%を超える部分が薄すぎる状態です。壁を厚くするには、このタスクの id を input_task_id としてプリント可能性を修復に渡してください（.stl、.fbx、または .gltf の model_url の場合は、代わりにファイルを model_url として送信してください）。
        • unknown: モデルを計測できませんでした。肉厚チェック自体が失敗した場合、タスクは FAILED で終了します。
    • 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
}

The Analyze Printability Task Object (wall thickness checked)

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000012000,
  "expires_at": 1715725412000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "error",
    "issue_count": 2,
    "error_count": 1,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "intended_print": {
      "printer_type": "sla",
      "height_mm": 100,
      "longest_side_mm": 118,
      "wall_thickness_mm": 0.8,
      "dimensions_mm": [118, 72.41, 99.87]
    },
    "thin_walls": {
      "thin_area_ratio": 0.083,
      "has_thin_walls": true,
      "status": "error"
    },
    "evaluated_at": 1700000012000
  },
  "consumed_credits": 0
}