チュートリアル
HiAPI API で kling-3.0/motion-control を使用する方法:curl と Python の例
このページの内容
kling-3.0/motion-control の用途と採用すべきタイミング
モーション制御は動画生成における能力の一種です:参照動画をモデルに渡すと、テキストプロンプトだけで動作を記述するのではなく、モデルが出力内の動き・リズム・構図を駆動します。HiAPI API で kling-3.0/motion-control を使用する場合、参照動画が主要な入力となります。参照動画はオブジェクトがどのように動くかを固定し、その他のパラメータはその動きを中心に生成される内容を形作ります。
動きそのものが難しい場合に、このモデルを選択すべきです。適した典型的なシナリオ:
- 短い動画があり、異なる内容でそのカメラワークや被写体の動作を再現したい。
- テキストプロンプト任せのテキストto動画の結果ではなく、予測可能な動きが必要である。
- 動きを複数回の生成にわたって再利用できる資産として扱うパイプラインを構築しており、そのため一文の説明ではなく入力として扱うべきである。
テキストto動画だけが必要で、動きの参照がない場合、モーション制御はアップロード手順とより厳しい入力制約を追加するだけで、利点はありません。同様に、参照動画が長すぎたり構図が不安定だったりする場合は、より多くのリトライを見込んでください。本ガイドの残りの部分では、モーション制御が適切なツールであると判断済みで、信頼性が高く再現可能な統合方法を求めていることを前提とします。
前提条件とエンドポイントの設定
初回呼び出しの前に、三つの項目を準備してください。
1. API キー
HiAPI.ai アカウントのコンソールでキーを作成し、ソースコードに書くのではなく環境変数に保存します:
export HIAPI_API_KEY="your_api_key_here"
各リクエストでベアラートークンとして送信します:Authorization: Bearer $HIAPI_API_KEY。
2. ベース URL の規約
すべての HiAPI 呼び出しは同じベース URL とバージョン付きのパスプレフィックスを共有します。環境を切り替える際に呼び出し箇所を変更しなくて済むよう、ベース URL は設定に置いてください:
export HIAPI_BASE_URL="https://api.hiapi.ai"
3. モデル識別子
モデルはリクエストの model フィールドでリクエストごとに選択し、正確な識別子 kling-3.0/motion-control を使用する必要があります。複数箇所にハードコードせず、定数として受け渡すことで、将来モデルを変更する際に一行の修正で済みます。
また、API が参照動画を取得できるホスティング場所も必要です。通常は署名付きの期限付き URL を使用します。カスタムヘッダーや cookie なしでアクセスできることを確認してください。
この三項目が整えば、残る作業はリクエスト構造とタスクのライフサイクルです。
参照動画とモーションパラメータの提供
モーション制御のリクエストは概念的には二つに分かれます:動きのソース(参照動画)と生成設定(モデルが何を出力すべきか)です。
参照動画
参照動画は JSON ペイロード内で生のバイト列として渡すのではなく、URL 形式でリクエストボディに含めます。実用的な二つのルール:
- タスクがキューに入り処理される間ずっと有効な URL を使用する。署名付き URL が早く期限切れになることは、タスクが投入から数分後に失敗する一般的な原因です。
- 動画は短く、映像は安定させる。長すぎる、揺れが激しい、または頻繁にカットされる参照素材は、モデルにあいまいな動きの信号を与えてしまいます。
素材がプライベートストレージにある場合は、アップロード時ではなく投入時に十分長い有効期間の署名付き URL を生成してください。
モーションと出力のパラメータ
通常、参照動画と一緒に設定するパラメータ:
- 参照の動きによって駆動されるべき目標内容を記述するテキストプロンプト。
- 出力のアスペクト比と長さの設定。生成動画を掲載位置に合わせます。
- モデルが公開している動きの強度や忠実度の設定。参照への忠実さとプロンプトの自由度の間で調整します。
これらのパラメータは関数の引数に分散させるのではなく、クライアント内の小さく明示的な設定オブジェクトとして扱ってください。これにより何を投入したかを正確に記録でき、これはこのモデルで最も有用なデバッグ材料です。
最後に、投入前に検証します:参照 URL がメディアのコンテンツタイプを返すか、プロンプトが空でないか、すべての数値設定がドキュメントの範囲内か。ローカルでのチェックはミリ秒で済みますが、拒否された非同期タスクは往復一回と混乱の代償を払うことになります。
非同期タスク:投入、ポーリング、結果の読み取り
モーション制御は投入レスポンスで動画を返すのではなく、追跡が必要なタスクを返します。クライアントは最初からこのライフサイクルを中心に構築してください。
ステップ 1 — 投入
モデルのエンドポイントにタスクを POST します。投入に成功するとタスク識別子が返ります。その ID を即座に永続化してください。それはタスクを操作する唯一のハンドルであり、ポーリングやサポート依頼で使用します。
ステップ 2 — ポーリング
その ID でタスクの状態を GET します。状態フィールドは次の三つのいずれかを示します:
- 保留中またはキュー待ち:受け付け済みだが未開始。待機を続ける。
- 処理中または実行中:進行中。バックオフを伴って待機を続ける。
- 終端状態:成功または失敗。ポーリングを停止する。
ポーリングループは出力フィールドの有無だけでなく、終端状態を明示的に確認すべきです。失敗したタスクには結果がなく、「結果なし」を「まだ実行中」と扱うと無限ループになります。
ステップ 3 — 結果の読み取り
成功時、レスポンスには出力位置、通常は生成動画の URL が含まれます。速やかに自分のストレージへダウンロードしてください。一時 URL の背後にある生成資産を永続的に利用可能とは見なすべきではありません。
ポーリングのベストプラクティス
二つのルールで本番環境でも信頼性を保てます:
- エンドポイントを叩き続けるのではなく、ポーリング間にバックオフを入れる(1〜2 秒から始めて徐々に増やす)。
- 総待機時間に上限を設け、タイムアウトをリトライ可能なエラーとして表面化させ、ワーカースレッドを永久にブロックしない。
各実行についてタスク ID、投入したパラメータ、最終状態を記録してください。異常が発生したとき、そのログは他の人に尋ねる前にほとんどの疑問に答えてくれます。
実行可能な curl リクエスト
以下はシェルでの完全なフローです。タスクを投入し、タスク ID を抽出し、終端状態になるまでポーリングします。
#!/usr/bin/env bash
set -euo pipefail
BASE="$HIAPI_BASE_URL"
MODEL="kling-3.0/motion-control"
# 1) タスクを投入
SUBMIT=$(curl -sS -X POST "$BASE/v1/videos/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-3.0/motion-control",
"prompt": "紙の舟が雨の都市の通りを漂う、映画的な雰囲気",
"reference_video_url": "https://your-bucket.example.com/refs/pan-left.mp4",
"duration": 5,
"aspect_ratio": "16:9"
}')
echo "$SUBMIT"
TASK_ID=$(echo "$SUBMIT" | python3 -c 'import sys,json; print(json.load(sys.stdin)["id"])')
echo "task: $TASK_ID"
# 2) 終端状態までポーリング
while true; do
STATUS_JSON=$(curl -sS "$BASE/v1/videos/generations/$TASK_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY")
STATUS=$(echo "$STATUS_JSON" | python3 -c 'import sys,json; print(json.load(sys.stdin)["status"])')
echo "status: $STATUS"
case "$STATUS" in
succeeded) echo "$STATUS_JSON"; break ;;
failed|cancelled) echo "$STATUS_JSON" >&2; exit 1 ;;
esac
sleep 3
done
このスクリプトを改変する際の二点の注意。第一に、モデル識別子とエンドポイントパスを変数に保持し、スクリプトを読みやすく保つこと。第二に、上記のパースは jq を使わず Python のみを使っていますが、これは Python がほぼどこでも利用できるためです。jq を好む場合は置き換え可能です。いずれにせよ重要な動作は同じです:投入レスポンスからタスク ID を抽出し、終端状態の値が現れるまでその状態をポーリングします。
同じリクエスト(Python 版)
以下の Python クライアントは curl のフローに対応しますが、ポーリングループがより堅牢です:近似指数バックオフ、全体タイムアウト、そして各終端状態の明示的な処理を備えます。
import os
import time
import requests
BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
MODEL = "kling-3.0/motion-control"
HEADERS = {
"Authorization": f"Bearer {KEY}",
"Content-Type": "application/json",
}
TERMINAL = {"succeeded", "failed", "cancelled"}
def submit_job(prompt: str, reference_video_url: str, duration: int = 5) -> str:
payload = {
"model": MODEL,
"prompt": prompt,
"reference_video_url": reference_video_url,
"duration": duration,
"aspect_ratio": "16:9",
}
r = requests.post(
f"{BASE}/v1/videos/generations",
headers=HEADERS,
json=payload,
timeout=30,
)
r.raise_for_status()
return r.json()["id"]
def wait_for_job(task_id: str, timeout_s: int = 600) -> dict:
deadline = time.time() + timeout_s
delay = 2.0
while time.time() < deadline:
r = requests.get(
f"{BASE}/v1/videos/generations/{task_id}",
headers=HEADERS,
timeout=30,
)
r.raise_for_status()
data = r.json()
status = data.get("status")
if status in TERMINAL:
return data
time.sleep(delay)
delay = min(delay * 1.5, 15.0)
raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")
if __name__ == "__main__":
task_id = submit_job(
prompt="紙の舟が雨の都市の通りを漂う、映画的な雰囲気",
reference_video_url="https://your-bucket.example.com/refs/pan-left.mp4",
)
print("submitted:", task_id)
result = wait_for_job(task_id)
if result["status"] == "succeeded":
print("output:", result.get("output"))
else:
print("job did not succeed:", result)
改変時に維持する価値のある部分:終端状態の集合、上限付きのバックオフ、そして独立した投入関数と待機関数です。実際のサービスでは、これらを二つのプロセスに分けます——リクエストハンドラから投入してタスク ID を保存し、ワーカーにポーリングさせる——ことで、遅いタスクが HTTP レスポンスをブロックすることは決してありません。
よくある失敗箇所とそのデバッグ方法
kling-3.0/motion-control の統合問題のほとんどは少数のカテゴリに収まります。順に確認してください。
認証とモデルのエラー
401 はほぼ常に、ベアラートークンが欠落している、切り詰められている、または誤った環境から取得されたことを意味します。モデル未検出エラーは model 文字列が完全に一致していないことを意味します——スラッシュ区切りの識別子であるため、文字順の誤りや余分な空白は設定側では静かに失敗し、API 側では大声でエラーになります。
参照動画が利用できない
タスクは受け付けられたが、数分後に参照 URL を取得できずに失敗する。原因を頻度順に挙げると:署名付き URL が処理前に期限切れになる;URL がサービスから送信されない認証ヘッダーを必要とする;URL が動画ではなく HTML(ログインページやエラーページ)を返す。自分のネットワークの外部から通常の curl でその URL をテストし、コンテンツタイプを確認してください。
パラメータの形式エラーまたは範囲外
長さとアスペクト比の設定がドキュメントの範囲外である場合、投入時に拒否されますが、これは良いことです——すぐにエラーが得られます。ローカルで事前に検証しておけば、タイプミスを発見するのに往復一回を要することはありません。
ポーリングの欠陥
二つの古典的な問題:ループが出力フィールドだけを確認して failed を決して確認せず、無限ループになる;そしてスリープなしのタイトループでポーリングし、自分自身がレート制限にかかる。明示的な終端状態の確認とバックオフを追加し、エラー報告には常にタスク ID を添えて、タスクを再構築するのではなく照会できるようにしてください。
結果 URL の期限切れ
動画を生成したが、一時的な出力 URL だけを保存していた。タスク成功後すぐに出力を自分のストレージへダウンロードしてください。返された URL は取得用のハンドルであり、永続ストレージではないと見なしてください。
各デバッグセッションの開始時に、正確なリクエストボディと生のレスポンス JSON を記録してください。上記のほぼすべての問題はこの二つの材料で見えてきます。さらに深く進む準備ができたら、HiAPI.ai のドキュメントにある他の動画モデルとエンドポイントのリファレンスを参照し、同じ「先に投入、後にポーリング」のクライアント形態を保ってください。