Python での Kling AI 画像から動画への API

HiAPI の非同期タスクエンドポイントを使い、Python で Kling AI 画像から動画への API を利用します。以下のクイックスタートでは、現在呼び出し可能な kling-3.0-omni/image-to-video モデル ID を使用し、タスクが終了状態になるまでポーリングして、生成された MP4 をダウンロードします。

正確なフィールドを確認するには、Kling 3.0 Omni 画像から動画への API ドキュメントを開いてください。現在の Omni モデルページでモデルと Playground を確認し、本番実行前にリアルタイムの Kling API 価格を確認してください。

クイックスタート：Python で Kling 画像から動画を実行する

python -m pip install requests で requests をインストールし、環境に HIAPI_API_KEY を設定し、IMAGE_URL を公開された JPEG、PNG、または WebP の URL に置き換えます。完全なスクリプトは最初のコピー可能なコードブロックです：

import os
import time
from pathlib import Path

import requests

API_BASE = "https://api.hiapi.ai/v1"
API_KEY = os.environ["HIAPI_API_KEY"]
IMAGE_URL = "https://cdn.example.com/first-frame.jpg"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "kling-3.0-omni/image-to-video",
    "input": {
        "image_urls": [IMAGE_URL],
        "prompt": "The camera slowly pushes in as leaves move in a light breeze",
        "duration": 5,
        "resolution": "1080p",
        "sound": False,
    },
}

created = requests.post(
    f"{API_BASE}/tasks",
    headers=HEADERS,
    json=payload,
    timeout=30,
)
created.raise_for_status()
task_id = created.json()["data"]["taskId"]

deadline = time.time() + 900
while time.time() < deadline:
    response = requests.get(
        f"{API_BASE}/tasks/{task_id}",
        headers=HEADERS,
        timeout=30,
    )
    response.raise_for_status()
    task = response.json()["data"]

    if task["status"] == "success":
        output_url = task["output"][0]["url"]
        break
    if task["status"] == "fail":
        raise RuntimeError(task.get("error") or f"Task {task_id} failed")

    time.sleep(8)
else:
    raise TimeoutError(f"Task {task_id} did not finish within 15 minutes")

with requests.get(output_url, stream=True, timeout=180) as download:
    download.raise_for_status()
    with Path("kling-output.mp4").open("wb") as video:
        for chunk in download.iter_content(1024 * 1024):
            if chunk:
                video.write(chunk)

print("Saved kling-output.mp4")

作成リクエストは taskId を返し、動画生成の完了を待機しません。スクリプトは GET /v1/tasks/{taskId} をポーリングし、success または fail で停止し、結果 URL は期限切れになるため、最初の出力をできるだけ早くダウンロードします。

Kling Omni モデルを開いてこの payload を試す。

現在利用可能な Kling 画像から動画へのモデルを選択する

モデル ID	適用シナリオ	入力と出力の約定
kling-3.0-omni/image-to-video	最初のフレーム/最後のフレームの制御、オプションのネイティブサウンド、または 4K が必要な場合	1～2 つの公開画像 URL；3～15 秒；720p、1080p、または 4K
kling-3.0-turbo/image-to-video	開始フレームが 1 つだけで、720p/1080p のよりシンプルなスキーマで要件を満たせる場合	ちょうど 1 つの公開画像 URL；prompt は必須；3～15 秒；720p または 1080p

Omni の完全なフィールドリファレンスは Omni I2V ドキュメントを参照してください。Turbo には別途 Turbo I2V schema リファレンスがあります。どちらも同じ /v1/tasks の作成とポーリングのワークフローを使用するため、1 つの実行スクリプトを保ち、model と input だけを置き換えられます。

モデルの要件に適合するリクエストボディ

最初のフレームと最後のフレームを指定する Omni

最初のフレームを表す URL を 1 つ送信するか、2 つの URL を [first, last] の順序で並べて送信します：

{
  "model": "kling-3.0-omni/image-to-video",
  "input": {
    "image_urls": [
      "https://cdn.example.com/first-frame.jpg",
      "https://cdn.example.com/last-frame.jpg"
    ],
    "prompt": "The camera arcs around the subject as the light changes from dawn to noon",
    "duration": 8,
    "resolution": "1080p",
    "sound": true
  }
}

Omni は image_urls を 1 つまたは 2 つ受け付けます。prompt はオプションで、duration は 3 から 15 の整数、resolution は 720p、1080p、または 4K、sound はオプションです。

開始フレームを 1 つ指定する Turbo

{
  "model": "kling-3.0-turbo/image-to-video",
  "input": {
    "prompt": "The subject turns toward the camera while leaves move in a light breeze",
    "image_urls": ["https://cdn.example.com/first-frame.jpg"],
    "duration": 8,
    "resolution": "1080p"
  }
}

Turbo は prompt の指定が必須で、image_urls にはちょうど 1 つの要素を含める必要があります。Omni のみがサポートするフィールド（sound など）を送信せず、テキストから動画へのフィールド（aspect_ratio など）も追加しないでください。映像はソース画像によって決まります。

Kling AI の価格：リアルタイムの料金を参照し、価格をそのまま転記しない

HiAPI 上の Kling AI の価格は従量課金制です。現在、2 つの画像から動画へのモデルはどちらも生成された秒数に基づいて課金され、具体的な料率はモデルと解像度によって決まります。Omni にはさらに異なる音声オン時の料金区分があります。より長いクリップ、より高い解像度、またはネイティブ音声はいずれもタスクの費用を変動させます。

料率は変更される可能性があるため、本ガイドでは固定の米ドル価格表を掲載しません。予算を立てる前、または大量のタスクを送信する前に、すぐにリアルタイムのモデル価格表を確認してください。

Kling AI は無料ですか？

いいえ：HiAPI 上では、Kling 画像から動画への API 生成は無制限に無料の API ではありません。成功したタスクは、選択したモデル、再生時間、解像度、音声設定に応じたリアルタイム料率で残高を消費します。アカウントのプロモーションや新規ユーザー特典は変更される可能性があり、条件が付く場合もあるため、保証された Kling の無料枠と見なさないでください。タスクを送信する前に、アカウントで現在の特典と残高を確認してください。

タスクの失敗や重複を防ぐための本番チェック

1. 直接ダウンロード可能な HTTPS 画像 URL を使用してください。localhost、ログインが必要なページ、HTML 共有ページ、期限切れの署名付き URL は、タスク作成後に失敗する可能性があります。
2. worker を再試行する前に taskId を保存してください。作成呼び出しを再試行すると、2 つ目のタスクが作成され課金される可能性があります。
3. success と fail を終了状態と見なしてください。本番環境では、トップレベルの callback.url を使用し、照合のフォールバックとしてポーリングを維持してください。
4. output[].url を速やかにダウンロードし、長期保存する結果を管理下のストレージにコピーしてください。
5. 送信前に選択したモデルのスキーマを検証してください。厳格なモデル約定は未知のフィールドを拒否します。

よくあるエラー

• HTTP 400：リクエストがスキーマと一致しません。指摘されたフィールド、列挙値、配列の長さ、JSON の型を確認してください。
• HTTP 401：bearer キーが欠落しているか無効、または選択したモデルで使用できません。
• タスクが fail になる：作成リクエストは検証を通過しましたが、レンダラーが入力を取得できないか、生成を完了できませんでした。taskId と返されたエラーを作成レスポンスとは別に記録してください。
• 出力 URL が期限切れ：レンダリングは成功した可能性がありますが、一時的な取得 URL を期限内にダウンロードしていません。

よくある質問

Python ではどの Kling 画像から動画へのモデルを使用すべきですか？

1～2 フレームの制御、オプションのネイティブサウンド、または 4K が必要な場合は、kling-3.0-omni/image-to-video を使用してください。開始フレーム 1 つと 720p/1080p 出力で要件を満たせる場合は、kling-3.0-turbo/image-to-video を使用してください。Python の作成、ポーリング、ダウンロードのコードは変わりません。

現在の Kling AI 画像から動画へのモデル ID は何ですか？

本記事で扱う現在呼び出し可能な ID は kling-3.0-omni/image-to-video と kling-3.0-turbo/image-to-video です。POST /v1/tasks のトップレベルの model フィールドにいずれかの ID を送信してください。

Kling 画像から動画へは何枚の画像を受け付けますか？

Omni は最初のフレームとして 1 枚の画像、または [first, last] の順序で 2 枚の画像を受け付けます。Turbo は開始フレームの画像をちょうど 1 枚受け付けます。

Kling AI API の費用はいくらですか？

生成された秒数に基づいて課金されます。正確なリアルタイム料率はモデルと解像度によって決まり、Omni ではさらに音声設定によって決まります。リアルタイム価格ページを使用し、本ガイドの固定価格をそのまま転記しないでください。

API 経由で Kling AI を使用するのは無料ですか？

無制限の Kling API 無料枠は保証されません。生成はリアルタイムのタスク料率でアカウント残高を消費します。固定の無料枠があると仮定せず、アカウントに現在条件付きの starter 特典があるか確認してください。

作成リクエストが成功したのにタスクが失敗するのはなぜですか？

JSON は初期検証を通過しましたが、レンダラーが画像を取得できないか、生成を完了できない可能性があります。画像が公開されていて期限切れでないことを確認し、保存した taskId に基づいて終了状態のエラーを確認してください。

生成された動画を取得するにはどうすればよいですか？

作成レスポンスから data.taskId を読み取ります。ローカルスクリプトは GET /v1/tasks/{taskId} をポーリングでき、本番環境では callback.url を使用できます。success の場合、data.output[0].url が期限切れになる前にダウンロードしてください。

次に完全な Kling Omni API リファレンスを読み、テストリクエストを準備する際に現在のモデルページを開いてください。