UV展開API
UV展開APIは、既存の3Dモデルに対して高品質なUV展開を自動生成します。テクスチャリングの前提ステップとして使用するか、クリーンで重ならないUVレイアウトが必要な場合に使用します（Blender、Substance Painter、Unrealなどの下流ツール用）。
出力は「UVホワイトモデル」で、入力と同じ形状ですが、新しいUV座標が付与され、実際のテクスチャはありません（glTFマテリアルスロットを有効に保つために2×2のグレープレースホルダーマテリアルが含まれています。標準ツールではこれを未テクスチャとして扱います）。
制限事項。 自動UVは現在、40,000面までのメッシュをサポートしています。それ以上の大きさのモデルは400で拒否されます。ポリゴン数を減らすために最初にリメッシュを実行してください。UV生成中に四角形メッシュとn-gonメッシュは三角形化されるため、出力は常に三角形メッシュになります。
UV展開タスクの作成
このエンドポイントは新しいUV展開タスクを作成します。
パラメータ
input_task_id または model_url のいずれか一つが必要です。両方が提供された場合、input_task_id が優先されます。
- Name
- input_task_id
- Type
- string
- 必須
- Description
UV展開したいGLB出力を持つ完了したMeshy APIタスクのIDです（例えば、画像から3D、テキストから3D、またはリメッシュの結果）。ソースタスクは
SUCCEEDEDのステータスを持ち、GLBファイルを生成している必要があります。ソースメッシュが40,000面のフェイス数上限を超える場合、リクエストは
400で拒否され、ポリゴン数を減らすためにまずリメッシュを実行する必要があります。
- Name
- model_url
- Type
- string
- 必須
- Description
公開アクセス可能なURLまたはData URIを介して3Dモデルを直接提供します。
.glbのみがサポートされています — APIはglTFバイナリを読み取り、他の形式を解析しません。他の形式のモデル（.fbx、.obj、.stl、.gltf）をUV展開するには、まず変換APIを介して.glbに変換し、その後、生成されたタスクIDをinput_task_idとして、またはそのGLB出力URLをここに渡します。Data URIの場合、MIMEタイプ
application/octet-streamを使用してください。input_task_idと同様に40,000面の上限が適用されます：サイズオーバーのメッシュは400で拒否されます — まずリメッシュを実行してください。
戻り値
レスポンスのresultプロパティには、新しく作成されたUV展開タスクのidが含まれています。
失敗モード
- Name
400 - Bad Request- Description
リクエストが受け入れられませんでした。一般的な原因：
- パラメータが不足している:
input_task_idまたはmodel_urlのいずれかを提供する必要があります。 - 無効な入力タスク:
input_task_idはGLB結果を持つ成功したタスクを指している必要があります。 - フェイス数超過: ソースメッシュがUV展開の上限を超えるフェイス数を持っています。まずリメッシュを実行してください。
- 無効なモデル形式:
model_urlがサポートされていない拡張子のファイルを指しています。 - 到達不能なURL:
model_urlがダウンロードできませんでした。
- パラメータが不足している:
- Name
401 - Unauthorized- Description
認証に失敗しました。APIキーを確認してください。
- Name
402 - Payment Required- Description
このタスクを実行するためのクレジットが不足しています。UV展開は1回の呼び出しにつき5クレジットが必要です。
- Name
404 - Not Found- Description
この機能はあなたのアカウントで有効になっていません。UV展開はロールアウト中にStatsigフラグで制限されています — アクセスが必要な場合はMeshyサポートに連絡してください。
- Name
429 - Too Many Requests- Description
レート制限を超えました。
Request
# Chain from an existing Meshy task
curl https://api.meshy.ai/openapi/v1/uv-unwrap \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"input_task_id": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}'
# Or from a publicly accessible model URL
curl https://api.meshy.ai/openapi/v1/uv-unwrap \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"model_url": "https://example.com/path/to/model.glb"
}'
Response
{
"result": "019361c6-9b34-7b23-bef2-d0107c4d92e2"
}
UV展開タスクを取得する
Request
curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
以下の例のタスクオブジェクトを参照してください。
UV展開タスクを削除する
UV展開タスクを永久に削除します。タスクとその出力はアクセスできなくなります。
Request
curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-X DELETE \
-H "Authorization: Bearer ${YOUR_API_KEY}"
UV展開タスクをリスト
呼び出し元のUV展開タスクのページネーションされたリストを、新しいものから順に返します。標準的なページネーションはpage_numとpage_sizeを使用します。
Request
curl "https://api.meshy.ai/openapi/v1/uv-unwrap?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"
UV展開タスクをストリームする
サーバー送信イベントとしてタスクprogressを購読します。各messageイベントはUV展開タスクオブジェクトを運びます。タスクがSUCCEEDED、FAILED、またはCANCELEDに達するとストリームは閉じます。
完了時の低遅延のために、GET /openapi/v1/uv-unwrap/:idをポーリングする代わりにこれを使用してください。
Request
curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-N
UV展開タスクオブジェクト
- Name
- id
- Type
- string
- Description
タスクのユニークな識別子。
- Name
- type
- Type
- string
- Description
常に
uv-unwrap。
- Name
- model_urls
- Type
- object
- Description
生成されたUVホワイトモデルのための事前署名されたダウンロードURL。UV展開は常に単一の
glbエントリを返します。出力は入力ジオメトリを保持し、新しいUV座標を入れ替え、任意のテクスチャの代わりにデフォルトのグレーマテリアルを使用します。
- Name
- thumbnail_url
- Type
- string
- Description
UVホワイトモデルのPNGプレビューのための事前署名されたURL。
- 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
タスク作成のタイムスタンプ（ミリ秒単位）。
- Name
- started_at
- Type
- timestamp
- Description
処理が開始された時のタイムスタンプ（ミリ秒単位）。開始されるまで
0。
- Name
- finished_at
- Type
- timestamp
- Description
完了時のタイムスタンプ（ミリ秒単位）。完了するまで
0。
- Name
- expires_at
- Type
- timestamp
- Description
署名されたダウンロードURLが期限切れになる時のタイムスタンプ（ミリ秒単位）。
- Name
- task_error
- Type
- object
- Description
失敗したタスクのエラー詳細。完全な
task_errorオブジェクトのリファレンスについてはエラーを参照してください。
- Name
- consumed_credits
- Type
- integer
- Description
このタスクで消費されたクレジット。
FAILEDタスクの場合は0を返します（失敗時にはクレジットが返金されます）。UV展開は成功時に5クレジットを請求します。
Example UV Unwrap Task Object
{
"id": "019361c6-9b34-7b23-bef2-d0107c4d92e2",
"type": "uv-unwrap",
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/019361c6-9b34-7b23-bef2-d0107c4d92e2/output/model.glb?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/019361c6-9b34-7b23-bef2-d0107c4d92e2/output/preview.png?Expires=***",
"progress": 100,
"status": "SUCCEEDED",
"preceding_tasks": 0,
"created_at": 1716579120000,
"started_at": 1716579122000,
"finished_at": 1716579180000,
"expires_at": 1716665580000,
"task_error": {
"message": ""
},
"consumed_credits": 5
}