リギング API

ヒューマノイド3Dモデルにスケルトン（アーマチュア）を追加し、メッシュをバインドして、キャラクターをアニメーション可能な状態にします。リギングされたキャラクターにアニメーションを適用するには、Animation API を参照してください。

リギングは、四肢と胴体の構造が明確に定義された、標準的なヒューマノイド（二足歩行）キャラクターに対してのみ適切に機能します。

POST/openapi/v1/rigging

リギングタスクを作成する

3Dモデルのリギングタスクを作成します。タスクが成功すると、標準形式でリギングされたキャラクターが返され、オプションで基本的な歩行・走行アニメーションも返されます。

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

リギングは以下のようなモデルには適していません：

テクスチャのないメッシュ
人型でないアセット
四肢や体の構造が不明瞭な人型アセット

Request

POST

/openapi/v1/rigging

# Rig a model from a URL
curl https://api.meshy.ai/openapi/v1/rigging \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model_url": "YOUR_MODEL_URL_OR_DATA_URI",
    "height_meters": 1.8
  }'

Response

{
  "result": "018b314a-a1b5-716d-c222-2f1776f7f579"
}

パラメータ

Name
input_task_id
Type
string
必須
Description
model_url を送信しない場合は必須です。リギングしたいモデルを持つタスクのIDです。Meshyはテクスチャ付きの人型モデルをサポートしています。
モデルは最大380,000三角形まで対応しています（四角形は2としてカウントされます）。これを超えるモデルは 400 を返します。この上限を超えないようにするには、まずRemesh APIを target_polycount を 300000 以下に設定して実行するか、topology: quad の場合は 150000 以下に設定して実行してください。

Name
model_url
Type
string
必須
Description
input_task_id を送信しない場合は必須です。リギングするモデルを、公開URLまたはData URIとして指定します。両方を送信した場合、Meshyは input_task_id を使用します。
モデルは、http または https のURLからの場合は最大400MB、Data URIの場合は最大100MBのGLB（.glb）ファイルである必要があります。リギングはテクスチャ付きの人型モデルをサポートしています。
モデルは最大380,000三角形まで対応しています（四角形は2としてカウントされます）。これを超えるモデルは 400 を返します。この上限を超えないようにするには、まずRemesh APIを target_polycount を 300000 以下に設定して実行するか、topology: quad の場合は 150000 以下に設定して実行してください。
キャラクターの顔は、glTFの標準の正面方向である+Z軸を向いている必要があります。別の軸を向いているモデルでは、ポーズ推定が失敗します。
100MBを超えるファイルは、さらに以下のルールにも従う必要があります：
- 面の数は最大10,000,000までです。これを超えるファイルは 400 を返します。Meshyは面を三角形としてカウントし、複数回描画されるメッシュはコピーごとに1回としてカウントします。
- Draco圧縮を使用してはいけません。

Name
height_meters
Type
number
デフォルト 1.7
Description
キャラクターのおおよその身長（メートル単位）です。Meshyはこれを使ってモデルのスケーリングとリギングをより正確に行います。負の値を指定すると 400 が返されます。
Name
texture_image_url
Type
string
⚠ 非推奨
Description
モデルが独自のテクスチャを持っている場合は指定しないでください。指定しない場合、Meshyは model_url ファイルに埋め込まれたテクスチャ、または入力タスクのテクスチャを使用します。これを送信すると、この画像がリギングされたモデルの唯一のテクスチャとなり、モデルはPBRマップを失います。
モデルのUV展開されたベースカラーテクスチャを、公開URLまたはData URIとして指定します。画像は最大20MBのPNGファイルである必要があります。他の画像形式を指定すると 400 が返されます。

戻り値

レスポンスの result フィールドには、新しく作成されたリギングタスクのIDが格納されます。

失敗モード

Name
400 - Bad Request
Description
リクエストを実行できません。エラーメッセージには検出された問題が示されます。例：
- パラメータが不足している：model_url と input_task_id のどちらも送信されていません。
- モデル形式が無効：model_url のファイルがサポートされていない拡張子です。.glb のみサポートされています。
- 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を超えており、そのヘッダーに確認すべきメッシュ、ノード、またはレコードが多すぎます。ファイル内のオブジェクト数を減らしてから、再送信してください。
- 画像が大きすぎる：texture_image_url の画像が20MBを超えています。
- テクスチャ形式が無効：texture_image_url の画像がPNGファイルではありません。
- 身長が無効：height_meters が負の値です。
- 入力タスクが無効：input_task_id が有効なAPIタスクを参照していません。
- 面数の上限超過：入力モデルが380,000三角形を超えています（四角形は2としてカウントされます）。モデルをリギングする前に、target_polycount を 300000 以下に設定するか、topology: quad の場合は 150000 以下に設定してRemesh APIを実行してください。
リクエストを修正してから、再送信してください。エラーを参照してください。
Name
401 - Unauthorized
Description
APIキーが指定されていないか、無効です。Authorization ヘッダーを確認してください。
Name
402 - Payment Required
Description
例：
- クレジット不足：アカウントにこのタスクを実行するための十分なクレジットがないか、アカウントがクレジットの上限に達しています。クレジット残高を確認してから、再試行してください。
- 無料プラン：タスクを作成するには有料プランが必要です。サブスクリプション設定でプランをアップグレードしてから、再試行してください。
Name
403 - Forbidden
Description
input_task_id がバスレリーフモデルであり、このエンドポイントではリギングできません。メッセージは This model type does not support this operation です。別のモデルを送信してください。
Name
422 - Unprocessable Entity
Description
ポーズ推定が失敗しました。モデルが有効な人型キャラクターではない可能性があります。人型キャラクターのモデルを送信してください。model_url の場合は、キャラクターが+Z軸を向いているかも確認してください。
Name
429 - Too Many Requests
Description
レート制限を超過しました。しばらく待ってから、再試行してください。レート制限を参照してください。

GET/openapi/v1/rigging/:id

リギングタスクを取得する

IDを指定してリギングタスクを返します。

Request

GET

/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579

curl https://api.meshy.ai/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "type": "rig",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5,
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.fbx?Expires=...",
    "rigged_character_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.glb?Expires=...",
    "basic_animations": {
      "walking_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.glb?Expires=...",
      "walking_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.fbx?Expires=...",
      "walking_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin_armature.glb?Expires=...",
      "running_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.glb?Expires=...",
      "running_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.fbx?Expires=...",
      "running_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin_armature.glb?Expires=..."
    }
  },
  "preceding_tasks": 0
}

パラメータ

Name
id
Type
path
Description
作成時のレスポンスに含まれるタスクIDです。

戻り値

リギングタスクオブジェクト。

DELETE/openapi/v1/rigging/:id

リギングタスクを削除する

リギングタスクを、そのモデルやデータも含めて完全に削除します。削除を取り消すことはできません。

Request

DELETE

/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS. The task keeps running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

パスパラメータ

Name
id
Type
path
Description
削除するタスクのID。

タスクのステータス

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

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

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

返り値

タスクが削除された場合は 200 OK、タスクが IN_PROGRESS の場合は 409 Conflict を返します。

GET/openapi/v1/rigging

リギングタスクの一覧取得

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

APIで作成したタスクはAPI内にとどまり、ウェブアプリのMy Assetsには表示されません。IDが分からなくなったタスクを見つけるには、このエンドポイントを使用してください。

Request

GET

/openapi/v1/rigging

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

GET/openapi/v1/rigging/:id/stream

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

リギングタスクの更新情報を、Server-Sent Events（SSE）としてストリーミングします。

Request

GET

/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579/stream

curl -N https://api.meshy.ai/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// These examples are shortened. Each event holds the full task object.
event: message
data: {
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: { // Example of a SUCCEEDED task event, with the same fields as the Rigging task object
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "type": "rig",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5,
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/.../Character_output.fbx?...",
    "rigged_character_glb_url": "https://assets.meshy.ai/.../Character_output.glb?...",
    "basic_animations": {
      "walking_glb_url": "https://assets.meshy.ai/.../Animation_Walking_withSkin.glb?...",
      "walking_fbx_url": "https://assets.meshy.ai/.../Animation_Walking_withSkin.fbx?...",
      "walking_armature_glb_url": "https://assets.meshy.ai/.../Animation_Walking_withSkin_armature.glb?...",
      "running_glb_url": "https://assets.meshy.ai/.../Animation_Running_withSkin.glb?...",
      "running_fbx_url": "https://assets.meshy.ai/.../Animation_Running_withSkin.fbx?...",
      "running_armature_glb_url": "https://assets.meshy.ai/.../Animation_Running_withSkin_armature.glb?..."
    }
  },
  "preceding_tasks": 0
}

パラメータ

Name
id
Type
path
Description
作成時のレスポンスで返されたタスクIDです。

戻り値

リギングタスクオブジェクトのストリームを、Server-Sent Events として返します。

各イベントは、Getエンドポイントが返すものと同じ形式で、タスクオブジェクト全体を保持します。タスクが PENDING または IN_PROGRESS の間は、結果フィールドにはまだ値がありません。

リギングタスクオブジェクト

リギングタスクオブジェクトは、1体のキャラクターのリギングを表します。ステータス、progress、そしてタスクが成功した際の出力ファイルを保持します。

プロパティ

Example Rigging Task Object

{
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "type": "rig",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5,
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.fbx?Expires=...",
    "rigged_character_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.glb?Expires=...",
    "basic_animations": {
      "walking_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.glb?Expires=...",
      "walking_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.fbx?Expires=...",
      "walking_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin_armature.glb?Expires=...",
      "running_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.glb?Expires=...",
      "running_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.fbx?Expires=...",
      "running_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin_armature.glb?Expires=..."
    }
  },
  "preceding_tasks": 0
}

Name
id
Type
string
Description
タスクID。不透明な文字列として扱い、そのフォーマットに依存しないでください。
Name
type
Type
string
Description
タスクタイプ。常にrigです。
Name
status
Type
string
Description
タスクステータス。PENDING、IN_PROGRESS、SUCCEEDED、FAILED、CANCELEDのいずれかです。
Name
progress
Type
integer
Description
タスクがどれだけ完了しているかをパーセンテージで示します。タスクが開始するまでは0、成功すると100になります。
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
タスクの結果ファイルが期限切れになる時刻（Unixミリ秒）。この時刻を過ぎると、Meshyはファイルを削除する場合があります。
Name
task_error
Type
object
Description
タスクが失敗した場合のエラー詳細。エラーを参照してください。
Name
consumed_credits
Type
integer
Description
タスクで使用されたクレジット数。ステータスがPENDING、IN_PROGRESS、SUCCEEDEDの場合に存在します。FAILEDタスクの場合は0です。これは、タスクが失敗した場合にMeshyがクレジットを払い戻すためです。
Name
result
Type
object
Description
出力ファイルのURL。タスクが成功するまでは、各URLは空文字列であり、basic_animationsはnullです。
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  FBXファイルとしてリギングされたキャラクターのダウンロードURL。
- Name
  rigged_character_glb_url
  Type
  string
  Description
  GLBファイルとしてリギングされたキャラクターのダウンロードURL。
- Name
  basic_animations
  Type
  object (optional)
  Description
  デフォルトの歩行アニメーションと走行アニメーションのダウンロードURL。
  Name
  walking_glb_url
  Type
  string
  Description
  スキン付きの歩行アニメーション（GLBファイル）。
  Name
  walking_fbx_url
  Type
  string
  Description
  スキン付きの歩行アニメーション（FBXファイル）。
  Name
  walking_armature_glb_url
  Type
  string
  Description
  歩行アニメーションのアーマチュア（GLBファイル）。
  Name
  running_glb_url
  Type
  string
  Description
  スキン付きの走行アニメーション（GLBファイル）。
  Name
  running_fbx_url
  Type
  string
  Description
  スキン付きの走行アニメーション（FBXファイル）。
  Name
  running_armature_glb_url
  Type
  string
  Description
  走行アニメーションのアーマチュア（GLBファイル）。
Name
preceding_tasks
Type
integer
Description
キュー内でこのタスクより前にあるタスクの数。この値は、タスクがPENDINGの間のみ意味を持ちます。