Text to Motion API

テキストによる説明からキャラクターのモーションクリップを生成します。「手を振るキャラクター」や「よろよろと前進するゾンビ」のようなアクションを記述すると、生のモーションクリップが得られます。このクリップは、あなた自身のパイプラインやDCCツール内でリグ付きキャラクターにリターゲットできます。

出力はスタンドアロンのモーションクリップです。キャラクターモデルを必要とせず、特定のモデルに紐付けられてもいません。まずキャラクターにリグを追加するには、Rigging APIを参照してください。クリップをリグ付きキャラクターに適用するには、タスクのidをmotion_task_idとしてAnimation APIに送信してください。

POST/openapi/v1/text-to-motion

Text to Motionタスクを作成する

Text to Motionタスクを作成します。テキストのpromptからモーションクリップを生成します。

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

primeタスクは10クレジットを消費し、Meshyの高品質なモーションモデルを使用します。swiftタスクは3クレジットを消費し、より高速で低コストなモーションモデルを使用します。

Request

POST

/openapi/v1/text-to-motion

# Generate a motion clip with required params only
curl https://api.meshy.ai/openapi/v1/text-to-motion \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "a character waving",
    "duration": 3
  }'

# Generate a fast, economical clip with Swift mode
curl https://api.meshy.ai/openapi/v1/text-to-motion \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "a character waving",
    "mode": "swift",
    "duration": 4.5
  }'

Response

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

パラメータ

Name
prompt
Type
string
必須
Description
生成するモーションを説明するテキストで、最大400文字です。これより長いテキストは400を返します。
Name
mode
Type
string
デフォルト prime
Description
モーションモデルを指定します。これはクリップのファイル形式も決定します。
利用可能な値:
- prime: 高品質、FBXクリップを返す
- swift: 高速かつ低コスト、BVHクリップを返す
それ以外の値を指定すると400が返されます。
Name
duration
Type
number
必須
Description
目標とするクリップの長さを秒単位で指定します。2から10の範囲で0.5刻みで指定でき、例えば2、2.5、3などです。それ以外の値を指定すると400が返されます。

戻り値

レスポンスのresultフィールドには、新しく作成されたText to Motionタスクのidが格納されます。

失敗モード

Name
400 - Bad Request
Description
リクエストを実行できません。エラーメッセージには検出された問題が示されます。例:
- promptが欠落または空: promptが欠落している、空である、または400文字を超えています。
- 無効なmode: modeがprimeまたはswiftのいずれでもありません。
- 無効なduration: durationが欠落している、2から10の範囲外である、または0.5秒刻みになっていません。
リクエストを修正して、再度送信してください。エラーを参照してください。
Name
401 - Unauthorized
Description
APIキーが欠落しているか無効です。Authorizationヘッダーを確認してください。
Name
402 - Payment Required
Description
例:
- クレジット不足: アカウントにこのタスクを実行するための十分なクレジットがないか、アカウントがクレジット上限に達しています。クレジット残高を確認してから再試行してください。
- 無料プラン: タスクの作成には有料プランが必要です。サブスクリプション設定でプランをアップグレードしてから再試行してください。
Name
403 - Forbidden
Description
コンテンツのmoderationによってpromptがフラグ付けされました。promptを変更して、リクエストを再度送信してください。
Name
429 - Too Many Requests
Description
レート制限を超過しました。しばらく待ってから再試行してください。レート制限を参照してください。

GET/openapi/v1/text-to-motion/:id

Get a Text to Motion task

指定したIDのText to Motionタスクを返します。

Request

GET

/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791

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

Response

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "text-to-motion",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1787314497437,
  "started_at": 1787314498012,
  "finished_at": 1787314505881,
  "expires_at": 1787573705881,
  "task_error": null,
  "result": {
    "motion_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/clip.fbx?Expires=...",
    "motion_format": "fbx",
    "duration_ms": 3000,
    "mode": "prime"
  },
  "consumed_credits": 10
}

パラメータ

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

戻り値

Text to Motion タスクオブジェクト。

GET/openapi/v1/text-to-motion

Text to Motionタスク一覧を取得

お客様のText to Motionタスクのページネーションされたリストを、新しい順に返します。リストをページ送りするには、page_numとpage_sizeを使用してください。

レスポンスはText to Motionタスクオブジェクトの配列です。

APIで作成したタスクはAPI内に保持され、ウェブアプリのMy Assetsには表示されません。IDを紛失したタスクを見つけるには、このエンドポイントを使用してください。

Request

GET

/openapi/v1/text-to-motion

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

Response

[
  {
    "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
    "type": "text-to-motion",
    "status": "SUCCEEDED",
    "...": "..."
  }
]

GET/openapi/v1/text-to-motion/:id/stream

Text to Motion タスクをストリーミングする

Text to Motion タスクの更新を Server-Sent Events (SSE) としてストリーミングします。

Request

GET

/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791/stream

curl -N https://api.meshy.ai/openapi/v1/text-to-motion/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 events carry the full task object at every stage; the result
// fields stay empty until the task succeeds.
event: message
data: {
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "text-to-motion",
  "status": "IN_PROGRESS",
  "progress": 50,
  "created_at": 1787314497437,
  "started_at": 1787314498012,
  "finished_at": 0,
  "expires_at": 0,
  "task_error": null,
  "result": {
    "motion_url": "",
    "motion_format": "",
    "duration_ms": 0,
    "mode": ""
  },
  "consumed_credits": 10
}

event: message
data: { // Example of a SUCCEEDED task event, with the same fields as the Text to Motion task object
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "text-to-motion",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1787314497437,
  "started_at": 1787314498012,
  "finished_at": 1787314505881,
  "expires_at": 1787573705881,
  "task_error": null,
  "result": {
    "motion_url": "https://assets.meshy.ai/.../output/clip.fbx?Expires=...",
    "motion_format": "fbx",
    "duration_ms": 3000,
    "mode": "prime"
  },
  "consumed_credits": 10
}

パラメータ

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

戻り値

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

すべての message イベントはタスクオブジェクト全体を含みます。タスクが PENDING または IN_PROGRESS の間、result フィールドは空（"" または 0）であり、finished_at と expires_at は 0 です。タスクの進行状況を追うには、status と progress を確認してください。

DELETE/openapi/v1/text-to-motion/:id

Text to Motionタスクを削除する

Text to Motionタスクを、そのモーションクリップを含めて完全に削除します。削除を取り消すことはできません。

Request

DELETE

/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791 \
  -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が返されます。

Text to Motionタスクオブジェクト

Text to Motionタスクオブジェクトは、1つのモーションクリップの生成を表します。タスクが成功すると、ステータス、progress、クリップを保持します。

プロパティ

Example Text to Motion Task Object

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "text-to-motion",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1787314497437,
  "started_at": 1787314498012,
  "finished_at": 1787314505881,
  "expires_at": 1787573705881,
  "task_error": null,
  "result": {
    "motion_url": "https://assets.meshy.ai/.../output/clip.fbx?Expires=...",
    "motion_format": "fbx",
    "duration_ms": 3000,
    "mode": "prime"
  },
  "consumed_credits": 10
}

Name
id
Type
string
Description
タスクID。不透明な文字列として扱い、その形式に依存しないでください。
Name
type
Type
string
Description
タスクタイプ。常に text-to-motion です。
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ミリ秒）。タスクが完了するまでは 0 です。Meshyはタスク完了後3日間クリップを保持するため、それまでにダウンロードしてください。
Name
preceding_tasks
Type
integer
Description
キュー内でこのタスクより前にあるタスクの数。この値はタスクが PENDING の間のみ意味を持ちます。値が 0 の場合、このフィールドは省略されます。
Name
consumed_credits
Type
integer
Description
タスクが使用したクレジット数。prime modeの場合は 10、swift modeの場合は 3 です。FAILED タスクの場合は 0 です。これは、タスクが失敗した場合にMeshyがクレジットを返金するためです。
Name
task_error
Type
object
Description
タスクが失敗した場合のエラー詳細。それ以外の場合は null です。エラーを参照してください。
Name
result
Type
object
Description
タスクが成功した場合に生成されるモーションクリップ。それまでは、フィールドは存在しますが空（"" または 0）です。
- Name
  motion_url
  Type
  string
  Description
  モーションクリップのダウンロードURL。Meshyは読み取りのたびにURLに再度署名を行い、タスクの保持期間が過ぎるとURLは期限切れになります。
- Name
  motion_format
  Type
  string
  Description
  クリップのファイル形式。prime modeの場合は fbx、swift modeの場合は bvh です。
- Name
  duration_ms
  Type
  integer
  Description
  クリップの長さ（ミリ秒）。
- Name
  mode
  Type
  string
  Description
  クリップの生成にMeshyが使用したmode。prime または swift です。