Kling 4.0 画像から動画へのAPI：リクエストリファレンスと実際の実行例

Kling 4.0 画像から動画へは、1枚の最初のフレーム画像から、同期音声付きの3〜30秒のクリップを作成できます。このガイドでは、hiapi 上でそのまま使用できるリクエスト例、API が受け入れるフィールドと拒否するフィールド、そして実際の実行結果を示します。API キーは hiapi コンソール から取得してください。モデル ID は kling-4.0/image-to-video で、モデルページ に現在の仕様が記載されています。

まだ Kling 3.0 を使用している場合、Kling 4.0 API 概要 はリリース前に書かれたもので、リリース告知を説明しています。現在利用可能なリファレンスはこのページです。

最小リクエスト（curl）

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-4.0/image-to-video",
    "input": {
      "prompt": "彼女は少し頭をカメラの方へ向け、髪が風に揺れ、カメラがゆっくりと寄っていく、周囲から波の音",
      "image_urls": ["https://example.com/first-frame.jpg"],
      "duration": 3,
      "resolution": "720p"
    }
  }'

レスポンスはすぐにタスク ID を返します：

{"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

GET /v1/tasks/<taskId> をポーリングし、data.status が success になるまで待ち、その後 data.output[0].url を読み取ります。

Python：送信とポーリング

import os, time, requests

BASE = "https://api.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

def kling4_i2v(image_url, prompt, duration=5, resolution="720p"):
    r = requests.post(f"{BASE}/v1/tasks", headers=HEADERS, json={
        "model": "kling-4.0/image-to-video",
        "input": {
            "prompt": prompt,
            "image_urls": [image_url],   # ちょうど1枚の最初のフレーム画像
            "duration": duration,        # 整数、3-30
            "resolution": resolution,    # "720p" または "1080p"
        },
    })
    body = r.json()
    if body["code"] != 200:
        raise RuntimeError(body["message"])
    task_id = body["data"]["taskId"]

    while True:
        d = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d)
        time.sleep(10)

返された MP4 ファイルはすぐにダウンロードしてください。出力 URL には expireAt タイムスタンプがあり（私たちの実行では約7日後）、一時的なドメインでホストされているため、直接ホットリンクするのではなく、自分のストレージにコピーしてください。

API が受け入れるフィールド

故意に無効な値でこのエンドポイントを調査しました（これらの値は HTTP 400 INVALID_REQUEST を返し、タスクは作成されません）：

フィールド	観察されたルール
image_urls	必須の配列で、ちょうど1項目（2項目 → maxItems: got 2, want 1）
duration	整数、最小3、最大30。"5" のような文字列は拒否されます（got string, want integer）
resolution	720p または 1080p
aspect_ratio	任意：16:9、9:16、1:1、21:9。省略時は構図が元画像に従うとモデルページに記載されています
prompt	動きの説明。バリデータの調査ではこのフィールドを含まないリクエストのみを送信したため、推奨フィールドとして扱います

他の動画モデルからコードを移行する際に、つまずきやすい点が2つあります：

• フィールドは image_urls であり、image_url ではありません。 image_url を送信すると、「必須フィールド image_urls がありません」と「追加プロパティ image_url は許可されていません」の両方が報告されます。
• 音声のオン/オフスイッチはありません。 audio、generate_audio、sound はすべて追加プロパティとして拒否されます。音声は常に映像と一緒に生成されます。プロンプトで音声を誘導してください（上記の例では周囲の波の音を要求しています）。

未知のフィールドは無視されるのではなく拒否されるため、タイプミスは黙って無視される設定ではなく 400 として表面化します。

本番環境での注意点

• ポーリングよりもコールバックを優先してください。 クリップの生成には数分かかるため、タスク作成時に callback（url と when: "final" を含む）を渡し、webhook で結果を処理してください。ポーリングはフォールバックとしてのみ使用します。
• 課金前に検証してください。 無効な入力は 400 を返してタスクを作成しないため、期間と解像度を自分のコードで先にチェックしてください。誤ったリクエストは無料ですが、正しいリクエストは要求した秒数ごとに課金されます。
• 課金は秒単位で解像度にも依存します。 長いクリップと 1080p はより高額になります。記事中の数字に頼らず、現在の料金は 料金ページ を確認してください。
• タスク ID を保存してください。 一時的なネットワークエラーでポーリングが失敗した場合は、再送信するのではなく同じ ID を再度ポーリングしてください。そうしないと2つ目のクリップが作成され課金されます。

実測実行

上記のリクエストを送信しました：縦向きの最初のフレーム画像、duration: 3、resolution: "720p"、aspect_ratio なし。

• 約10秒ごとにポーリングしたときに観察されたステータス遷移：handling → archiving → success。
• 総実時間：3秒のクリップで約274秒。handling が約255秒を占めました。秒単位ではなく分単位で計画し、コールバックを中心に設計してください。
• 出力ファイル（ffprobe で確認）：H.264 ビデオ、1280×720、3.04秒、さらに同じ長さの AAC 音声トラック。したがって音声は実際に MP4 に埋め込まれており、構図は 16:9 の元画像に従っています。

私たちはテストしていません：1080p、3秒を超える期間、およびデフォルト以外の aspect_ratio 値。これらの制限は生成された出力ではなく、API の検証メッセージとモデルページに基づいています。

関連ページ

• Kling 4.0 画像から動画へのモデルページ
• Kling 4.0 テキストから動画へのモデルページ、元画像がない場合に適しています
• Kling 3.0 画像から動画へのモデルページ
• Kling 3.0 Turbo 画像から動画への使い方
• hiapi 料金
• hiapi ドキュメント

よくある質問

Kling 4.0 画像から動画へで音声をオフにできますか？

リクエストフィールドではできません。audio、generate_audio、sound はすべてバリデータに拒否されます。プロンプトで欲しい音（または欲しくない音）を記述してください。

入力画像は何枚まで送信できますか？

1枚です。image_urls にはちょうど1枚の最初のフレーム画像を含める必要があります。

1つのリクエストにはどのくらい時間がかかりますか？

私たちの3秒 720p クリップはエンドツーエンドで約274秒かかりました。本番負荷ではコールバックを使用してください。

最長のクリップはどれくらいですか？

API は duration を最大30（整数秒）まで受け入れ、それ以上の値は拒否します。私たち自身は3秒のクリップのみを生成しました。