修復プリント適性 API

FDMでプリント可能になるように3Dモデルを修復します — 非多様体エッジ、縮退面、穴、その他のトポロジーの問題を修正し、メッシュをプリント準備済みの状態にします。

POST/openapi/v1/print/repair

Repair Printability タスクを作成

この endpoint は、新しい repair-printability タスクを作成します。このタスクは 3D モデルに対してトポロジ修復を実行し、水密でプリント可能なバージョンを返します。

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

パラメータ

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

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

  • Name
    input_task_id
    Type
    string
    必須
    Description

    所有している成功済みタスクの ID。サポートされているタスクタイプ: Image to 3D、Multi-Image to 3D、Text to 3D、Remesh、および Retexture。タスクのステータスは SUCCEEDED であり、GLB アセットを生成している必要があります。

  • Name
    model_url
    Type
    string
    必須
    Description

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

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

    true に設定すると、タスクはプレビューの透明背景（RGBA）版を追加でレンダリングし、GET レスポンスで alpha_thumbnail_url として返します。既存の thumbnail_url フィールドは変更されません。

戻り値

レスポンスの result プロパティには、新しく作成された repair-printability タスクの 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 key を確認してください。

  • 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

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

この endpoint は、ID によって修復プリント適性タスクを取得します。

パラメータ

  • Name
    id
    Type
    path
    Description

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

戻り値

修復プリント適性タスクオブジェクト。タスクが SUCCEEDED に達するまで、model_urls ブロックは空です。入力形式に一致する 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": "",
    "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

修復プリント適性タスクを削除する

この endpoint は、修復プリント適性タスクとその修復済み出力を完全に削除します。この操作は元に戻せません。

パスパラメータ

  • Name
    id
    Type
    path
    Description

    削除する修復プリント適性タスクの ID。

戻り値

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

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

// Returns 200 Ok on success.
GET/openapi/v1/print/repair

修復プリント適性タスクの一覧取得

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

戻り値

Repair Printability Task オブジェクトのページネーションされた一覧を返します。

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=***",
      "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

修復プリント適性タスクをストリーミングする

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

パラメータ

  • Name
    id
    Type
    path
    Description

    ストリーミングする修復プリント適性タスクの一意の識別子。

戻り値

Server-Sent Events として 修復プリント適性タスクオブジェクト のストリームを返します。

PENDING または IN_PROGRESS のタスクの場合、レスポンスストリームには必要な progress フィールドと status フィールドのみが含まれます。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.
// 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-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=***",
    "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
}

修復プリント適性タスクオブジェクト

  • 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

    タスクの進捗です。タスクがまだ開始されていない場合、このプロパティは 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
      fbx
      Type
      string
      Description

      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=***",
    "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
}