Resize API
3Dモデルを実世界のサイズ(メートル単位)にリサイズします。高さまたは最も長い辺の長さを設定するか、Meshyにオブジェクトの実世界での高さを推定させることができます。
Resizeタスクを作成する
Resizeタスクを作成します。タスクはバックグラウンドで実行されます。タスクに通常かかる時間については、処理時間を参照してください。
Request
# Simple: resize to a specific height
curl https://api.meshy.ai/openapi/v1/resize \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"resize_height": 1.8
}'
# Advanced: resize longest side with custom origin
curl https://api.meshy.ai/openapi/v1/resize \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"model_url": "https://example.com/model.glb",
"resize_longest_side": 2.0,
"origin_at": "center"
}'
Response
{
"result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}
パラメータ
- Name
- input_task_id
- Type
- string
- 必須
- Description
model_urlを送信しない場合は必須です。3Dモデルを生成したタスク(例えばText to 3D、Image to 3D、Remesh、Retextureタスク)のIDです。このタスクはAPI由来で、ステータスがSUCCEEDEDである必要があります。Meshyはリサイズされたモデルを GLB ファイルとして返します。
- Name
- model_url
- Type
- string
- 必須
- Description
input_task_idを送信しない場合は必須です。リサイズするモデルを、公開URLまたはdata URIとして指定します。両方送信した場合、Meshyはinput_task_idを使用します。モデルは、GLB、glTF、OBJ、FBX、またはSTLファイルで、
httpまたはhttpsのURLからは最大400MB、data URIとしては最大100MBである必要があります。data URIの場合は、MIMEタイプapplication/octet-streamを使用してください。100MBを超えるファイルには、以下のルールも適用されます。
- GLB、glTF、FBX、またはOBJファイルの面数は最大10,000,000面までです。Meshyは面を三角形として数えるため、四角形は2面として、複数回描画されるメッシュはコピーごとに1回として数えられます。
- FBXファイルはバイナリFBX 7.1以降である必要があります。
- GLBまたはglTFファイルはDraco圧縮を使用していてはいけません。
GLB、OBJ、FBX、またはSTLファイルは、結果でも同じ形式が維持されます。
.gltfファイルまたはdata URIは、GLBとして返されます。
resize_height、resize_longest_side、auto_sizeのうち、必ず1つだけを送信してください。どれも送信しない場合、または複数送信した場合は400が返されます。
- Name
- resize_height
- Type
- number
- Description
モデルの新しい高さ(メートル単位)で、0より大きい値である必要があります。負の値を送信すると
400が返されます。
- Name
- resize_longest_side
- Type
- number
- Description
モデルの最長辺の新しい長さ(メートル単位)で、0より大きい値である必要があります。負の値を送信すると
400が返されます。Meshyはモデルのアスペクト比を維持します。
- Name
- auto_size
- Type
- boolean
- Description
AIビジョンでオブジェクトの実世界での高さを推定し、その高さにモデルをリサイズするかどうかを指定します。
origin_atを設定しない場合、Meshyは原点を底面に配置します。
- Name
- origin_at
- Type
- string
- デフォルト bottom
- Description
リサイズ後にモデルの原点をどこに配置するかを指定します。
bottomまたはcenterです。
レスポンス
レスポンスのresultフィールドには、新しいResizeタスクのIDが格納されます。
失敗モード
- Name
400 - Bad Request- Description
リクエストを実行できません。エラーメッセージには、検出された問題が示されます。例えば:
- パラメータの欠落:
model_urlとinput_task_idのどちらも送信されていません。 - リサイズモードの欠落:
resize_height、resize_longest_side、auto_sizeのいずれも送信されていません。 - 相互排他的なパラメータ:リクエストに
resize_height、resize_longest_side、auto_sizeのうち複数が含まれています。1つだけ送信してください。 - 負のサイズ:
resize_heightまたはresize_longest_sideが負の値です。 - 無効な入力タスク:
input_task_idが、モデルファイルを持つ成功したAPIタスクではありません。 - 無効なモデル形式:
model_urlのファイルが、サポートされていない拡張子です。 - 到達不能なURL:Meshyが
model_urlのファイルをダウンロードできません。 - モデルファイルが大きすぎる:
model_urlのファイルが、httpまたはhttpsのURLからの場合は400MBを、data URIの場合は100MBを超えています。 - 面数が多すぎる:
model_urlのファイルが100MBを超えており、面数が10,000,000を超えています。面数を減らしてから、再度ファイルを送信してください。 - ASCII FBXが100MBを超えている:
model_urlのファイルが100MBを超えるASCII FBXです。バイナリFBXまたはGLBとして送信してください。 - 読み取り不能なモデルファイル:
model_urlのファイルが100MBを超えており、Meshyがそのヘッダーを読み取れません。例えば、Draco圧縮されたGLBまたはglTF、あるいは7.1より古いバイナリFBXなどです。 - モデルヘッダーが複雑すぎる:
model_urlのファイルが100MBを超えており、そのヘッダーに含まれるメッシュ、ノード、またはレコードが多すぎてチェックできません。ファイル内のオブジェクト数を減らしてから、再度送信してください。
リクエストを修正してから、再度送信してください。エラーを参照してください。
- パラメータの欠落:
- 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
レート制限を超えました。しばらく待ってから再試行してください。レート制限を参照してください。
リサイズタスクを取得
IDを指定してリサイズタスクを返します。
Request
curl https://api.meshy.ai/openapi/v1/resize/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
{
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"type": "resize",
"model_urls": {
"glb": "https://assets.meshy.ai/.../model.glb?Expires=..."
},
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000001000,
"task_error": null,
"consumed_credits": 1
}
Resizeタスクを削除する
Resizeタスクを、そのモデルやデータも含めて完全に削除します。削除を元に戻すことはできません。
Request
curl --request DELETE \
--url https://api.meshy.ai/openapi/v1/resize/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 が返されます。
Resizeタスク一覧の取得
お使いのResizeタスクの一覧を返します。
Request
curl https://api.meshy.ai/openapi/v1/resize?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
[
{
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"type": "resize",
"model_urls": {
"glb": "https://assets.meshy.ai/.../model.glb?Expires=..."
},
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000001000,
"task_error": null,
"consumed_credits": 1
}
]
パラメータ
- Name
- page_num
- Type
- integer
- デフォルト 1
- Description
返却するページ番号。最大
255まで指定できます。これより大きい値を指定すると400が返されます。
- Name
- page_size
- Type
- integer
- デフォルト 10
- Description
1ページあたりのタスク数。最大
100まで指定できます。
- Name
- sort_by
- Type
- string
- Description
並び順。
利用可能な値:
+created_at:古い順-created_at:新しい順
返り値
Resizeタスクオブジェクトのページネーションされたリスト。
Resizeタスクをストリーミングする
Resizeタスクの更新をServer-Sent Events(SSE)としてストリーミングします。
Request
curl -N https://api.meshy.ai/openapi/v1/resize/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response Stream
// Message event examples illustrate task progress.
event: message
data: {
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"progress": 0,
"status": "PENDING"
}
event: message
data: {
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"type": "resize",
"model_urls": {
"glb": "https://assets.meshy.ai/.../model.glb?Expires=..."
},
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000001000,
"task_error": null,
"consumed_credits": 1
}
パラメータ
- Name
- id
- Type
- path
- Description
作成時のレスポンスから取得したタスクIDです。
戻り値
ResizeタスクオブジェクトのストリームをServer-Sent Eventsとして返します。
各イベントには、Getエンドポイントが返すものと同じ形式で、タスクオブジェクト全体が含まれます。タスクがPENDINGまたはIN_PROGRESSの間は、結果フィールドにはまだ値が入っていません。
Resizeタスクオブジェクト
Resizeタスクオブジェクトは、3Dモデルの1回のリサイズを表します。タスクが成功したときのステータス、progress、モデルファイルを保持します。
プロパティ
- Name
- id
- Type
- string
- Description
タスクID。不透明な文字列として扱い、その形式に依存しないでください。
- Name
- type
- Type
- string
- Description
タスクタイプ。常に
resizeです。
- Name
- model_urls
- Type
- object
- Description
リサイズされたモデルファイルのダウンロードURL。
input_task_idの場合、ファイルは常にGLBです。model_urlの場合、GLB、OBJ、FBX、STLファイルはそのフォーマットを保持し、.gltfファイルまたはData URIはGLBとして返されます。
- Name
- progress
- Type
- integer
- Description
タスクがどれだけ完了したかをパーセンテージで示します。タスクが開始するまでは
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
タスクが作成された時刻(Unixミリ秒)。
- Name
- started_at
- Type
- timestamp
- Description
タスクが開始された時刻(Unixミリ秒)。タスクが開始するまでは
0です。
- Name
- finished_at
- Type
- timestamp
- Description
タスクが終了した時刻(Unixミリ秒)。タスクが終了するまでは
0です。
- Name
- expires_at
- Type
- timestamp
- Description
タスクのダウンロードURLが期限切れになる時刻(Unixミリ秒)。タスクが終了するまでは
0です。
- Name
- texture_urls
- Type
- array
- Description
タスクが成功した場合の、モデルのテクスチャマップのダウンロードURL:テクスチャセットごとに1つのオブジェクトからなる配列です。各オブジェクトには
base_colorのURLがあり、さらにmetallic、roughness、normal、emission、metallic_roughnessのURLを持つこともあります。タスクが成功するまではnullで、モデルにテクスチャマップがない場合は空の配列になります。
- Name
- task_error
- Type
- object
- Description
タスクが失敗した場合のエラー詳細。エラーを参照してください。
- Name
- consumed_credits
- Type
- integer
- Description
タスクが使用したクレジット数。Resizeタスクの場合は
1です。FAILEDタスクの場合は0です。