Text to Motion API

自然言語による説明からキャラクターのモーションクリップを生成します。「手を振るキャラクター」「よろめきながら前進するゾンビ」といった動作を記述すると、独自のパイプラインやDCCツールでリギング済みキャラクターにリターゲットできる、生のモーションクリップが得られます。

出力はスタンドアロンのモーションクリップであり、キャラクターモデルを必要とせず、キャラクターモデルに紐付けられることもありません。まずキャラクターに骨骼绑定を行うには、Rigging API を参照してください。生成したクリップをリギング済みキャラクターに適用するには、タスクの id を motion_task_id として Animation API に渡してください — これは3日間のアセット保持期間内に適用する必要があります。

POST/openapi/v1/text-to-motion

Text to Motionタスクを作成する

このエンドポイントは、テキストのpromptからモーションクリップを生成する新しいタスクを作成します。

modeがprimeのタスクは10クレジットを消費し、最高品質のモーションモデルで生成します。modeがswiftのタスクは3クレジットを消費し、より高速で経済的なモーションモデルで生成します。

パラメータ

Name
prompt
Type
string
必須
Description
生成するモーションの自然言語による説明です。最大400文字です。
Name
mode
Type
string
デフォルト prime
Description
モーション生成のmodeです。利用可能な値: prime、swift。primeは最高品質で生成し、FBXを出力します。swiftはより高速で低コストであり、BVHを出力します。
Name
duration
Type
number
必須
Description
生成するモーションクリップの目標時間(秒)です。2から10の間で、0.5刻みで指定します(例: 2、2.5、3、…10)。

返り値

レスポンスの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キーを確認してください。
Name
402 - Payment Required
Description
このタスクを実行するためのクレジットが不足しています。
Name
403 - Forbidden
Description
promptがコンテンツmoderationによってフラグされました。
Name
429 - Too Many Requests
Description
レート制限を超過しました。

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

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

Text to Motion タスクを取得

このエンドポイントでは、有効なタスク id を指定して Text to Motion タスクを取得できます。含まれるプロパティについては、Text to Motion タスクオブジェクトを参照してください。

パラメータ

Name
id
Type
path
Description
取得する Text to Motion タスクの一意の識別子。

戻り値

レスポンスには Text to Motion タスクオブジェクトが含まれます。詳細は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
}

GET/openapi/v1/text-to-motion

テキストからモーションへのタスク一覧の取得

呼び出し元のText to Motionタスクのページネーションされたリストを、新しい順に返します。page_numとpage_sizeによる標準的なページネーションが使用されます。

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

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 タスクをストリーミングする

このエンドポイントは、Server-Sent Events（SSE）を使用して Text to Motion タスクのリアルタイム更新をストリーミングします。

パラメータ

Name
id
Type
path
Description
ストリーミング対象の Text to Motion タスクの一意の識別子です。

戻り値

The Text to Motion Task Objects のストリームを Server-Sent Events として返します。

すべての message イベントには完全なタスクオブジェクトが含まれます。タスクが PENDING または IN_PROGRESS の間、result フィールドはまだ空（"" / 0）であり、finished_at / expires_at は 0 です。status と progress を監視してください。

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 stream item, mirroring The Text to Motion Task Object structure
  "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
}

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

Text to Motion タスクを削除する

このエンドポイントは、生成されたモーションクリップを含め、Text to Motion タスクを完全に削除します。この操作は元に戻せません。

パスパラメータ

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

戻り値

成功時には 200 OK を返します。

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

// Returns 200 Ok on success.

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

Text to Motion タスクオブジェクトは、テキストの prompt からモーションクリップを生成するための作業単位を表します。

プロパティ

Name
id
Type
string
Description
タスクの一意の識別子。
Name
type
Type
string
Description
タスクの種類。値は text-to-motion です。
Name
status
Type
string
Description
タスクのステータス。可能な値: PENDING、IN_PROGRESS、SUCCEEDED、FAILED、CANCELED。
Name
progress
Type
integer
Description
タスクの progress（0～100）。
Name
created_at
Type
timestamp
Description
タスクが作成されたタイムスタンプ（エポックからのミリ秒数）。
タイムスタンプは、RFC 3339 標準に従って、 1970年1月1日 UTC からの経過ミリ秒数を表します。例えば、2023年9月1日金曜日 12:00:00 PM GMT は 1693569600000 と表されます。これは Meshy API 内の すべて のタイムスタンプに適用されます。
Name
started_at
Type
timestamp
Description
タスクの処理が開始されたタイムスタンプ（エポックからのミリ秒数）。開始されていない場合は 0。
Name
finished_at
Type
timestamp
Description
タスクが完了したタイムスタンプ（エポックからのミリ秒数）。完了していない場合は 0。
Name
expires_at
Type
timestamp
Description
タスクの結果アセットが期限切れになるタイムスタンプ（エポックからのミリ秒数）。タスクが完了するまでは 0。生成されたクリップはタスク完了後3日間保持されます。期限切れになる前にダウンロードしてください。
Name
preceding_tasks
Type
integer
Description
キュー内の先行タスクの数。ステータスが PENDING の場合のみ意味を持ち、値が0の場合は省略されます。
Name
consumed_credits
Type
integer
Description
このタスクによって消費されたクレジット数。prime mode では 10、swift mode では 3。FAILED タスクの場合は 0 を返します（失敗時はクレジットが返還されます）。
Name
task_error
Type
object
Description
失敗したタスクのエラー詳細。タスクが FAILED でない限り null。task_error オブジェクトの全リファレンスについてはエラーを参照してください。
Name
result
Type
object
Description
タスクが SUCCEEDED になると、生成されたモーションクリップが含まれます。それまではフィールドは存在しますが空です（"" / 0）。
- Name
  motion_url
  Type
  string
  Description
  生成されたモーションクリップのダウンロード可能な 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
  クリップが生成された mode：prime または swift。

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
}