プリント可能性を修復 API

3Dモデルを FDM でのプリント可能性のために修復します — 非多様体の辺、縮退面、穴、その他の topology の問題を修正し、メッシュをプリント可能な状態にします。

POST/openapi/v1/print/repair

Create a Repair Printability Task

このエンドポイントは、新しいプリント可能性修復タスクを作成します。このタスクは3Dモデルに対してtopology修復を実行し、水密でプリントに適したバージョンを返します。

出力形式は入力形式と一致します。model_url で .stl を送信した場合、レスポンスの model_urls.stl に修復済みメッシュが格納され、他の形式のフィールドは空になります。input_task_id を指定した場合は常に元タスクのGLBが読み込まれるため、出力は .glb になります。

パラメータ

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

ジオメトリの変更に伴い、修復時に既存のテクスチャは削除されます。テクスチャを再度追加するには、修復後のモデルに対してRetexture APIを使用してください。

  • Name
    model_url
    Type
    string
    必須
    Description

    修復対象の3DモデルのURLです。サポートされる形式: .glb、.gltf、.obj、.fbx、.stl。最大ファイルサイズ: 100 MB。http、https、または data: URL を使用する必要があります（data URLは拡張子チェックを回避します）。

  • Name
    alpha_thumbnail
    Type
    boolean
    デフォルト false
    Description

    true に設定すると、タスクはプレビューの透過背景（RGBA）版も追加でレンダリングし、GETレスポンスで alpha_thumbnail_url として返します。既存の thumbnail_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を超えています。
    • タスクが未成功: 参照先のタスクがまだ保留中、進行中、または失敗しています。
    • GLB不足: 参照先のタスクに修復対象のGLBアセットがありません。
  • Name
    401 - Unauthorized
    Description

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

  • Name
    402 - Payment Required
    Description

    よくある原因:

    • 無料プラン: タスクの作成には有料プランが必要です。サブスクリプションページからアップグレードしてください。
    • クレジット不足: ワークスペースのクレジット上限に達しました。
  • Name
    404 - Not Found
    Description

    参照先のタスクが存在しないか、別のユーザーが所有しています。

  • Name
    429 - Too Many Requests
    Description

    保留中タスクの上限またはレート制限を超過しました。

Request

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

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

Response

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

プリント可能性を修復タスクを取得

このエンドポイントは、IDによってプリント可能性を修復タスクを取得します。

パラメータ

  • Name
    id
    Type
    path
    Description

    取得するプリント可能性を修復タスクのID。

戻り値

プリント可能性を修復タスクオブジェクト。model_urls ブロックは、タスクが SUCCEEDED に達するまで空です。入力形式に一致する model_urls フィールドのみが値を持ちます。

Request

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-repair",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1715725401000,
  "task_error": null,
  "model_urls": {
    "glb": "",
    "gltf": "",
    "fbx": "",
    "obj": "",
    "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "texture_urls": [],
  "consumed_credits": 10
}
DELETE/openapi/v1/print/repair/: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/repair/a43b5c6d-7e8f-901a-234b-567c890d1e2f
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/print/repair/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/repair

プリント可能性を修復タスク一覧の取得

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

パラメーター

オプション属性

  • 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/repair
curl https://api.meshy.ai/openapi/v1/print/repair?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-repair",
    "status": "SUCCEEDED",
    "progress": 100,
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000030000,
    "expires_at": 1715725401000,
    "task_error": null,
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "gltf": "",
      "fbx": "",
      "obj": "",
      "stl": "",
      "usdz": "",
      "3mf": "",
      "mtl": ""
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
    "texture_urls": [],
    "consumed_credits": 10
  }
]
GET/openapi/v1/print/repair/:id/stream

プリント可能性を修復タスクをストリーム

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

パラメータ

  • Name
    id
    Type
    path
    Description

    ストリーミング対象のプリント可能性を修復タスクの一意の識別子。

戻り値

Server-Sent Eventsとして、Repair Printability Task Objectのストリームを返します。

各フレームには、そのステージにおけるタスクオブジェクト全体が含まれます。これは Get エンドポイントが返すものと同じ形式です。そのため、タスクが PENDING または IN_PROGRESS の間は、 出力フィールドはまだ値が設定されておらず（null、[] または {}）、 finished_at は null です。model_urls ブロックは、タスクが SUCCEEDED に達した時点で初めて送信されます。

Request

GET
/openapi/v1/print/repair/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream
curl -N https://api.meshy.ai/openapi/v1/print/repair/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-repair",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1715725401000,
  "task_error": null,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.glb?Expires=***",
    "gltf": "",
    "fbx": "",
    "obj": "",
    "stl": "",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/preview.png?Expires=***",
  "texture_urls": [],
  "consumed_credits": 10
}

The Repair Printability Task Object

  • Name
    id
    Type
    string
    Description

    タスクの一意な識別子です。実装の詳細としてタスクIDにはk-sortable UUIDを使用していますが、idのフォーマットについていかなる仮定もしないでください。

  • Name
    type
    Type
    string
    Description

    プリント可能性を修復タスクのタイプです。値はprint-repairです。

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

    修復された3Dモデルのダウンロード可能なURLです。入力フォーマットに一致するフィールドのみが値を持ち、他のフォーマットのフィールドは空文字列になります。

    • Name
      glb
      Type
      string
      Description

      修復されたGLBのダウンロード可能なURLです。入力がGLBの場合、またはinput_task_idが使用された場合に値が設定されます。

    • Name
      gltf
      Type
      string
      Description

      修復されたGLTFのダウンロード可能なURLです。入力がGLTFのアップロードだった場合に値が設定されます。

    • Name
      fbx
      Type
      string
      Description

      修復されたFBXのダウンロード可能なURLです。入力がFBXのアップロードだった場合に値が設定されます。

    • Name
      obj
      Type
      string
      Description

      修復されたOBJのダウンロード可能なURLです。入力がOBJのアップロードだった場合に値が設定されます。

    • Name
      stl
      Type
      string
      Description

      修復されたSTLのダウンロード可能なURLです。入力がSTLのアップロードだった場合に値が設定されます。

    • Name
      usdz
      Type
      string
      Description

      USDZ出力用に予約されています。プリント可能性を修復タスクでは常に空文字列です。

    • Name
      3mf
      Type
      string
      Description

      3MF出力用に予約されています。プリント可能性を修復タスクでは常に空文字列です。

    • Name
      mtl
      Type
      string
      Description

      MTL出力用に予約されています。プリント可能性を修復タスクでは常に空文字列です。

  • Name
    thumbnail_url
    Type
    string
    Description

    修復されたモデルからレンダリングされたプレビュー画像のURLです。

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

    thumbnail_urlの透明背景（RGBA）バージョンへのダウンロード可能なURLです。タスクがalpha_thumbnail: trueで作成され、透明プレビューが正常にレンダリングされた場合にのみ存在します。それ以外の場合、このフィールドは省略されます。

  • Name
    texture_urls
    Type
    array
    Description

    常に空の配列です。修復は入力のジオメトリのみを保持し、テクスチャの再生成は行いません。

  • Name
    consumed_credits
    Type
    integer
    Description

    このタスクによって消費されたクレジット数です。タスクがSUCCEEDEDに達すると10になります。FAILEDタスクの場合は0を返します（失敗した場合はクレジットが返還されます）。

The Repair Printability Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-repair",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1715725401000,
  "task_error": null,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "gltf": "",
    "fbx": "",
    "obj": "",
    "stl": "",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "texture_urls": [],
  "consumed_credits": 10
}