Kling 3.0 Turbo テキストtoビデオ API の使い方：パラメータ、コード、エラー

TL;DR

• Kling 3.0 Turbo テキストtoビデオのモデル名は kling-3.0-turbo/text-to-video で、Kling 3.0 の高速版です。モデルページを開くとオンラインで試せます。
• 秒単位の課金：720p は 1 秒 $0.13、1080p は 1 秒 $0.16。長さは 3〜15 秒の任意の整数、5 秒 720p で 1 本 $0.65。
• パラメータは 4 つだけ：prompt、duration、aspect_ratio、resolution。それ以外のフィールド（seed、negative_prompt など）を渡すと 400 が返ります。

まず 1 本見てみる

720p、5 秒、16:9：

aerial drone shot sweeping over a norwegian fjord waterfall, mist drifting,
camera gliding forward, smooth natural motion, stable cinematic camera
movement, consistent lighting across frames, cinematic composition, dramatic
directional lighting, rich cohesive color grade, ultra-detailed, premium
commercial finish

このプロンプトで生成 →（5 秒、720p、16:9）

kling-3.0-turbo/text-to-video、5 秒。

パラメータ早見表

フィールド	必須	値	説明
prompt	はい	最大 2500 文字	画面、被写体、動作、カメラワーク。引用符内のセリフはリップシンクに対応
duration	いいえ	整数 3〜15、デフォルト 5	秒単位の課金、1 秒増えればその分の料金
aspect_ratio	いいえ	16:9（デフォルト）/ 9:16 / 1:1	横長、縦長、正方形
resolution	いいえ	720p（デフォルト）/ 1080p	1 秒あたりの単価を決める

sound フィールドはありませんが、生成された動画には音声が付いており、オフにはできません。4K、ラストフレーム、参照画像もありません。これらが必要なら Kling 3.0 標準版か Omni を使ってください。

curl：最初の 1 本を動かす

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0-turbo/text-to-video",
    "input": {
      "prompt": "A golden retriever surfing a turquoise wave at sunset, cinematic slow motion, water droplets frozen mid-air",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p"
    }
  }'

レスポンスには data.taskId だけが含まれます。5〜10 秒ごとに GET /v1/tasks/{taskId} をポーリングし、status が success になったら output[0].url から動画をダウンロードします。

Python：送信、ポーリング、ダウンロード

# pip install requests; export HIAPI_KEY=あなたのKey
import os, time, uuid, requests

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

def generate(timeout_s=900, **inp):
    # 同じ送信をリトライするときは同じ Idempotency-Key を再利用すると、課金は 1 回だけ
    r = requests.post(API, json={"model": "kling-3.0-turbo/text-to-video", "input": inp},
                      headers={**H, "Idempotency-Key": str(uuid.uuid4())}, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(d)
        time.sleep(8)
    raise TimeoutError(task_id)

# 縦長 3 秒 720p で方向性を試す、$0.39
url = generate(
    prompt="A barista pours latte art in slow motion, close-up, warm cafe light",
    duration=3, aspect_ratio="9:16", resolution="720p",
)
with open("clip.mp4", "wb") as f:
    f.write(requests.get(url).content)

料金

長さ	720p（$0.13/秒）	1080p（$0.16/秒）
3 秒（最短）	$0.39	$0.48
5 秒	$0.65	$0.80
10 秒	$1.30	$1.60
15 秒（最長）	$1.95	$2.40

HiAPI 現行価格、2026 年 10 月 18 日確認。

失敗時は課金されません。詳しい比較は Kling 3.0 Turbo API 価格をご覧ください。

遭遇するエラー

渡したもの	返り値
prompt を渡していない	400、missing required field "prompt"
余分なフィールドを渡した（seed、negative_prompt など）	400、additional properties ... not allowed
duration: 2	400、duration: minimum: got 2, want 3
duration: 99	400、duration: maximum: got 99, want 15
aspect_ratio: "4:3"	400、16:9、9:16、1:1 のみ可
resolution: "480p"	400、720p、1080p のみ可
Key が誤っているか欠けている	401、permission_denied
残高不足	402、まずチャージしてから原因を調査

パラメータエラーは送信時に同期的に返ります。生成失敗は後からポーリングしたときに status が fail となり、エラーは data.error に入ります。両方の経路を処理する必要があります。

本番投入前の注意

• ポーリングの代わりにコールバックを使う：input と同じ階層に "callback": {"url": "https://your-app.example.com/hiapi/callback", "when": "final"} を追加すると、タスク終了時に 1 回だけ通知されます。taskId で重複排除してください。
• Idempotency-Key リクエストヘッダーを付ける：タイムアウトでリトライするときは同じ Key を使えば、タスクは 1 つだけ作成され、課金も 1 回だけです。
• 結果はすぐにダウンロード：output[0].url には有効期限があります。
• 15 秒を超えるなら分割：前のクリップの最終フレームを kling-3.0-turbo/image-to-video に最初のフレームとして渡し、続きを生成します。

よくある質問

1 本にどのくらいかかりますか？

分単位です。長さが長いほど、解像度が高いほど時間がかかります。ポーリングの上限は 10〜15 分を推奨します。またはコールバックを直接使ってください。

ネガティブプロンプトは使えますか？

使えません。避けたいものはプロンプトに直接書いてください。例えば「no text overlays, no watermarks」のように。

Turbo と Kling 3.0 標準版はどう選びますか？

Turbo は速度重視のモデルで、音声が付いています。標準版は音声オフの 720p なら 1 秒 $0.10 で安く、音声はオン/オフを選べ、4K も出力できます。同じプロンプトでの比較は Kling 3.0 Turbo vs Kling 3.0 をご覧ください。

上のフィヨルドのプロンプトをコピーして、$0.39 で 3 秒のテストを 1 本生成してください。