リメッシュ API

3Dモデルのメッシュを新しいtopologyと面数で再構築し、選択した形式でエクスポートします。モデルは、画像から3Dやテキストから3Dなど、別のMeshyタスクから取得することも、モデルファイルから取得することもできます。

POST/openapi/v1/remesh

Remeshタスクを作成する

Remeshタスクを作成します。タスクはバックグラウンドで実行されます。タスクに通常どれくらいの時間がかかるかについては、処理時間を参照してください。

モデルのフォーマットを変換したりリサイズしたりするには、Convert APIまたはResize APIを使用してください。このページに記載されている非推奨のパラメータは引き続き動作しますが、新しく統合する場合はこれらのエンドポイントを使用してください。

Request

POST

/openapi/v1/remesh

# Basic remesh with custom formats and resize
curl https://api.meshy.ai/openapi/v1/remesh \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["glb", "fbx"],
    "topology": "quad",
    "target_polycount": 50000,
    "resize_height": 1.0,
    "origin_at": "bottom"
  }'

# Quad remesh with auto-size
curl https://api.meshy.ai/openapi/v1/remesh \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["glb", "fbx"],
    "topology": "quad",
    "target_polycount": 50000,
    "auto_size": true
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

パラメータ

Name
input_task_id
Type
string
必須
Description
model_urlを送信しない場合は必須です。リメッシュしたいモデルを持つタスクのID。例えば、テキストから3D、画像から3D、リテクスチャ、Remeshタスクなどです。このタスクはAPIで作成し、ステータスがSUCCEEDEDである必要があります。

Name
model_url
Type
string
必須
Description
input_task_idを送信しない場合は必須です。リメッシュするモデルを、公開URLまたはData URIとして指定します。両方を送信した場合、Meshyはinput_task_idを使用します。
モデルは、httpまたはhttpsのURLからの場合は最大400 MB、Data URIの場合は最大100 MBの、GLB、glTF、OBJ、FBX、またはSTLファイルである必要があります。Data URIの場合は、MIMEタイプapplication/octet-streamを使用してください。
100 MBを超えるファイルは、さらに以下のルールにも従う必要があります：
- GLB、glTF、FBX、またはOBJファイルの面数は最大10,000,000面までです。Meshyは面を三角形としてカウントするため、四角形は2面としてカウントされ、複数回描画されるメッシュはコピーごとに1回カウントされます。
- FBXファイルはバイナリFBX 7.1以降である必要があります。
- GLBまたはglTFファイルはDraco圧縮を使用していてはいけません。

Name
target_formats
Type
string[]
デフォルト ["glb"]
Description
生成するファイルフォーマット。
利用可能な値：
- glb
- fbx
- obj
- usdz
- blend
- stl
- 3mf
Name
topology
Type
string
デフォルト triangle
Description
リメッシュ後のモデルの面タイプ。
利用可能な値：
- quad：四角形主体のメッシュ
- triangle：デシメーション処理された三角形メッシュ
Name
target_polycount
Type
integer
デフォルト 30000
Description
目標とする面数で、100から300000までの範囲です。結果はモデルのジオメトリによって、目標値と異なる場合があります。範囲外の値を指定すると400が返されます。
Name
decimation_mode
Type
integer
Description
レベルによる適応的な面数設定です。これを設定すると、Meshyはtarget_polycountを無視します。
利用可能な値：
- 1：ultra
- 2：high
- 3：medium
- 4：low
Name
resize_height
Type
number
⚠ 非推奨
デフォルト 0
Description
代わりにResize APIを使用してください。モデルをリサイズする高さ（メートル単位）。resize_height、resize_longest_side、auto_sizeのうち、最大1つだけを送信してください。
Name
resize_longest_side
Type
number
⚠ 非推奨
デフォルト 0
Description
代わりにResize APIを使用してください。モデルのバウンディングボックスの最長辺をリサイズする長さ（メートル単位）。resize_height、resize_longest_side、auto_sizeのうち、最大1つだけを送信してください。
Name
auto_size
Type
boolean
⚠ 非推奨
デフォルト false
Description
代わりにResize APIを使用してください。AIビジョンでオブジェクトの実世界での高さを推定し、それに合わせてモデルをリサイズするかどうか。resize_height、resize_longest_side、auto_sizeのうち、最大1つだけを送信してください。
Name
origin_at
Type
string
⚠ 非推奨
デフォルト bottom
Description
代わりにResize APIを使用してください。モデルの原点を置く位置で、bottomまたはcenterです。デフォルト値は、resize_height、resize_longest_side、auto_sizeのいずれかを送信した場合に適用されます。これらのいずれも送信しない場合、Meshyはorigin_atを送信した場合のみ原点を移動します。

Name
convert_format_only
Type
boolean
⚠ 非推奨
Description
代わりにConvert APIを使用してください。モデルをtarget_formatsに変換するだけにするかどうか。trueの場合、Meshyはtopology、target_polycount、decimation_mode、resize_height、resize_longest_side、auto_sizeを無視しますが、それらの値の検証は引き続き行うため、無効な値を送信すると400が返されます。convert_format_only: trueの場合、target_formatsが空またはnullだと400が返されます。

Name
alpha_thumbnail
Type
boolean
デフォルト false
Description
透明な背景（RGBA）のプレビューも生成するかどうか。生成されたプレビューは、タスクを取得した際にalpha_thumbnail_urlで返されます。thumbnail_urlは変更されません。

返り値

レスポンスのresultフィールドには、新しく作成されたRemeshタスクのIDが入ります。

失敗モード

Name
400 - Bad Request
Description
リクエストを実行できません。エラーメッセージには、検出された問題が示されます。例えば：
- パラメータ不足：model_urlもinput_task_idも送信されませんでした。
- 無効な入力タスク：input_task_idが成功したAPIタスクではないか、そのAIモデルがリメッシュに対応していません。
- 無効なモデルフォーマット：model_urlのファイルがサポートされていない拡張子です。
- 到達不能なURL：Meshyがmodel_urlのファイルをダウンロードできません。
- モデルファイルが大きすぎる：model_urlのファイルが、httpまたはhttpsのURLの場合は400 MBを超えているか、Data URIの場合は100 MBを超えています。
- 面数が多すぎる：model_urlのファイルが100 MBを超えており、面数が10,000,000を超えています。面数を減らしてから、ファイルを再送信してください。
- 100 MBを超えるASCII FBX：model_urlのファイルが100 MBを超えるASCII FBXです。バイナリFBXまたはGLBとして送信してください。
- 読み取り不能なモデルファイル：model_urlのファイルが100 MBを超えており、Meshyがそのヘッダーを読み取れません。例えば、Draco圧縮されたGLBまたはglTF、あるいは7.1より古いバイナリFBXなどです。
- モデルヘッダーが複雑すぎる：model_urlのファイルが100 MBを超えており、そのヘッダーに含まれるメッシュ、ノード、またはレコードが多すぎてチェックできません。ファイル内のオブジェクト数を減らしてから、再送信してください。
- 無効なtopology：topologyがquadでもtriangleでもありません。
- 相互排他的なパラメータ：リクエストにauto_size、resize_height、resize_longest_sideのうち複数が含まれています。1つだけを送信してください。
リクエストを修正してから、再度送信してください。エラーを参照してください。
Name
401 - Unauthorized
Description
APIキーが存在しないか無効です。Authorizationヘッダーを確認してください。
Name
402 - Payment Required
Description
例えば：
- クレジット不足：このタスクに対してアカウントのクレジットが不足しているか、アカウントがクレジット制限に達しています。クレジット残高を確認してから、再試行してください。
- 無料プラン：タスクを作成するには有料プランが必要です。サブスクリプション設定でプランをアップグレードしてから、再試行してください。
Name
403 - Forbidden
Description
input_task_idが、このエンドポイントではリメッシュできない浮き彫り（bas-relief）モデルです。メッセージはThis model type does not support this operationです。別のモデルを送信してください。
Name
404 - Not Found
Description
input_task_idがあなたのどのタスクとも一致しません。タスクIDを確認してから、リクエストを再度送信してください。
Name
429 - Too Many Requests
Description
レート制限を超過しました。しばらく待ってから再試行してください。レート制限を参照してください。

GET/openapi/v1/remesh/:id

リメッシュタスクを取得

IDを指定してリメッシュタスクを返します。

Request

GET

/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "remesh",
  "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
      "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
},
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
}

パラメータ

Name
id
Type
path
Description
作成レスポンスから取得したタスクIDです。

返り値

リメッシュタスクオブジェクト。

DELETE/openapi/v1/remesh/:id

リメッシュタスクを削除

リメッシュタスクを、そのモデルやデータも含めて完全に削除します。削除を取り消すことはできません。

Request

DELETE

/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/remesh/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 keeps 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."
}

パスパラメータ

Name
id
Type
path
Description
削除するタスクのID。

タスクのステータス

PENDING のタスクを削除すると、タスクを作成した際に使用したクレジットが返金されます。

IN_PROGRESS のタスクは削除できません。リクエストは 409 Conflict を返し、タスクは実行され続けます。Meshyは、すでに開始されたタスクについては返金を行わないため、そのようなタスクを削除すると、クレジットと結果の両方を失うことになります。 SUCCEEDED、FAILED、または CANCELED のいずれかの状態になるのを待ってから削除してください。

最終ステータス（SUCCEEDED、FAILED、または CANCELED）にあるタスクを削除しても、クレジットは返金されません。

戻り値

タスクが削除された場合は 200 OK、タスクが IN_PROGRESS の場合は 409 Conflict が返されます。

GET/openapi/v1/remesh

リメッシュタスク一覧の取得

あなたのリメッシュタスクの一覧を返します。

Request

GET

/openapi/v1/remesh

curl https://api.meshy.ai/openapi/v1/remesh?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "remesh",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
      "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null
  }
]

パラメーター

Name
page_num
Type
integer
デフォルト 1
Description
返すページ番号。
Name
page_size
Type
integer
デフォルト 10
Description
1ページあたりのタスク数。最大 100 まで。
Name
sort_by
Type
string
Description
並び順。
利用可能な値：
- +created_at: 古い順
- -created_at: 新しい順

戻り値

リメッシュタスクオブジェクトのページネーションされたリスト。

GET/openapi/v1/remesh/:id/stream

リメッシュタスクをストリーミングする

リメッシュタスクの更新情報を、Server-Sent Events (SSE) としてストリーミングします。

Request

GET

/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream

curl -N https://api.meshy.ai/openapi/v1/remesh/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.
// These examples are shortened. Each event holds the full task object.
event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "remesh",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
    "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
}

パラメータ

Name
id
Type
path
Description
作成レスポンスに含まれるタスクIDです。

戻り値

リメッシュタスクオブジェクトのストリームを、Server-Sent Events として返します。

各イベントには、Get エンドポイントが返すものと同じ形式で、タスクオブジェクト全体が含まれます。タスクが PENDING または IN_PROGRESS の間は、結果フィールドにまだ値が設定されていません。

リメッシュタスクオブジェクト

リメッシュタスクオブジェクトは、3Dモデルの1回のリメッシュを表します。タスクのステータス、progress、そしてタスクが成功した場合のモデルファイルを保持します。

プロパティ

Example Remesh Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "remesh",
  "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
      "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5
}

Name
id
Type
string
Description
タスクID。不透明な文字列として扱い、そのフォーマットに依存しないでください。
Name
type
Type
string
Description
タスクタイプ。常に remesh です。
Name
model_urls
Type
object
Description
リメッシュされたモデルのダウンロードURLで、ファイル形式ごとに1つずつ用意されます。タスクが生成しなかった形式については、空文字列ではなくキー自体が存在しません。
- Name
  glb
  Type
  string
  Description
  GLBファイル。
- Name
  fbx
  Type
  string
  Description
  FBXファイル。
- Name
  obj
  Type
  string
  Description
  OBJファイル。
- Name
  usdz
  Type
  string
  Description
  USDZファイル。
- Name
  blend
  Type
  string
  Description
  Blenderファイル。
- Name
  stl
  Type
  string
  Description
  STLファイル。
- Name
  3mf
  Type
  string
  Description
  3MFファイル。target_formats に 3mf が含まれる場合のみ存在します。
Name
thumbnail_url
Type
string
Description
リメッシュされたモデルのプレビュー画像のダウンロードURL。
Name
alpha_thumbnail_url
Type
string
Description
thumbnail_url の透明背景（RGBA）版のダウンロードURL。タスクを alpha_thumbnail: true で作成し、Meshyが透明プレビューをレンダリングした場合にのみ存在します。
Name
progress
Type
integer
Description
タスクがどの程度完了しているかをパーセンテージで示します。タスクが開始するまでは 0 で、成功すると 100 になります。
Name
status
Type
string
Description
タスクのステータス。PENDING、IN_PROGRESS、SUCCEEDED、FAILED のいずれかです。
Name
preceding_tasks
Type
integer
Description
キュー内でこのタスクより前にあるタスクの数。この値はタスクが PENDING の間のみ意味を持ちます。
Name
created_at
Type
timestamp
Description
タスクが作成された時刻（Unixミリ秒）。
Name
started_at
Type
timestamp
Description
タスクが開始された時刻（Unixミリ秒）。タスクが開始するまでは 0 です。
Name
finished_at
Type
timestamp
Description
タスクが終了した時刻（Unixミリ秒）。タスクが終了するまでは 0 です。
Name
task_error
Type
object
Description
タスクが失敗した場合のエラー詳細。エラーを参照してください。
Name
consumed_credits
Type
integer
Description
タスクが使用したクレジットの数。ステータスが PENDING、IN_PROGRESS、SUCCEEDED のいずれかの場合に存在します。FAILED タスクでは 0 になります。これは、タスクが失敗した場合にMeshyがクレジットを返金するためです。