アニメーション API

リグ付きキャラクターにアニメーションを適用したり、適用可能なアニメーションの一覧を取得したりできます。

POST/openapi/v1/animations

アニメーションタスクを作成する

アニメーションタスクを作成します。このタスクは、事前にリギングしたキャラクターにアニメーションを適用します。アニメーションには以下のいずれかを使用できます。

アニメーションライブラリのプリセットアクション（action_id）
複数のプリセットアクションを1つのファイルにまとめたもの（action_ids）
Text to Motion APIで生成したモーションクリップ（motion_task_id）

出力を後処理することもできます。タスクはバックグラウンドで実行されます。タスクに通常かかる時間については、処理時間を参照してください。

Request

POST

/openapi/v1/animations

# Animate a rigged model with required params only
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579",
    "action_id": 92
  }'

# Apply several preset actions and get one file with one clip per action
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579",
    "action_ids": [10, 25, 92]
  }'

# Apply a generated Text to Motion clip instead of a preset action
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579",
    "motion_task_id": "018c425b-b2c6-727e-d333-3c1887i9h791"
  }'

# With post-processing to change FPS
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579",
    "action_id": 92,
    "post_process": {
      "operation_type": "change_fps",
      "fps": 24
    }
  }'

Response

{
  "result": "018c425b-b2c6-727e-d333-3c1887i9h791"
}

パラメータ

Name
rig_task_id
Type
string
必須
Description
アニメーションを適用するキャラクターのRiggingタスクのID。POST /openapi/v1/riggingから取得します。このタスクはステータスがSUCCEEDEDである必要があります。

action_id、action_ids、motion_task_idのうち、必ず1つだけを送信してください。

Name
action_id
Type
integer
必須
Description
action_idsまたはmotion_task_idを送信しない場合は必須です。適用するプリセットアニメーションのID。アニメーションの全一覧については、アニメーションライブラリのリファレンス、またはアニメーション一覧の取得を参照してください。

Name
action_ids
Type
array of integers
必須
Description
action_idまたはmotion_task_idを送信しない場合は必須です。一度に適用する1〜10個のプリセットアニメーションのID（重複不可）。IDが10個を超える場合、またはIDが重複している場合は400が返されます。IDについては、アニメーションライブラリのリファレンスを参照してください。
Meshyは、アクションごとに1つのアニメーションクリップを持つ1つのファイルを返します。これはゲームエンジンのステートマシンに適しています。Meshyはリスト内の各アクションに対して課金します。料金を参照してください。
IDを1つだけ含むリストは、そのIDをaction_idとして送信するのと同じ動作をします。

Name
motion_task_id
Type
string
必須
Description
action_idまたはaction_idsを送信しない場合は必須です。プリセットアクションの代わりに適用するText to MotionタスクのクリップのID。このタスクはステータスがSUCCEEDEDである必要があり、リグは二足歩行型である必要があります。
Meshyはクリップをリグ済みキャラクターにリターゲットします。このタスクを作成する際にクリップがコピーされるため、Text to Motionタスクが後で期限切れになったり削除されたりしても、このタスクには影響しません。MeshyはText to Motionタスクのファイルを3日間保持するため、その期間内にクリップを適用してください。

Name
post_process
Type
object
Description
アニメーション出力の後処理。省略すると標準のアニメーションファイルが得られます。
motion_task_idを使用する場合、リターゲットの結果はGLBのみのアニメーションになることがあります。post_processを送信してもFBXファイルが利用できない場合、タスクはtask_errorで失敗し、Meshyはクレジットを返金します。post_processを指定しない場合、タスクは成功し、animation_fbx_urlは空になります。

次の場合のみ適用 post_process is set

Name
operation_type
Type
string
Description
実行する操作。指定しない場合、Meshyは追加のファイルを作成しません。以下の一覧にない値を指定すると400が返されます。
利用可能な値：
- change_fps：フレームレートをfpsに変更します
- fbx2usdz：アニメーションをUSDZに変換します
- extract_armature：アーマチュアをFBXファイルとして抽出します
Name
fps
Type
integer
デフォルト 30
Description
変更後のフレームレート。24、25、30、60のいずれかです。operation_typeがchange_fpsの場合にのみ適用されます。これら以外の値を指定すると400が返されます。

action_idsを使用する場合、タスクはアクションごとに1つのファイルではなく、1つのマージされたファイルを返します。animation_glb_urlとanimation_fbx_urlはそれぞれ、要求されたすべてのアクションを個別のクリップとして保持する1つのファイルを指します。そのファイル内では、

クリップの順序：IDの数値順ではなく、action_ids配列の順序です。
クリップ名：ライブラリ内のアニメーション名です。これは、Meshyウェブアプリでキャラクターのすべてのアニメーションを1つのファイルとしてエクスポートした場合に得られる名前と一致します。要求された2つのIDが同じクリップ名を持つ場合、Meshyは名前を一意に保つため、後の方にaction_idを追加します。
後処理：Meshyは各クリップではなく、マージされたファイルに対して後処理を適用します。

戻り値

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

失敗モード

Name
400 - Bad Request
Description
リクエストを実行できません。エラーメッセージには、検出された問題が示されます。例：
- パラメータの欠落：rig_task_idが欠落しているか、action_id、action_ids、motion_task_idのいずれも送信されていません。
- パラメータの競合：リクエストにaction_id、action_ids、motion_task_idのうち複数が含まれています。1つだけ送信してください。
- 無効なrigタスク：rig_task_idが有効なタスクIDではない、Riggingタスクではない、または成功していないタスクを指しています。
- 無効なアクションID：action_id、またはaction_ids内のいずれかのエントリが、有効なアニメーションではありません。
- アクションが多すぎる：action_idsに10個を超えるIDが含まれています。
- アクションの重複：action_idsに同じIDが複数回含まれています。
- モーションタスクが準備未完了：motion_task_idのタスクがまだSUCCEEDEDに達していません。
- サポートされていないrig：motion_task_idには二足歩行型のrigが必要であり、Meshyは四足歩行型のrigを拒否します。
リクエストを修正してから、再度送信してください。エラーを参照してください。
Name
401 - Unauthorized
Description
APIキーが欠落しているか、無効です。Authorizationヘッダーを確認してください。
Name
402 - Payment Required
Description
例：
- クレジット不足：アカウントにこのタスクを実行するのに十分なクレジットがないか、アカウントがクレジット上限に達しています。クレジット残高を確認してから、再試行してください。
- 無料プラン：タスクの作成には有料プランが必要です。サブスクリプション設定でプランをアップグレードしてから、再試行してください。
Name
403 - Forbidden
Description
rig_task_idのタスクが浮き彫り（bas-relief）モデルであり、このエンドポイントではアニメーション化できません。メッセージはThis model type does not support this operationです。別のモデルをリギングしてください。
Name
404 - Not Found
Description
Meshyはリクエストに必要なタスクまたはファイルを見つけられません。以下のいずれかが該当します。
- Meshyはあなたのタスクの中からrig_task_idのタスクを見つけられません。IDを確認してください。
- Meshyはexpires_atを過ぎた後、rig_task_idのタスクのファイルを削除しました。キャラクターを再度リギングしてください。
- Meshyはmotion_task_idのタスクを見つけられません。IDを確認してください。
- Meshyは Text to Motionタスクのファイルを3日間保持するため、モーションクリップの期限が切れています。別のText to Motionタスクを作成してください。
Name
429 - Too Many Requests
Description
レート制限を超えました。しばらく待ってから再試行してください。レート制限を参照してください。

GET/openapi/v1/animations/:id

アニメーションタスクを取得する

IDを指定してAnimationタスクを返します。

Request

GET

/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791

curl https://api.meshy.ai/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "animate",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 3,
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/Animation_Reaping_Swing_withSkin.glb?Expires=...",
    "animation_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/Animation_Reaping_Swing_withSkin.fbx?Expires=...",
    "processed_usdz_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/processed.usdz?Expires=...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/processed_armature.fbx?Expires=...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/processed_60fps.fbx?Expires=..."
  },
  "preceding_tasks": 0
}

パラメータ

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

返り値

Animationタスクオブジェクト。

DELETE/openapi/v1/animations/:id

Animationタスクを削除

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

Request

DELETE

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

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/animations/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/animations

Animationタスク一覧の取得

お使いのAnimationタスクのページネーションされた一覧を、新しいものから順に返します。一覧をページ送りするには、page_num と page_size を使用します。

API経由で作成したタスクは、ウェブアプリの My Assets には表示されないため、APIを通じて管理する必要があります。IDが分からなくなったタスクを見つけるには、このエンドポイントを使用してください。

Request

GET

/openapi/v1/animations

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

GET/openapi/v1/animations/:id/stream

Animationタスクをストリーミング

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

Request

GET

/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791/stream

curl -N https://api.meshy.ai/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791/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": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: { // Example of a SUCCEEDED task stream item, with the same structure as the Animation task object
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "animate",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 3,
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.glb?...",
    "animation_fbx_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.fbx?...",
    "processed_usdz_url": "https://assets.meshy.ai/.../processed.usdz?...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/.../processed_armature.fbx?...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/.../processed_60fps.fbx?..."
  },
  "preceding_tasks": 0
}

パラメータ

Name
id
Type
path
Description
作成レスポンスから取得したタスクID。

戻り値

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

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

アニメーションタスクオブジェクト

アニメーションタスクオブジェクトは、リギングされたキャラクターに適用される1つのアニメーションを記述します。タスクが成功すると、ステータス、progress、アニメーションファイルを保持します。

プロパティ

Example Animation Task Object

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "animate",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 3,
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.glb?...",
    "animation_fbx_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.fbx?...",
    "processed_usdz_url": "https://assets.meshy.ai/.../processed.usdz?...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/.../processed_armature.fbx?...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/.../processed_60fps.fbx?..."
  },
  "preceding_tasks": 0
}

Name
id
Type
string
Description
タスクID。不透明な文字列として扱い、そのフォーマットに依存しないでください。
Name
type
Type
string
Description
タスクタイプ。常に animate です。
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ミリ秒）。
Name
task_error
Type
object
Description
タスクが失敗した場合のエラー詳細。エラーを参照してください。
Name
consumed_credits
Type
integer
Description
タスクが使用したクレジット数。ステータスが PENDING、IN_PROGRESS、SUCCEEDED の場合に存在します。FAILED のタスクでは 0 になります。これは、タスクが失敗した場合、Meshyがクレジットを払い戻すためです。
Name
result
Type
object
Description
タスクのステータスが SUCCEEDED のとき、アニメーションファイルのダウンロードURL。
- Name
  animation_glb_url
  Type
  string
  Description
  GLBファイルとしてのアニメーション。action_ids で作成されたタスクの場合、このファイル1つにリクエストされたすべてのアクションが個別のクリップとして格納されます。
- Name
  animation_fbx_url
  Type
  string
  Description
  FBXファイルとしてのアニメーション。action_ids で作成されたタスクの場合、このファイル1つにリクエストされたすべてのアクションが個別のクリップとして格納されます。
- Name
  processed_usdz_url
  Type
  string
  Description
  処理済みアニメーションのUSDZファイル。
- Name
  processed_armature_fbx_url
  Type
  string
  Description
  処理済みアーマチュアのFBXファイル。
- Name
  processed_animation_fps_fbx_url
  Type
  string
  Description
  フレームレートを変更した後のアニメーション（FBXファイル）。例えば change_fps 操作を使用した場合などです。
Name
preceding_tasks
Type
integer
Description
キューの中でこのタスクより前にあるタスクの数。この値はタスクが PENDING の間のみ意味を持ちます。

GET/openapi/v1/animations/library

アニメーション一覧の取得

ライブラリ内のすべてのアニメーションをaction_id順に返します。レスポンスはページ分割のない完全なリストなので、1回の呼び出しでアクションピッカーを埋めることができます。フィルターは結果を絞り込みます。すべてのアニメーションを取得するには、フィルターをすべて省略してください。

同じリストを各アクションのアニメーションプレビュー付きで閲覧するには、アニメーションライブラリのリファレンスを参照してください。

このリクエストにクレジットはかかりません。

Request

GET

/openapi/v1/animations/library

curl "https://api.meshy.ai/openapi/v1/animations/library?category=Fighting" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "action_id": 4,
    "name": "Attack",
    "key": "Attack",
    "category": "Fighting",
    "sub_category": "AttackingwithWeapon",
    "preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Attack.gif"
  },
  {
    "action_id": 92,
    "name": "Double Combo Attack",
    "key": "Double_Combo_Attack",
    "category": "Fighting",
    "sub_category": "AttackingwithWeapon",
    "preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Double_Combo_Attack.gif"
  }
]

パラメータ

Name
search
Type
string
Description
検索するテキストです。Meshyは、大文字小文字を区別せず、nameまたはkeyにこのテキストを含むアニメーションを返します。Meshyはテキストをそのまま一致させるため、%や_はワイルドカードとして扱われません。
Name
category
Type
string
Description
一覧表示するカテゴリを、完全一致で指定します。不明なカテゴリを指定すると、空のリストが返されます。
利用可能な値:
- WalkAndRun
- BodyMovements
- DailyActions
- Fighting
- Dancing
Name
sub_category
Type
string
Description
一覧表示するサブカテゴリを、完全一致で指定します。categoryなしで送信することもできます。サブカテゴリ名はカテゴリをまたいで一意ではありません。例えば、TransitioningはFightingとDailyActionsの両方に存在します。そのためcategoryを指定しない場合、このフィルターはすべてのカテゴリ内のサブカテゴリに一致します。
Name
action_ids
Type
string
Description
返すアニメーションを、カンマ区切りで最大200個のaction_id値として指定します。閲覧する代わりに特定のIDを検索するために使用します。200個を超えるIDを指定すると400が返されます。
レスポンスには、どのアニメーションにも存在しないIDは含まれません。そのため、このフィルターを使って、保存しておいたIDがまだ有効かどうかを確認することもできます。

フィルターの組み合わせ

Meshyはフィルターをまとめて適用します。それぞれが結果を絞り込むため、Meshyはすべてのフィルターに一致する場合にのみアニメーションを返します。1つのフィルター内では、その値のいずれかに一致すれば構いません。例えば、searchはnameまたはkeyに一致し、action_idsはリスト内のいずれかのIDに一致します。

そのため、重なりのない組み合わせはエラーではなく空の配列を返します。アクション92は「Double Combo Attack」というFightingのアニメーションです。例えば：

?action_ids=92&category=Fightingはアクション92を返します。
?action_ids=92&category=Dancingは[]を返します。これはDancingのアニメーションではないためです。
?action_ids=92&search=walkは[]を返します。これは名前がwalkに一致しないためです。

任意のカテゴリから特定のアニメーションを取得するには、action_ids単独で送信してください。

戻り値

アニメーションオブジェクトのリストです。

アニメーションタスクの作成は、このエンドポイントが返すすべてのaction_idを受け付け、このエンドポイントは作成時に受け付けられるすべてのIDを返します。どちらも廃止されたアニメーションは含みません。ライブラリをキャッシュしている場合は、時々更新してください。そうすることで、廃止されたIDがピッカーに残り続けることを防げます。

アニメーションオブジェクト

アニメーションオブジェクトは、ライブラリ内の1つのアニメーションを記述します。

Example Animation Object

{
  "action_id": 92,
  "name": "Double Combo Attack",
  "key": "Double_Combo_Attack",
  "category": "Fighting",
  "sub_category": "AttackingwithWeapon",
  "preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Double_Combo_Attack.gif"
}

Name
action_id
Type
integer
Description
アニメーションタスクを作成する際にaction_idとして送信する値です。これは一意で安定していますが、連続してはいません。廃止されたアニメーションは番号に欠番を残すため、ある範囲内のすべてのIDが有効であると想定しないでください。
Name
name
Type
string
Description
アニメーションの表示名です。一部のアニメーションは別のバリアントと名前を共有しているため、一意ではありません。アニメーションを識別するには、action_idまたはkeyを使用してください。
Name
key
Type
string
Description
アニメーションの一意で安定したスラッグです。自分のストレージのキーとして数値以外のIDが必要な場合に使用してください。
Name
category
Type
string
Description
トップレベルのグループです。例：Fighting
Name
sub_category
Type
string
Description
カテゴリ内のグループです。例：AttackingwithWeapon
Name
preview_url
Type
string
Description
アクションのアニメーションGIFプレビューのURLです。自作のピッカー内で直接表示できます。