Auto Split API

3Dモデルを、印刷可能な個別のパーツに分割します——自動で、指定したパーツ名に基づいて、あるいは色の領域ごとに分割でき、必要に応じてコネクターを追加できます。カットによって生じた薄い部分は常に補強されるため、すべてのパーツが中実（ソリッド）に印刷されます。

Auto Splitは現在、テクスチャなしのモデルのみをサポートしています。画像から3Dおよびマルチ画像から3Dを利用する場合は、should_texture を false に設定して入力を生成してください。テクスチャ付きの入力は 400 エラーで拒否されます。

POST/openapi/v1/print/split

Auto Split タスクを作成する

このエンドポイントは、新しい Auto Split タスクを作成します。このタスクは、以前のタスクのモデルを個別に印刷可能なパーツに切り分け、分割されたモデルを返します。各パーツはファイル内で独立したオブジェクトとして扱われます。

パラメータ

  • Name
    input_task_id
    Type
    string
    必須
    Description

    分割対象のモデルを持つ、成功したタスクの ID です。サポートされているタスクタイプ: 画像から3D、マルチ画像から3D、テキストから3D（プレビュー）、リメッシュ、変換、リサイズ。タスクのステータスは SUCCEEDED である必要があり、そのモデルは Meshy 6 または Meshy 7（ai_model が meshy-6、meshy-7、または latest）で生成されている必要があります。ローポリおよび Smart Topology（meshy-t2）モデルはサポートされていません。

  • Name
    mode
    Type
    string
    デフォルト auto
    Description

    モデルをどのようにパーツへ分割するかを指定します。

    利用可能な値:

    • auto: Meshy が切断箇所を選択します。prompt は無視されます。
    • by_parts: prompt で指定した頭、腕、胴体などの構造的なパーツに沿って切断します。
    • by_color: prompt で指定した色領域に沿って切断します。アップロードされた画像から生成された入力（画像から3D または マルチ画像から3D）が必要です。それ以外の入力は 400 で拒否されます。
次の場合のみ適用 mode = by_parts or by_color
  • Name
    prompt
    Type
    string
    必須
    Description

    分割対象のパーツを、任意の言語で記述します。Meshy はここから 1〜10 個のパーツ名を読み取るため、モデルを説明するのではなく、パーツに名前を付けてください。例えば split into the figure and the base、または head, torso, left arm, right arm, legs のように指定します。最大 600 文字です。失敗パターンは2つあります。分割の指示のように読めるが2つ未満のパーツしか名付けていない説明(例えば split into individual parts)は 400 で拒否され、課金は発生しません。Meshy がまったく解釈できない説明の場合は auto にフォールバックし、タスクはそのまま実行されて課金されますが、レスポンスに prompt_ignored: true が含まれます。

  • Name
    target_formats
    Type
    array
    デフォルト ["glb"]
    Description

    分割されたモデルをエクスポートする形式です。各パーツは、すべての形式においてそれぞれ独立したオブジェクトになります。glb は常に生成され、model_urls に含まれて返されます。それ以外に必要な形式があれば、追加でリストに指定してください。

    利用可能な値: glb、obj、fbx、usdz、blend、3mf。

  • Name
    layout
    Type
    string
    デフォルト assembled
    Description

    各出力形式、およびサムネイルにおけるパーツの配置方法です。

    利用可能な値:

    • assembled: パーツは元のモデルにあった位置のまま保持されます。
    • on_plate: パーツは平らに並べられ、造形プレート上に広げられ、そのままスライスできる状態になります — ウェブアプリの On Plate ビューと同じ配置です。

    どちらのレイアウトでも、エクスポートされたファイルにはパーツごとに1つのオブジェクトのみが含まれます。切断によって生じた潰れた薄片や点のような残余パーツは、エクスポート前に除去されるため、ファイル内で見つかるすべてのオブジェクトは印刷可能です。

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

    各切断面にほぞ継ぎ(mortise-and-tenon)コネクタを追加し、印刷したパーツ同士がはまり合うようにします。

次の場合のみ適用 connectors = true
  • Name
    connector_type
    Type
    string
    デフォルト cube
    Description

    各切断面のコネクタの形状です。

    利用可能な値: cube、cylinder。

  • Name
    connector_size
    Type
    number
    デフォルト 0.5
    Description

    切断面に対するコネクタの相対的なサイズです。

    有効範囲: 0.1 〜 0.8。

  • Name
    connector_height
    Type
    number
    デフォルト 0.1
    Description

    切断面からコネクタがどれだけ突き出るかを、切断面に対する相対値で指定します。

    有効範囲: 0.1 〜 0.8。

戻り値

レスポンスの result プロパティには、新しく作成された Auto Split タスクの id が含まれます。

失敗モード

  • Name
    400 - Bad Request
    Description

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

    • prompt が未指定: mode が by_parts または by_color の場合、prompt は必須です。
    • prompt で指定されたパーツが2つ未満: by_parts / by_color では、少なくとも2つの名前付きパーツ(例えば head, torso, base)が必要です。split into individual parts のような一般的な指示は拒否されます。課金は発生しません。
    • サポートされていない入力タスク: input_task_id は、Meshy 6 または Meshy 7 で生成された、サポート対象タイプの成功したタスクを指している必要があります。
    • テクスチャ付きの入力: 入力モデルにテクスチャが含まれています。現時点ではテクスチャなしのモデルのみサポートされています。
    • 参照画像なし: by_color にはアップロードされた画像から生成された入力が必要です。
    • サポートされていない形式: target_formats に stl が含まれています。
    • 範囲外のコネクタ値: connector_size または connector_height が 0.1 〜 0.8 の範囲外です。
  • Name
    401 - Unauthorized
    Description

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

  • Name
    402 - Payment Required
    Description

    このタスクを実行するためのクレジットが不足しています。

  • Name
    404 - Not Found
    Description

    input_task_id が存在しないか、あなたのアカウントに属していません。

  • Name
    429 - Too Many Requests
    Description

    レート制限を超過しました。by_parts および by_color のリクエストは、アカウントごとに1分あたり12リクエストという prompt 解析の制限も共有します。

  • Name
    503 - Service Unavailable
    Description

    プロンプトベースの分割(by_parts および by_color)は一時的に利用できません。後で再試行するか、影響を受けない mode: "auto" を使用してください。課金は発生しません。

Request

POST
/openapi/v1/print/split
# Simple request: let Meshy choose the cuts
curl https://api.meshy.cn/openapi/v1/print/split \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
  }'

# Advanced request: name the parts, add connectors, export glb and obj
curl https://api.meshy.cn/openapi/v1/print/split \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "mode": "by_parts",
    "prompt": "split into the figure and the base",
    "target_formats": ["glb", "obj"],
    "layout": "on_plate",
    "connectors": true,
    "connector_type": "cylinder",
    "connector_size": 0.4
  }'

Response

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

Auto Split タスクを取得

このエンドポイントは、IDによってAuto Splitタスクを取得します。

パラメータ

  • Name
    id
    Type
    path
    Description

    取得するAuto SplitタスクのID。

戻り値

Auto Splitタスクオブジェクト。

Request

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-split",
  "model_urls": {
    "glb": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "part_count": 4,
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000082000,
  "task_error": null,
  "consumed_credits": 10
}
DELETE/openapi/v1/print/split/:id

Auto Splitタスクを削除する

このエンドポイントは、関連するすべてのモデルとデータを含め、Auto Splitタスクを完全に削除します。この操作は取り消せません。

パスパラメータ

  • Name
    id
    Type
    path
    Description

    削除するAuto SplitタスクのID。

戻り値

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

Request

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

Response

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

Auto Split タスク一覧の取得

このエンドポイントを使用すると、Auto Split タスクの一覧を取得できます。

パラメーター

任意の属性

  • Name
    page_num
    Type
    integer
    Description

    ページネーション用のページ番号です。1 から始まり、デフォルトも 1 です。

  • Name
    page_size
    Type
    integer
    Description

    ページサイズの上限です。デフォルトは 10 件です。最大は 100 件で、それより大きい値は 100 に制限されます。

  • Name
    sort_by
    Type
    string
    Description

    並び替えに使用するフィールドです。使用可能な値：

    • +created_at：作成日時の昇順で並び替えます。
    • -created_at：作成日時の降順で並び替えます。

戻り値

Auto Split タスクオブジェクトのページネーションされた一覧を返します。

Request

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-split",
    "model_urls": {
      "glb": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
    "part_count": 4,
    "progress": 100,
    "status": "SUCCEEDED",
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000082000,
    "task_error": null,
    "consumed_credits": 10
  }
]
GET/openapi/v1/print/split/:id/stream

Auto Splitタスクをストリーミングする

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

パラメータ

  • Name
    id
    Type
    path
    Description

    ストリーミングするAuto Splitタスクの一意の識別子。

戻り値

Auto SplitタスクオブジェクトのストリームをServer-Sent Eventsとして返します。

各messageイベントには、Auto Splitタスクを取得するによって返されるものと同じ完全なタスクオブジェクトが含まれ、consumed_credits、タイムスタンプ、prompt_ignoredも含まれます。タスクがPENDINGまたはIN_PROGRESSの間は、フレーム間で変化するフィールドはprogress、status、started_at、preceding_tasksであり、SUCCEEDEDに達するとmodel_urls、thumbnail_url、part_count、partsが出現します。errorイベントにはstatus_codeとmessageのみが含まれるため、statusを読み取る前にイベント名で分岐処理を行ってください。

Request

GET
/openapi/v1/print/split/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream
curl -N https://api.meshy.cn/openapi/v1/print/split/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 (other task fields omitted here for brevity;
// each frame is the full task object).
event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "type": "print-split",
  "model_urls": {
    "glb": "https://assets.meshy.cn/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.cn/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/preview.png?Expires=***",
  "part_count": 4,
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000082000,
  "task_error": null,
  "consumed_credits": 10
}

Auto Split タスクオブジェクト

Auto Split タスクは以下のプロパティのみを持ちます。他のタスクオブジェクトに含まれる生成プロンプト用のフィールド（name、object_prompt、texture_prompt など）、単一の model_url、および texture_urls は、split では決して設定されず、返却されません。タスクの実行中に値が入るプロパティ（thumbnail_url、model_urls、各タイムスタンプ）は常に存在し、値が入るまでは空のままなので、PENDING と SUCCEEDED の間でキーの集合が変化することはありません。

  • Name
    id
    Type
    string
    Description

    タスクの一意な識別子です。実装の詳細としてタスク ID には k-sortable な UUID を使用していますが、id の形式について何らかの前提を置くべきではありません。

  • Name
    type
    Type
    string
    Description

    タスクの種類です。値は print-split です。

  • Name
    model_urls
    Type
    object
    Description

    分割されたモデルへのダウンロード可能な URL で、リクエストされたフォーマットごとに1つずつ含まれます。各パーツはファイル内でそれぞれ別のオブジェクトになります。リクエストされなかったフォーマットのプロパティは省略されます。

    • Name
      glb
      Type
      string
      Description

      GLB 形式の分割モデルへのダウンロード可能な URL です。

    • Name
      obj
      Type
      string
      Description

      OBJ 形式の分割モデルへのダウンロード可能な URL です。

    • Name
      fbx
      Type
      string
      Description

      FBX 形式の分割モデルへのダウンロード可能な URL です。

    • Name
      usdz
      Type
      string
      Description

      USDZ 形式の分割モデルへのダウンロード可能な URL です。

    • Name
      blend
      Type
      string
      Description

      Blender 形式の分割モデルへのダウンロード可能な URL です。

    • Name
      3mf
      Type
      string
      Description

      3MF 形式の分割モデルへのダウンロード可能な URL です。

  • Name
    thumbnail_url
    Type
    string
    Description

    リクエストされた layout に従い、各パーツが異なる色で表示された、分割モデルのレンダリングプレビューへのダウンロード可能な URL です。

  • Name
    prompt_ignored
    Type
    boolean
    Description

    by_parts または by_color リクエストの prompt でパーツ名が指定されなかったために、Meshy が代わりに自動的にモデルを分割した場合に true になります — その場合、結果に含まれるパーツ名はあなたが指定したものではなく、Meshy によるものです。PENDING の時点から存在します。auto タスクの場合、および prompt に従って分割が行われた場合は省略されます。

  • Name
    part_count
    Type
    integer
    Description

    分割されたモデル内の印刷可能なパーツ数です — エクスポートされたファイル内のオブジェクトごとに1つとなります。セグメンテーションによって印刷可能なパーツにできなかった、つぶれた薄片はエクスポート前にファイルから除去され、カウントされません。

  • Name
    progress
    Type
    integer
    Description

    タスクの progress です。タスクがまだ開始されていない場合、このプロパティは 0 になります。タスクが成功すると、100 になります。

  • Name
    status
    Type
    string
    Description

    タスクのステータスです。取り得る値は PENDING、IN_PROGRESS、SUCCEEDED、FAILED、CANCELED のいずれかです。

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

    失敗したタスクのエラー詳細です。task_error オブジェクトの完全なリファレンスについては エラー を参照してください。

  • Name
    consumed_credits
    Type
    integer
    Description

    このタスクによって消費されたクレジット数です。常に存在し、タスクが受理されると 10 になり、FAILED タスクでは失敗時に課金が返金されるため 0 になります。タスクが PENDING のうちに削除された場合も返金されます。

The Auto Split Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-split",
  "model_urls": {
    "glb": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "part_count": 4,
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000082000,
  "task_error": null,
  "consumed_credits": 10
}