UV Unwrap API
UV Unwrap APIは、既存の3Dモデルに対して高品質なUV展開を自動生成します。テクスチャリングの前段階として、あるいはBlender、Substance Painter、Unrealなどの下流ツール向けにクリーンで重なりのないUVレイアウトが必要な場合はいつでもご利用ください。
出力結果は「UVホワイトモデル」です。入力と同じ形状を保ちながら、まったく新しいUV座標を持ち、実際のテクスチャは含まれません（glTFのマテリアルスロットを有効に保つため、2×2のグレーのプレースホルダーマテリアルが含まれています。標準的なツールではこれをテクスチャなしとして扱います）。
制限事項。 Auto UVは現在、最大40,000面までのメッシュに対応しています。これを超えるモデルは400エラーで拒否されるため、先にRemeshを実行してポリゴン数を削減してください。四角形ポリゴンおよびn角形メッシュは、UV生成時に三角形分割されるため、出力は常に三角形メッシュになります。
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を使用してください。最大ファイルサイズ：100 MB。
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をダウンロードできませんでした。 - モデルファイルが大きすぎる：
model_urlのファイルが100 MBを超えています。
- パラメータの欠落：
- 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 Unwrapタスクを取得する
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展開タスクをストリームする
タスクのprogressをServer-Sent Eventsとして購読します。各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
}