テキストからモーションへのAPI

自然言語による説明からキャラクターモーションクリップを生成します。アクションを説明してください — 「キャラクターが手を振る」、「ゾンビが前進している」 — すると、あなたのパイプラインやDCCツールでリグされたキャラクターに向けてリターゲットできる生のモーションクリップを受取ります。

この出力はスタンドアロンのモーションクリップであり、キャラクターモデルを必要とせず、またはそれに添付されません。キャラクターを最初にリグするには、リギングAPIをご覧ください。

POST/openapi/v1/text-to-motion

テキストからモーションタスクを作成する

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

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

パラメーター

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

リターン

応答のresultプロパティには、新しく作成されたテキストからモーションタスクのidが含まれています。

失敗モード

Name
400 - Bad Request
Description
要求は受け入れることができませんでした。一般的な原因:
- プロンプトが不足または空: promptが不足している、空白である、または400文字を超えている。
- 無効なモード: modeがprimeまたはswiftでない。
- 無効な期間: durationが不足している、2–10の範囲外である、または0.5秒のステップになっていない。
Name
401 - Unauthorized
Description
認証に失敗しました。API keyを確認してください。
Name
402 - Payment Required
Description
このタスクを実行するためのクレジットが不足しています。
Name
403 - Forbidden
Description
プロンプトがコンテンツmoderationによってフラグ付けされました。
Name
429 - Too Many Requests
Description
レート制限を超過しました。

Request

POST

/openapi/v1/text-to-motion

# 必須パラメーターのみでモーションクリップを生成する
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
  }'

# 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

テキストからモーションへのタスクを取得する

このエンドポイントを使用すると、有効なタスクidを指定してテキストからモーションへのタスクを取得できます。テキストからモーションへのタスクオブジェクトをご参照ください、どのプロパティが含まれているか確認できます。

パラメータ

Name
id
Type
path
Description
取得するテキストからモーションへのタスクのユニークな識別子。

返却値

レスポンスにはテキストからモーションへのタスクオブジェクトが含まれています。テキストからモーションへのタスクオブジェクトセクションを参照してください。

リクエスト

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

レスポンス

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

テキストからモーションへのタスクを一覧表示

発信者の最新のテキストからモーションへのタスクのページネーションされたリストを返します。page_num と page_size を使用した標準的なページネーション。

レスポンスはテキストからモーションタスクオブジェクトの配列です。

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

リクエスト

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

レスポンス

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

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

テキストからモーションタスクをストリームする

このエンドポイントは、サーバー送信イベント (SSE) を使用してテキストからモーションタスクに対するリアルタイムの更新をストリームします。

パラメータ

Name
id
Type
path
Description
ストリームするテキストからモーションタスクの一意の識別子。

戻り値

サーバー送信イベントとして、テキストからモーションタスクオブジェクトのストリームを返します。

すべての 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

// エラーイベントの例
event: error
data: {
  "status_code": 404,
  "message": "タスクが見つかりません"
}

// メッセージイベントは、各ステージで完全なタスクオブジェクトを運びます。タスクが成功するまで、結果フィールドは空のままです。
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: { // 成功したタスクストリーム項目の例で、テキストからモーションタスクオブジェクトの構造を反映
  "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

テキストからモーションへのタスクを削除する

このエンドポイントは、テキストからモーションへのタスクを永久に削除し、生成されたモーションクリップも含まれます。この操作は元に戻せません。

パスパラメーター

Name
id
Type
path
Description
削除するテキストからモーションへのタスクの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

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

テキストからモーションへのタスクオブジェクト

テキストプロンプトからモーションクリップを生成する作業単位を表します。

プロパティ

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
タスクの進捗（0-100）。
Name
created_at
Type
timestamp
Description
タスクが作成された時刻（エポックからのミリ秒）。
タイムスタンプは、1970年1月1日UTCから経過したミリ秒数を表し、 RFC 3339 標準に従います。例えば、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 の場合にのみ意味があります。ゼロの場合は省略されます。
Name
consumed_credits
Type
integer
Description
このタスクによって消費されたクレジットの数。prime モードでは 10、swift モードでは 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 モードでは fbx、swift モードでは bvh。
- Name
  duration_ms
  Type
  integer
  Description
  生成されたクリップの持続時間（ミリ秒）。
- Name
  mode
  Type
  string
  Description
  クリップが生成されたモード：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
}