Python での Kling 3.0 Turbo イメージ・トゥ・ビデオ API：スキーマ、完全スクリプト、エラー処理

kling-3.0-turbo/image-to-video のスキーマは小さく厳格です。公開画像 URL 1 つ、必須のモーションプロンプト、3〜15 秒の整数の duration、そして 720p または 1080p の出力です。本ページはこのバージョン専用のリファレンスであり、リクエストボディを検証し、HTTP 400 エラーと非同期の TASK_FAILED 結果を区別するために使用します。

汎用的な作成・ポーリング・コールバック・ダウンロードの流れについては、Kling Python タスクランナーと Omni/Turbo 選択ガイドをご利用ください。

Turbo 入力スキーマ

フィールド	型	必須	受け付け可能な値
prompt	string	はい	モーションとカメラの挙動を記述
image_urls	文字列配列	はい	公開アクセス可能な画像 URL をちょうど 1 つ
duration	integer	いいえ	3〜15 秒
resolution	string	いいえ	720p または 1080p

Turbo は sound、aspect_ratio、negative_prompt、seed、mode を受け付けず、2 つ目の画像 URL も受け付けません。厳格なスキーマでは追加属性は黙って無視されるのではなく、拒否されます。

入力画像が画面の形状を決定します。タスクを作成する前に、公開ストレージバケットまたは CDN にアップロードしてください。レンダラーは localhost、プライベートなダッシュボード、有効期限切れの署名付き URL を取得できません。

最小限の有効なリクエスト

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0-turbo/image-to-video",
    "input": {
      "prompt": "The runner accelerates as the camera tracks from the side",
      "image_urls": ["https://cdn.example.com/first-frame.jpg"],
      "duration": 6,
      "resolution": "1080p"
    }
  }'

成功したレスポンスには data.taskId が含まれます。HTTP 200 は作成が成功したことのみを意味し、完了を意味するものではありません。動画のレンダリングは非同期で進行中です。

Python による事前検証

ネットワーク呼び出しの前に制約を検証し、明らかなエラーがタスクを作成しないようにします：

from urllib.parse import urlparse

import requests


def turbo_input(prompt: str, image_url: str, duration: int, resolution: str) -> dict:
    if not prompt.strip():
        raise ValueError("prompt is required")
    if type(duration) is not int or not 3 <= duration <= 15:
        raise ValueError("duration must be an integer from 3 to 15")
    if resolution not in {"720p", "1080p"}:
        raise ValueError("resolution must be 720p or 1080p")
    parsed = urlparse(image_url)
    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
        raise ValueError("image_url must be a public HTTP(S) URL")

    return {
        "prompt": prompt,
        "image_urls": [image_url],
        "duration": duration,
        "resolution": resolution,
    }


payload = {
    "model": "kling-3.0-turbo/image-to-video",
    "input": turbo_input(
        prompt="The runner accelerates as the camera tracks from the side",
        image_url="https://cdn.example.com/first-frame.jpg",
        duration=6,
        resolution="1080p",
    ),
}

response = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": "Bearer sk-your-key"},
    json=payload,
    timeout=30,
)
response.raise_for_status()
task_id = response.json()["data"]["taskId"]
print(task_id)

このローカルチェックは値の形式の問題を検出できますが、リモート画像が公開ダウンロード可能であることを証明することはできません。レンダラーはタスク作成後にその取得を実行します。

完全な Python スクリプト：送信・ポーリング・ダウンロード

上記のコードスニペットはタスク ID で終わります。このバージョンはジョブ全体を実行し、MP4 を保存します。Idempotency-Key ヘッダーを送信するため、タイムアウト後に同じ送信を再試行すると、2 つ目のタスクを作成して課金するのではなく、元のタスクが返されます：

import os
import time
import uuid

import requests

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


def run_turbo(prompt: str, image_url: str, duration: int = 5,
              resolution: str = "720p", out_path: str = "turbo.mp4") -> str:
    body = {
        "model": "kling-3.0-turbo/image-to-video",
        "input": turbo_input(prompt, image_url, duration, resolution),
    }
    key = str(uuid.uuid4())  # reuse this key if you retry the same submission
    r = requests.post(API, json=body, headers={**HEADERS, "Idempotency-Key": key}, timeout=30)
    if r.status_code == 400:
        raise ValueError(f"schema error, no task created: {r.text}")
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    deadline = time.time() + 900
    while time.time() < deadline:
        data = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        if data["status"] == "success":
            video = requests.get(data["output"][0]["url"], timeout=120)
            video.raise_for_status()
            with open(out_path, "wb") as f:
                f.write(video.content)  # the output URL is temporary, so save it now
            return out_path
        if data["status"] == "fail":
            raise RuntimeError(f"TASK_FAILED {task_id}: {data.get('error')}")
        time.sleep(10)
    raise TimeoutError(task_id)


print(run_turbo(
    "The runner accelerates as the camera tracks from the side",
    "https://cdn.example.com/first-frame.jpg",
))

この 5 秒の 720p クリップの料金は $0.65 です。本番環境では、ポーリングループを最上位の "callback": {"url": "https://your-app.example.com/hiapi/callback"} で置き換え、通知をタスク ID で重複排除してください。

HTTP 400：タスクが作成されなかった

HTTP 400 レスポンスは同期スキーマ検証の結果です。典型的な原因は次のとおりです：

無効な入力	失敗する理由	修正方法
"duration": "5"	整数ではなく文字列を送信した	5 を送信する
"duration": 20	最大値は 15	3〜15 を選択
image_urls が 2 つ	Turbo は 1 つしか受け付けない	開始フレームのみを保持
"resolution": "4K"	Turbo は 720p と 1080p をサポート	720p または 1080p を使用するか、Omni を選択
"sound": true	sound は Turbo スキーマに存在しない	そのフィールドを削除するか、Omni を選択
prompt の欠落	Turbo はプロンプトを必要とする	空でないモーションプロンプトを追加

検証は作成前に失敗するため、ポーリングできるタスク ID はありません。レスポンスボディとリクエスト ID を記録し、リクエストボディを修正して新しいリクエストを再送信してください。

TASK_FAILED：作成は成功したがレンダリングに失敗した

POST /v1/tasks が HTTP 200 とタスク ID を返した場合、その後の失敗は非同期タスクのライフサイクル上の問題であり、400 とは区別して扱う必要があります。

一般的な原因は次のとおりです：

• 画像 URL に Cookie または認証ヘッダーが必要；
• 署名付き画像 URL がレンダラーの取得前に期限切れになった；
• ホストがサーバー側の取得をブロックしている、または HTML ページにリダイレクトする；
• ファイルが破損している、またはメディアタイプが内容と一致しない；
• プロバイダーがそのレンダリングを完了できない。

タスク ID、最終的なエラーコードとメッセージ、元の入力 URL、リクエスト時刻を記録してください。再試行する前に、認証なしのサーバーがその画像を 2xx レスポンスと画像のコンテンツタイプで取得できることを確認してください。アクセスできない同じ URL を盲目的に再試行しても、失敗するタスクがもう 1 つ作成されるだけです。

汎用のPython ガイドには、共通の終状態ポーリングループと出力ダウンロードのコードが含まれています。そこに置いておくことで、本バージョンのリファレンスページでライフサイクルロジックを重複させずに済みます。

Turbo の料金とモデル選択

現在の本番料金は次のとおりです：

Turbo ティア	1 秒あたりの料金	5 秒タスク
720p	$0.130	$0.65
1080p	$0.160	$0.80

大量使用の前に、最新の料金ページを確認してください。Turbo という名称はモデル変種を表すものであり、すべての解像度で安くなることや、タスクが固定のレンダリング時間 SLA を満たすことを約束するものではありません。

ラストフレーム、音声、4K が必要な場合は、標準の Kling 3.0（kling-3.0/image-to-video）を選択してください。1 枚または 2 枚の画像（開始フレームと終了フレーム）を受け付け、sound スイッチを備え、720p 音声なしで $0.10/s、1080p 音声なしで $0.129/s です。参照画像や参照動画が必要な場合は Omni を選択してください。720p または 1080p の単一入力フレームについては、独自のモーションプロンプトでこれらの変種をベンチマークし、出力品質、待ち時間、総コストを評価してください。

よくある質問

Kling 3.0 Turbo イメージ・トゥ・ビデオは何枚の画像を受け付けますか？

公開画像 URL をちょうど 1 つです。2 つ目の画像はスキーマエラー（image_urls: maxItems: got 2, want 1）を引き起こします。開始フレームと終了フレームの制御が必要な場合は、標準の Kling 3.0 イメージ・トゥ・ビデオを使用してください。

有効な duration の値は？

3〜15 の整数を送信してください。"5" のような引用符付きの数字は文字列であり、検証に失敗します。

Turbo は 4K や音声をサポートしますか？

4K はサポートしません。このエンドポイントは 720p または 1080p を受け付けます。sound フィールドはありませんが、Turbo のクリップには音声が含まれており、オフにすることはできません。4K または無音の出力が必要な場合は、標準の Kling 3.0 または Omni を使用してください。

HTTP 400 と TASK_FAILED の違いは何ですか？

HTTP 400 はリクエストがスキーマに違反していることを意味するため、タスクは作成されません。TASK_FAILED は有効な作成レスポンスの後に発生し、入力の取得または生成の段階で起こります。

一見公開されている画像 URL が TASK_FAILED を引き起こすのはなぜですか？

その URL が Cookie に依存している、署名が期限切れになっている、サーバー側の取得をブロックしている、または画像バイトではなく HTML を返している可能性があります。再試行する前に、ブラウザの認証なしでテストしてください。