HiAPI
Ja
ブログ

使用ガイド

hiapi API で kling-3.0/motion-control を使ってショート動画を作る方法

Oct 8, 2026
hiapi API で kling-3.0/motion-control を使ってショート動画を作る方法

生成動画のキャラクターに特定の動きをさせたい——「ダンス」ではなく「この特定のクリップのこの特定のダンス」を——と思ったことがあるなら、通常の選択肢がいかにひどいかご存じでしょう。手作業でフレームごとにロトスコープするか、モーションモデルを再トレーニングするか、諦めてテキストプロンプトが返す結果をそのまま受け入れるか。kling-3.0/motion-control はこれらすべてを回避します。キャラクター画像と参照動画を渡すと、参照の動きと表情をあなたのキャラクターに転写します——リギング不要、キーフレーム不要、モーションキャプチャスーツ不要です。

本記事では実際のショート動画ワークフローをたどります。まずドライバーの写真を短い参照クリップにし、そのクリップで motion-control を使ってまったく別のキャラクター画像を動かします。以下のリクエストはすべて hiapi の /v1/tasks API への実呼び出しで、各素材はこの執筆中に生成されたもの（ベンダーのデモギャラリーから借りたものは一切なし）、各価格は hiapi の価格エンドポイント からリアルタイムで取得したものです。

kling-3.0/motion-control が実際にすること

このモデルは 2 つの入力を受け取ります：

  • image_url —— 単一のキャラクター肖像（「ターゲット」）。出力に誰が登場するかを決めます。
  • video_url —— 動きの参照クリップ、3〜30 秒。何をするかを決めます。

出力は、ターゲットキャラクターが参照動画の動きと表情を行う動画で、解像度は 720p または 1080p でレンダリングされます。テキストプロンプト、長さ、アスペクト比は受け付けません——出力の構図は参照クリップにそのまま従い、出力の長さも入力クリップの長さに従います（我々の 3 秒の参照は 3.03 秒の出力を返しました）。

入力が 2 つだけというこの狭い契約こそが、ショート動画コンテンツで役立つ理由です。モーションキャプチャ機器がなくても、ブランドマスコット、製品キャラクター、スタイライズされたアバターに説得力のある演技をさせられます——必要なのは、あなたが望む動きをする人間の動画が何かしら 1 本あればよいのです。

必要なもの

  • hiapi API キー（Authorization: Bearer <key>）
  • HTTPS で公開アクセス可能なキャラクター画像（ターゲットではなく、駆動するキャラクター）
  • アニメーション化したい実際のターゲットとなる 2 枚目のキャラクター画像
  • ローカルでカバーフレームを抽出したりクリップの長さを確認したい場合は ffmpeg/ffprobe（本記事と同じ方法）

実際のデモ：1 つのモーションクリップ、2 人の異なるキャラクター

motion-control の要点は、参照動画と最終的なキャラクターが一致している必要がないことです。これを示すため、本デモでは 3 つの生成ステップを使用します：

1. ドライバーの肖像を、短い参照クリップにアニメーション化：

その肖像は grok-imagine-1.5/image-to-video によって 3 秒・480p のモーションクリップになりました——既製のクリップを探す代わりに、静止画から参照クリップを作る速くて安い方法です：

2. まったく異なるターゲットキャラクター——同じ動き、まったく異なる外見：

3. 両方を motion-control に投入。 店主は配達員とまったく同じ振り返りの動きをします：

これがワークフロー全体です：好きなモーションクリップを生成（または取得）し、motion-control をまったく無関係なキャラクター画像に向け、そのキャラクターがその動きをする結果を得る。ショート動画パイプラインにとって、これは 1 つの参照モーションライブラリが無限の数のキャラクターを駆動でき、そのたびに参照アニメーションを撮り直したり作り直したりする必要がないことを意味します。

最小限の動作するリクエスト（curl）

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0/motion-control",
    "input": {
      "image_url": "https://static.hiapi.ai/blog/kling-3-0-motion-control-short-form-video/target-character.png",
      "video_url": "https://static.hiapi.ai/blog/kling-3-0-motion-control-short-form-video/motion-reference.mp4",
      "resolution": "720p"
    }
  }'

レスポンス（タスクは作成済み、まだ処理中）：

{
  "code": 0,
  "data": {
    "taskId": "tk-hiapi-01M4CWNSYA7RB637YJ2QZMHMMS",
    "status": "pending"
  },
  "success": true
}

完了するまでポーリング：

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01M4CWNSYA7RB637YJ2QZMHMMS \
  -H "Authorization: Bearer $HIAPI_API_KEY"

我々の実行では、3 秒・720p のクリップが最初から最後まで約 2.3 分かかりました（ステータスが success に切り替わるまで、およそ十数回 handling を繰り返しました）——ポーリングループを設計する際は、数秒ではなく数分を見込んでください。最終レスポンス：

{
  "code": 0,
  "data": {
    "taskId": "tk-hiapi-01M4CWNSYA7RB637YJ2QZMHMMS",
    "status": "success",
    "output": [
      {
        "type": "video",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M4CWNSYA7RB637YJ2QZMHMMS-0.mp4",
        "storage": "temp",
        "expireAt": 1792039027
      }
    ]
  },
  "success": true
}

その output[0].url は一時リンクです——expireAt は Unix タイムスタンプで、我々のテストでは有効期間は約 24 時間でした。すぐにダウンロードして再ホストしてください。公開するどのコンテンツからも直接リンクしないでください。

Python での同じ流れ

import os
import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
TOKEN = os.environ["HIAPI_API_KEY"]
HEADERS = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}


def create_motion_control_task(image_url: str, video_url: str, resolution: str = "720p") -> str:
    resp = requests.post(
        API_BASE,
        headers=HEADERS,
        json={
            "model": "kling-3.0/motion-control",
            "input": {
                "image_url": image_url,
                "video_url": video_url,
                "resolution": resolution,
            },
        },
        timeout=60,
    )
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_result(task_id: str, timeout_s: int = 600, poll_every: int = 10) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        if task["status"] == "success":
            return task["output"][0]["url"]
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(poll_every)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


if __name__ == "__main__":
    task_id = create_motion_control_task(
        image_url="https://your-cdn.example.com/target-character.png",
        video_url="https://your-cdn.example.com/motion-reference.mp4",
        resolution="720p",
    )
    output_url = wait_for_result(task_id)

    video_bytes = requests.get(output_url, timeout=120).content
    with open("motion-control-output.mp4", "wb") as f:
        f.write(video_bytes)
    print(f"saved {len(video_bytes)} bytes")

複雑なことは何もありません——タスクを作成し、一定間隔で GET /v1/tasks/{taskId} をポーリングし、success になった瞬間に output[0].url をダウンロードし、一時リンクが期限切れになる前に自分で再ホストします。

motion-control が実際に検証するパラメータ

スキーマは厳格です——この 3 つのフィールド以外はすべて拒否されます。これを試行錯誤で知るのではなく、事前に知っておくと役立ちます：

フィールド 必須か 説明
image_url はい 公開 HTTPS URL、ターゲットキャラクター
video_url はい 公開 HTTPS URL、3〜30 秒のモーション参照
resolution いいえ（デフォルトあり、ただし設定推奨） "720p" または "1080p"——これが価格帯も決める

他の動画モデルで期待するかもしれないフィールド——duration、aspect_ratio、prompt——はすべてスキーマエラーで拒否されます：

{
  "code": 1,
  "message": "input: Object { input } has unexpected additional properties: duration, aspect_ratio",
  "success": false
}

これは設計上のものです：出力の長さと構図は参照動画からそのまま継承されるため、duration/aspect_ratio で制御できるものはありません。より長い出力や構図の異なる出力が欲しい場合は、リクエストを変更するのではなく、送信前に参照クリップをトリミングまたは再構成してください。

価格：リクエスト単位ではなく出力秒単位で課金

hiapi の価格エンドポイント から直接：

解像度 価格
720p $0.10 / 出力秒
1080p $0.172 / 出力秒

課金は実際の出力長（estimated_seconds）によって決まり、それはあなたの参照クリップの長さを反映します——リクエストごとの固定料金ではありません。我々の 3 秒の参照は 720p で 3.03 秒の出力を生成し、およそ $0.30 かかりました。10 秒の 1080p 参照クリップなら $1.72 近くになります。コンテンツカレンダーでまとめて使う場合、実際に調整できるレバーは参照クリップの長さです。短い参照クリップはコストが低く、しかもショート動画フォーマット（Reels、TikTok、Shorts）では 3〜8 秒がクリップ全体になることも多く、完全なモーション演技を十分に伝えられます。

本番運用上の注意

  • 駆動クリップの構図は意図的に選ぶ。 出力は参照動画のアスペクト比、カメラ距離、テンポを継承します——クローズアップの参照は、ターゲットキャラクター画像のクロップに関係なくクローズアップの出力になります。
  • はっきりした表情は繊細な表情よりもうまく転写される。 参照のはっきりした振り返り、手を振る、首をかしげるなどの動きはターゲットキャラクターに確実に現れます。非常に繊細で自然な微表情はモデルが識別・転写するのが難しくなります。
  • 1 つの参照クリップを多くのキャラクターで再利用する。 video_url と image_url が完全に独立しているため、コンテンツパイプラインで最も効率的なパターンは、まず小さな参照モーションライブラリを作り、同じクリップで多くの異なるキャラクター画像を実行することです。
  • 一時的な出力 URL は有効期間が短い。 expireAt は通常 1 日程度です——ダウンロードを後回しにせず、すぐにダウンロードして再ホストしてください。
  • 処理は即時ではない。 このテストでは、3 秒・720p のクリップが最初から最後まで 2 分以上かかりました。ポーリングループや下流の自動化は、テキストからの画像生成呼び出しで通常の秒単位ではなく、分単位で計画してください。

関連コンテンツ

参照クリップとペアにしたいキャラクターがありますか？価格ページからキーを取得し、上の curl リクエストをあなた自身の image_url/video_url に向けてください——上のループ全体はそのままコピー＆ペーストできます。

よくある質問

モーション参照として任意の動画を使えますか？ はっきりした人間（または人型）の演者がいる動画であれば何でも使えます。HTTPS で公開アクセス可能で、長さが 3〜30 秒である限り。ターゲットキャラクターが含まれている必要はありません——それこそがこのモデルの意義です。

出力は参照動画の背景を保持しますか？ いいえ——キャラクターの外見（ターゲット画像が示す環境を含む）が引き継がれます。参照動画が提供するのは動きと表情であり、シーンの内容ではありません。

なぜリクエストが「unexpected additional properties」で拒否されたのですか？ スキーマは image_url、video_url、resolution のみを受け付けます。duration、aspect_ratio、prompt のようなフィールドはこのモデルの入力ではないため、即座に 400 が返ります——ペイロードから削除してください。

motion-control タスクにはどれくらいかかりますか？ クリップごとに数分見込んでください。我々の 3 秒・720p の例は、タスク作成からダウンロード可能な success 出力まで約 2.3 分かかりました。

価格とは別に出力解像度を制御できますか？ いいえ——resolution は出力品質設定であり価格帯のセレクターでもあります："720p" は $0.10/出力秒、"1080p" は $0.172/出力秒で課金されます。

タグkling動画生成hiapi apiモデルのユースケース

関連記事

すべての記事を見る →

永続的なAIアーティファクトで開発を始める

APIキーを取得して、タスクベースの1つのAPIで画像・動画・音声モデルを呼び出せます。

APIドキュメントを読む