UV展開 API

既存の3Dモデルに対してUV展開を生成します。モデルにテクスチャを適用する前、または Blender、Substance Painter、Unreal などのツールでクリーンかつ重なりのないUVレイアウトが必要な場合に実行してください。

出力結果はUVホワイトモデルです。入力と同じ形状を持ち、新しいUV座標が設定されており、実際のテクスチャは含まれません。glTFのマテリアルスロットを有効な状態に保つため、2×2のグレーのプレースホルダーマテリアルが含まれており、標準的なツールでは未テクスチャとして扱われます。

UV展開は最大40,000面までのメッシュに対応しています。これを超えるモデルの場合、400 が返されます。面数を減らすには、先に Remesh を実行してください。

Meshyは、UVを生成する際にクアッドメッシュやn角形メッシュを三角形分割するため、出力は常に三角形メッシュになります。

POST/openapi/v1/uv-unwrap

UV展開タスクを作成する

UV展開タスクを作成します。

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

Request

POST

/openapi/v1/uv-unwrap

# 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"
}

パラメータ

Name
input_task_id
Type
string
必須
Description
model_url を送信しない限り必須です。展開したいGLB出力を持つMeshy APIタスクのID。例えば、画像から3D、テキストから3D、またはリメッシュのタスクです。タスクのステータスは SUCCEEDED であり、GLBファイルを生成している必要があります。
メッシュの面数は最大40,000面までです。これを超えるメッシュは 400 を返します。面数を減らすには、先にリメッシュを実行してください。

Name
model_url
Type
string
必須
Description
input_task_id を送信しない限り必須です。展開するモデルを、公開URLまたはData URIとして指定します。両方を送信した場合、Meshyは input_task_id を使用します。
モデルは .glb ファイルである必要があります。他の形式を展開するには、先に変換APIを使ってGLBに変換してください。
ファイルは、http または https のURLの場合は最大400MB、Data URIの場合は最大100MBまでです。Data URIの場合は、MIMEタイプ application/octet-stream を使用してください。100MBを超えるGLBはDraco圧縮を使用してはいけません。
input_task_id の場合と同じ40,000面の制限が適用されます。これを超えるメッシュは 400 を返すため、先にリメッシュを実行してください。

戻り値

レスポンスの result フィールドには、新しいUV展開タスクのIDが格納されます。

失敗モード

Name
400 - Bad Request
Description
リクエストを実行できません。エラーメッセージには、検出された問題が示されます。例えば：
- パラメータの欠落: input_task_id と model_url のどちらも送信されませんでした。
- 無効な入力タスク: input_task_id がGLB結果を持つ成功したAPIタスクではありません。
- 面数超過: メッシュの面数がUV展開で許可されている数を超えています。先にリメッシュを実行してください。
- 無効なモデル形式: model_url のファイルがサポートされていない拡張子です。
- URLに到達できません: Meshyが model_url のファイルをダウンロードできません。
- モデルファイルが大きすぎます: model_url のファイルが、http または https のURLの場合は400MBを超えているか、Data URIの場合は100MBを超えています。
- 面数が多すぎます: model_url のファイルが100MBを超えており、面数が10,000,000を超えています。面数を減らしてから、ファイルを再送信してください。
- 読み取れないモデルファイル: model_url のファイルが100MBを超えており、Meshyがそのヘッダーを読み取れません。例えば、Draco圧縮されたGLBの場合です。
- モデルヘッダーが複雑すぎます: model_url のファイルが100MBを超えており、そのヘッダーに確認すべきメッシュ、ノード、またはレコードが多すぎます。ファイル内のオブジェクト数を減らしてから、再送信してください。
リクエストを修正してから、再送信してください。エラーを参照してください。
Name
401 - Unauthorized
Description
APIキーが欠落しているか無効です。Authorization ヘッダーを確認してください。
Name
402 - Payment Required
Description
例えば：
- クレジット不足: アカウントにこのタスクを実行するのに十分なクレジットがないか、アカウントがクレジット上限に達しています。UV展開タスクのコストは5クレジットです。クレジット残高を確認してから、再試行してください。
- フリープラン: タスクの作成には有料プランが必要です。サブスクリプション設定でプランをアップグレードしてから、再試行してください。
Name
403 - Forbidden
Description
input_task_id がバスレリーフモデルであり、このエンドポイントでは展開できません。メッセージは 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/uv-unwrap/:id

UV展開タスクを取得する

指定したIDのUV展開タスクの現在の状態を返します。

Request

GET

/openapi/v1/uv-unwrap/:id

curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

レスポンスの例については、UV展開タスクオブジェクトの例を参照してください。

Returns

UV展開タスクオブジェクト。

DELETE/openapi/v1/uv-unwrap/:id

UV Unwrapタスクを削除する

UV Unwrapタスクを、その出力結果を含めて完全に削除します。削除を取り消すことはできません。

Request

DELETE

/openapi/v1/uv-unwrap/:id

curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-X DELETE \
-H "Authorization: Bearer ${YOUR_API_KEY}"

タスクのステータス

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

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

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

GET/openapi/v1/uv-unwrap

UV展開タスクの一覧を取得

あなたのUV展開タスクの一覧を、新しい順にページネーション形式で返します。一覧をページ送りするには、page_num と page_size を使用してください。

Request

GET

/openapi/v1/uv-unwrap

curl "https://api.meshy.ai/openapi/v1/uv-unwrap?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

GET/openapi/v1/uv-unwrap/:id/stream

UV Unwrapタスクをストリーミングする

UV Unwrapタスクの更新をServer-Sent Events（SSE）としてストリーミングします。各messageイベントにはUV Unwrapタスクオブジェクトが含まれます。タスクがSUCCEEDED、FAILED、またはCANCELEDに達すると、ストリームは閉じられます。

タスクの完了をより早く知るには、GET /openapi/v1/uv-unwrap/:idをポーリングする代わりに、このエンドポイントを使用してください。

Request

GET

/openapi/v1/uv-unwrap/:id/stream

curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-N

UV展開タスクオブジェクト

UV展開タスクオブジェクトは、3Dモデルの1つのUV展開を表します。タスクが成功したときのステータス、progress、モデルファイルを保持します。

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
}

Name
id
Type
string
Description
タスクID。不透明な文字列として扱い、そのフォーマットに依存しないでください。
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
タスクが作成された時刻（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ミリ秒）。
Name
task_error
Type
object
Description
タスクが失敗した場合のエラー詳細。エラーを参照してください。
Name
consumed_credits
Type
integer
Description
タスクで使用されたクレジット数。成功したUV展開タスクは5クレジットを消費します。FAILEDタスクの場合は0になります。これは、タスクが失敗した場合にMeshyがクレジットを返金するためです。