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-gon メッシュは UV 生成中に 三角形化 されるため、出力は常に三角形メッシュになります。

POST/openapi/v1/uv-unwrap

UV展開タスクを作成

このendpointは新しいUV展開タスクを作成します。

パラメータ

input_task_id または model_url のいずれか一方のみが必須です。両方が指定された場合は、input_task_id が優先されます。

  • Name
    input_task_id
    Type
    string
    必須
    Description

    UV展開したいGLB出力を持つ、完了済みのMeshy APIタスクのID（例：Image to 3D、Text to 3D、またはRemeshの結果）。ソースタスクのステータスは SUCCEEDED であり、GLBファイルが生成されている必要があります。

    ソースメッシュが40,000面のフェイス数上限を超える場合、リクエストは 400 で拒否されます。その場合は、まずRemeshを実行してポリゴン数を下げてください。

  • Name
    model_url
    Type
    string
    必須
    Description

    公開アクセス可能なURLまたはデータURIを介して、3Dモデルを直接指定します。サポートされているのは .glb のみです — APIはglTFバイナリを読み取り、他の形式は解析しません。別の形式（.fbx、.obj、.stl、.gltf）のモデルをUV展開するには、まず Convert API で .glb に変換し、その結果のタスクIDを input_task_id として渡すか、ここでそのGLB出力URLを渡してください。

    データURIの場合は、MIMEタイプ application/octet-stream を使用してください。

    input_task_id と同じ40,000面の上限が適用されます。サイズ超過のメッシュは 400 で拒否されます — まずRemeshを実行してください。

戻り値

レスポンスの result プロパティには、新しく作成されたUV展開タスクの id が含まれます。

失敗モード

  • Name
    400 - Bad Request
    Description

    リクエストは受け入れられませんでした。一般的な原因：

    • パラメータ不足: input_task_id または model_url のいずれかを指定する必要があります。
    • 無効な入力タスク: input_task_id は、GLB結果を持つ成功済みタスクを参照している必要があります。
    • フェイス数超過: ソースメッシュのフェイス数がUV展開の上限を超えています。まずRemeshを実行してください。
    • 無効なモデル形式: model_url が、サポートされていない拡張子のファイルを指しています。
    • 到達不能なURL: model_url をダウンロードできませんでした。
  • Name
    401 - Unauthorized
    Description

    認証に失敗しました。API keyを確認してください。

  • Name
    402 - Payment Required
    Description

    このタスクを実行するためのクレジットが不足しています。UV展開は1回の呼び出しにつき5クレジットかかります。

  • Name
    404 - Not Found
    Description

    この機能はあなたのアカウントで有効になっていません。UV展開はロールアウト中、Statsigフラグによって制限されています — アクセスが必要な場合はMeshyサポートにお問い合わせください。

  • Name
    429 - Too Many Requests
    Description

    レート制限を超過しました。

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"
}
GET/openapi/v1/uv-unwrap/:id

UV 展開タスクを取得する

この endpoint は、ID によって UV 展開タスクの現在の状態を取得します。

戻り値

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

以下のタスクオブジェクトの例を参照してください。

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

UVアンラップタスクを削除

UVアンラップタスクを完全に削除します。タスクとその出力にはアクセスできなくなります。

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}"
GET/openapi/v1/uv-unwrap

UV Unwrapタスクの一覧表示

呼び出し元のUV Unwrapタスクのページ分割された一覧を、新しい順に返します。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 アンラップタスクをストリーミングする

Server-Sent Events としてタスクの進行状況を購読します。各 message イベントには UV アンラップタスクオブジェクト が含まれます。タスクが 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 アンラップタスクオブジェクト

  • Name
    id
    Type
    string
    Description

    タスクの一意の識別子。

  • Name
    type
    Type
    string
    Description

    常に uv-unwrap。

  • Name
    model_urls
    Type
    object
    Description

    生成された UV ホワイトモデルの署名付きダウンロード URL。UV Unwrap は常に単一の glb エントリを返します。出力は入力ジオメトリを保持し、新しい UV 座標に差し替え、texture の代わりにデフォルトのグレーのマテリアルを使用します。

  • 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 オブジェクトリファレンスについては、Errors を参照してください。

  • Name
    consumed_credits
    Type
    integer
    Description

    このタスクで消費されたクレジット。FAILED タスクでは 0 を返します（失敗時にはクレジットが返還されます）。UV Unwrap は成功時に 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
}