Kling V3.0 モーションコントロールは、参照動画からモーションを抽出し、それをフレームごとに適用することで、静止したキャラクター画像をアニメーション化できます。出力は、動画の動きを再現しつつ、画像のキャラクターの外観を保持します。これはモーショントランスファーと呼ばれる技術です。このガイドでは、Novita AI のエンドポイント、必要な入力、主要パラメータ、実際の API キーで実行可能な Python と curl の例を説明します。
モーションコントロールが適したツールである場合
モーションコントロールは、次の2つがある場合に適したツールです。アニメーション化したい静止キャラクター画像と、再現したい動きを持つ参照動画です。これは、プロンプトから動きを生成する Image-to-Video（I2V）とは異なります。モーションコントロールでは、動きは参照動画から正確にコピーされ、出力キャラクターは参照動画内の人物と同じ動きの軌跡をたどります。
次のような場合に使用します：
- 特定のダンス、歩行サイクル、またはジェスチャーをキャラクターのイラストや写真に適用したい場合
- 異なるキャラクター間で一貫性のある再現可能な動きが必要な場合（同じ参照動画、異なる画像）
- 動きの品質が重要で、自由度の高い I2V プロンプト結果が予測不能すぎるコンテンツを構築している場合
動き自体がまだ未定義の場合は使用しないでください。その場合は、説明プロンプトを使用した I2V の方が低コストで柔軟性が高くなります。
ステップ 1: Novita API キーを取得する
novita.ai にサインアップし、ダッシュボードから API キーを生成します。新規アカウントには、本番環境で使用する前にモーションコントロールをテストできる無料クレジットが付与されます。
ステップ 2: エンドポイントとモデル ID を確認する
Novita AI 上の Kling V3.0 モーションコントロールは、標準の非同期ビデオパターンを使用します。
タスクの送信:
POST https://api.novita.ai/v3/async/kling-v3.0-motion-control
結果のポーリング:
GET https://api.novita.ai/v3/async/task-result?task_id={task_id}
すべてのリクエストに以下が必要です：
Authorization: Bearer YOUR_NOVITA_API_KEY
Content-Type: application/json
完全なドキュメント: novita.ai/docs/api-reference/model-apis-kling-v3.0-motion-control
ステップ 3: 入力を準備する
モーションコントロールには、参照画像と参照動画の2つの入力が必要です。これらを適切に準備することが、出力品質の最大の要因です。
参照画像
出力の外観を保持するキャラクターです。要件：
- 形式: JPEG、PNG、JPG
- 最大サイズ: 10 MB
- 最小解像度: 各辺 340px
- アスペクト比: 2:5 ～ 5:2
- キャラクターが明確に見え、画像領域の 5% 以上を占め、大きな遮蔽がないこと（頭部や体を切り取らないでください）
最良の結果を得るには、キャラクターの体のプロポーションが参照動画に表示されているものとおおよそ一致する画像を使用してください。参照動画が全身のダンサーを示している場合は、ポートレートの切り抜きではなく、全身のキャラクター画像を使用してください。
参照動画
これはモーションソースです。出力のキャラクターは、この動画の動きを再現します：
- 形式: MP4、MOV
- 最大サイズ: 10 MB
- 長さ: 3～30秒
- 最小解像度: 各辺 340px
- アスペクト比: 2:5 ～ 5:2
- 参照動画内の人物は、全身または上半身が頭部を含めて見え、遮蔽されていない必要があります
背景がシンプルで明るく照明が当たった映像は、ノイズが多いまたは混雑したショットよりも正確にモーションを転送します。
ステップ 4: 最初のリクエストを送信する
最小限の curl リクエスト：
curl --request POST \
--url https://api.novita.ai/v3/async/kling-v3.0-motion-control \
--header 'Authorization: Bearer $NOVITA_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"image": "https://example.com/character.jpg",
"video": "https://example.com/reference_motion.mp4",
"prompt": "A person performing a smooth dance routine, cinematic lighting",
"model_name": "kling-v3.0-motion-control",
"character_orientation": "video"
}'
応答は即座に task_id を返します：
{
"task_id": "abc123xyz"
}
ステップ 5: 結果をポーリングする
Kling V3.0 モーションコントロールは非同期です。タスクを送信した後、ステータスが succeed になるまでポーリングします：
curl --request GET \
--url 'https://api.novita.ai/v3/async/task-result?task_id=abc123xyz' \
--header 'Authorization: Bearer $NOVITA_API_KEY'
完了すると、応答には出力 URL を含む videos 配列が含まれます：
{
"task": {
"status": "succeed"
},
"videos": [
{
"video_url": "https://cdn.novita.ai/output/abc123xyz.mp4",
"video_url_ttl": "3600"
}
]
}
通常の生成時間は、動画の長さとモードに応じて 30～120 秒です。エンドポイントを連打せずに 5～10 秒ごとにポーリングしてください。
完全な Python 統合例
このスクリプトは、モーションコントロールタスクを送信し、完了するまでポーリングします：
import os
import time
import requests
API_KEY = os.environ["NOVITA_API_KEY"]
BASE_URL = "https://api.novita.ai"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def submit_motion_control(image: str, video: str, prompt: str = "") -> str:
payload = {
"image": image,
"video": video,
"prompt": prompt,
"model_name": "kling-v3.0-motion-control",
"character_orientation": "video",
}
resp = requests.post(f"{BASE_URL}/v3/async/kling-v3.0-motion-control", json=payload, headers=HEADERS)
resp.raise_for_status()
return resp.json()["task_id"]
def poll_result(task_id: str, timeout: int = 300) -> str:
deadline = time.time() + timeout
while time.time() < deadline:
resp = requests.get(
f"{BASE_URL}/v3/async/task-result",
params={"task_id": task_id},
headers=HEADERS,
)
resp.raise_for_status()
data = resp.json()
status = data.get("task", {}).get("status")
if status == "succeed":
return data["videos"][0]["video_url"]
if status == "failed":
raise RuntimeError(f"Task failed: {data}")
time.sleep(8)
raise TimeoutError(f"Task {task_id} did not complete within {timeout}s")
if __name__ == "__main__":
image = "https://example.com/character.jpg"
video = "https://example.com/reference_motion.mp4"
print("Submitting task...")
task_id = submit_motion_control(image, video, prompt="smooth dance routine, warm lighting")
print(f"Task ID: {task_id}")
print("Polling for result...")
output_url = poll_result(task_id)
print(f"Output video: {output_url}")
API パラメータリファレンス
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
image |
文字列 | はい | アニメーション化するキャラクター画像の URL。上記の入力要件を参照してください。 |
video |
文字列 | はい | モーションが転送される参照動画の URL。 |
model_name |
文字列 | はい | kling-v3.0-motion-control に設定します。 |
prompt |
文字列 | いいえ | 目的のモーションスタイルまたはシーンコンテキストのテキスト説明。オプションですが、出力品質を向上させることができます。 |
character_orientation |
文字列 | いいえ | ポーズのアライメントと出力期間を制御します。"video" は参照動画の向きに合わせます。全身の複雑な動きに適しており、最大30秒まで対応します。"image" はキャラクター画像の向きに合わせます。カメラに対する動きに適しており、固定で5秒です。 |
character_orientation の実際の使い方
参照動画が正面を向いたダンサーで、キャラクター画像も正面を向いている場合、"video" はより良いモーショントランスファーを提供し、最大30秒まで対応します。参照動画が被写体の周りをカメラが移動し、画像が固定アングルのポートレートの場合、"image" は不要な遠近感の歪みを軽減する傾向があります。ただし、固定で5秒のクリップが生成されることに注意してください。
Standard と Pro: どの品質レベルを選ぶか
Kling V3.0 モーションコントロールは、2つの品質レベルで利用可能です：
Standard は 720p で出力します。これは、反復、モーションの互換性のテスト、または最終版にコミットする前の下書き生成に適した選択肢です。
Pro は 1080p で出力し、モーションの忠実度と被写体の一貫性が向上します。Pro は以下の場合に使用します：
- 出力が完成品（ソーシャル投稿、短編映画、製品デモ）に使用される場合
- キャラクターの顔や衣服の細かいディテールが重要な場合
- 時間経過による品質劣化がより目立つ長いクリップ（10秒以上）を生成する場合
ほとんどの開発ワークフローでは、まず Standard を使用して入力の互換性とモーション品質を確認し、最終パスで Pro に切り替えてください。
料金、長さ、コスト見積もり
Novita AI は、生成された動画の秒数ごとにモーションコントロールを課金します。Standard と Pro の各ティアには、秒単位のレートが別途設定されています。現在の料金については、Novita AI モデルページ を確認してください。
長さの制限：
character_orientation: "video"— 最大30秒character_orientation: "image"— 固定で5秒
コストは "video" モードの長さに比例してスケールします。"image" モードでは常に5秒のクリップが生成されます。
一般的なエラーのトラブルシューティング
タスクが即座に 422 またはバリデーションエラーで失敗する
image と video の両方が公開アクセス可能な URL（認証の背後や有効期限が切れた短期間の署名付き URL ではない）であることを確認してください。Novita バックエンドは、タスク実行時に両方のファイルを取得できる必要があります。
出力の動きがおかしい、またはキャラクターが歪む
最も一般的な原因は、画像内のキャラクターの向きと参照動画の間の不一致です。character_orientation を "video" と "image" の間で切り替えて、どちらがより良いアライメントを生成するかを試してください。
クリップの途中でキャラクターの顔の同一性が失われる 参照画像内のキャラクターが明確で遮蔽のない顔と体を持っていることを確認してください。長いクリップの場合、Pro ティアは Standard よりも被写体の一貫性を維持します。
参照動画の動きがきれいに転送されない ノイズが多い、または混雑した参照映像は、モーション抽出の品質を低下させます。パフォーマーが主要な被写体であり、背景が比較的クリーンな映像を使用してください。滑らかなモーショントランスファーを目指す場合は、手持ちのブレた映像は避けてください。
ステータスが 3 分以上 processing のまま
時折、キュー遅延が発生します。スタックとして扱う前に最長5分待ってください。それでもスタックしたままの場合は、新しいタスクを送信してください。古い task_id を再利用しないでください。
開発者が Kling モーションコントロールで構築するもの
ゲームアセットのキャラクターアニメーション: キャラクターのイラストを取得し、リギングやアニメーションソフトウェアを使わずに参照モーションクリップ（歩く、走る、攻撃）を適用します。
一貫した動きのソーシャルコンテンツ: 同じダンス参照動画を複数のキャラクター画像に適用して、同一の振り付けで異なる外観の一連のクリップを生成します。
プリビジュアライゼーション: 特定の動きのシーケンスがキャラクターデザインでどのように見えるかを、本格的なアニメーション制作に投資する前にテストします。
Eコマース製品表示: 衣服の動きを示す慎重に選択された参照動画を使用して、製品画像に微妙なポーズ変更や衣類の動きを適用します。
FAQ
Novita AI でのモーションコントロールと Image-to-Video の違いは何ですか？
Image-to-Video（I2V）は、テキストプロンプトに基づいて画像をアニメーション化します。動きはモデルが説明から生成します。モーションコントロールは、参照動画から特定の動きを画像内のキャラクターに転送します。モーションコントロールは正確で再現可能な動きを提供し、I2V は参照クリップを必要とせずに創造的な柔軟性を提供します。
参照動画のキャラクターは、画像のキャラクターの外観と一致する必要がありますか？
いいえ。参照動画はモーション抽出のみに使用されます。出力キャラクターは画像から来ており、動画からではありません。これがコア機能です。あるソースからの動き、別のソースからの外観。最良の転送品質を得るには、プロポーションがおおよそ一致している必要があります（全身動画には全身画像、上半身動画にはポートレート）。
公開されている任意の動画を参照として使用できますか？
形式とサイズの要件を満たす任意の動画を使用できます。モーションは、被写体が明確に見え、遮蔽が最小限の映像から最もよく転送されます。複雑なマルチパーソンシーンや、カット、ズームなどの編集が多用された映像は、精度を低下させる可能性があります。
生成にはどのくらい時間がかかりますか？
通常、出力の長さと Standard または Pro モードの選択に応じて 30～120 秒です。タイトなループではなく、8～10秒ごとにポーリングしてください。
