UV Unwrap API
UV Unwrap APIは、既存の3Dモデルに対して高品質なUV展開を自動生成します。テクスチャリングの前段階として、またはBlender、Substance Painter、Unrealなどの下流ツールのために、重なりのないクリーンなUVレイアウトが必要なときにいつでもご利用ください。
出力されるのは「UVホワイトモデル」です — 入力と同じ形状を保ちながら、新しいUV座標を持ち、実際のテクスチャは含まれません（glTFのマテリアルスロットを有効に保つため、2×2のグレーのプレースホルダーマテリアルが含まれていますが、標準的なツールではこれをテクスチャなしとして扱います）。
制限事項。 現在、Auto UVは最大40,000面までのメッシュに対応しています — それより大きいモデルは400エラーで拒否されるため、先にリメッシュを実行してポリゴン数を減らしてください。クワッド（四角形）およびn角形メッシュは、UV生成時に三角形化されるため、出力は常に三角形メッシュになります。
UV Unwrapタスクを作成する
このエンドポイントは、新しいUV Unwrapタスクを作成します。
パラメータ
input_task_id または model_url のいずれか一方が必須です。両方が指定された場合は、input_task_id が優先されます。
- Name
- input_task_id
- Type
- string
- 必須
- Description
UV展開したいGLB出力を持つ、完了済みのMeshy APIタスクのID（例：画像から3D、テキストから3D、またはRemeshの結果）。ソースとなるタスクのステータスは
SUCCEEDEDであり、GLBファイルを生成している必要があります。ソースメッシュの面数が上限の40,000面を超えている場合、リクエストは
400で拒否されます。その場合はまずRemeshを実行してポリゴン数を減らしてください。
- Name
- model_url
- Type
- string
- 必須
- Description
公開アクセス可能なURLまたはdata URIを介して、3Dモデルを直接指定します。サポートされるのは
.glbのみです — APIはglTFバイナリを読み取るのみで、他の形式は解析しません。他の形式（.fbx、.obj、.stl、.gltf）のモデルをUV展開するには、まずConvert APIで.glbに変換し、生成されたタスクIDをinput_task_idとして、またはそのGLB出力URLをここに渡してください。Data URIを使用する場合は、MIMEタイプ
application/octet-streamを使用してください。input_task_idの場合と同じ40,000面の上限が適用されます。上限を超えるメッシュは400で拒否されるため、まずRemeshを実行してください。
戻り値
レスポンスの result プロパティには、新しく作成されたUV Unwrapタスクの id が含まれます。
失敗モード
- Name
400 - Bad Request- Description
リクエストが受理できませんでした。よくある原因：
- パラメータの欠落：
input_task_idまたはmodel_urlのいずれかを指定する必要があります。 - 無効な入力タスク：
input_task_idは、GLB結果を持つ成功したタスクを参照している必要があります。 - 面数超過：ソースメッシュの面数がUV Unwrapの上限を超えています。まずRemeshを実行してください。
- 無効なモデル形式：
model_urlがサポートされていない拡張子のファイルを指しています。 - URLに到達できない：
model_urlをダウンロードできませんでした。
- パラメータの欠落：
- Name
401 - Unauthorized- Description
認証に失敗しました。APIキーを確認してください。
- Name
402 - Payment Required- Description
このタスクを実行するためのクレジットが不足しています。UV Unwrapは1回の呼び出しにつき5クレジットかかります。
- Name
404 - Not Found- Description
この機能はお使いのアカウントで有効になっていません。UV Unwrapは展開期間中、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展開タスクを完全に削除します。タスクとその出力にはアクセスできなくなります。
まだ PENDING 状態のタスクは削除され、作成時に消費されたクレジットは返金されます。
すでに IN_PROGRESS のタスクは削除できません。リクエストは 409 Conflict で
拒否され、タスクは実行され続けます。ワーカーがすでに開始しているタスクのクレジットは
返金対象外のため、実行中に削除すると、クレジットと結果の両方を失うことになります。
SUCCEEDED、FAILED、または CANCELED になるのを待ってから削除してください。
終了状態（SUCCEEDED、FAILED、または CANCELED）にあるタスクは、
返金なしで削除されます。
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 UnwrapタスクをStreamする
タスクのprogressをServer-Sent Eventsとして購読します。各messageイベントはUV Unwrap Taskオブジェクトを伝えます。タスクが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 Unwrapタスクオブジェクト
- 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
タスクの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
- 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
}