チュートリアル

Kling 2.5 Turbo 画像から動画へのAPIの使い方（curl + Python）

実行可能なファーストフレームからの動画生成ウォークスルー：タスクの作成、ポーリング、MP4のダウンロード——そして厳格な入力スキーマの完全なリスト。

Oct 21, 2026

TL;DR

kling-2.5-turbo/image-to-video は1枚のファーストフレーム画像を5秒または10秒の動画クリップに変換します。2枚目の画像URLを渡すと最終フレームを固定できます。このモデルはHiAPIの非同期タスクAPI上で動作します——まず POST /v1/tasks でタスクを作成し、次に GET /v1/tasks/{taskId} をポーリングして生成されたMP4を取得します。
出力料金は1秒あたり$0.06です：5秒クリップは$0.30、10秒クリップは$0.60。課金は完了した出力の秒数に基づき、入力が無効で失敗したタスクは出力を生成せず、課金もされません。
入力スキーマは厳格かつ閉鎖的です。必須：image_urls（配列、1〜2項目——複数形であることに注意）、prompt、duration（5 または 10 のみ）。オプション：aspect_ratio、negative_prompt、cfg_scale。単数形の image_url は即座に拒否されます。
このモデルはHiAPIで公開済みです：モデルページを開くでまずブラウザ上で試してから、以下のAPIに接続してください。

構築するものと準備するもの

この記事を読み終えると、動作するファーストフレーム → 動画の呼び出しが手に入ります：画像とモーションプロンプトを送信し、タスクをポーリングし、MP4をダウンロードします。まず2つのものを準備する必要があります：

HiAPIダッシュボードからAPIキーを取得——すべてのリクエストは Authorization: Bearer sk-... の形式で送信する必要があります。まだ作成していない場合は、認証ドキュメントを参照してください。
公開アクセス可能なファーストフレーム画像のURL。作成呼び出しは入力の構造のみを検証します。画像は実際にはタスク実行時に取得されるため、localhost やプライベートURLは後で失敗するタスクを作成してしまいます（詳細は後述）。

これは画像から動画への生成なので、モデルIDは kling-2.5-turbo/image-to-video です。プロンプトのみから動画を生成したい場合は、別のテキストから動画へのエンドポイントがあります。

最小限の動作例（curl）

タスクを作成します。モデル名はトップレベルに置き、モデルが読み取るすべての内容は input 内に置きます：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-2.5-turbo/image-to-video",
    "input": {
      "prompt": "The perfume bottle rotates slowly on the marble stand, light glints across the glass, petals drift down, slow orbit",
      "image_urls": ["https://static.hiapi.ai/gallery/2026/10/4852c542c4447593.jpg"],
      "duration": 5,
      "aspect_ratio": "9:16"
    }
  }'

作成に成功するとタスクIDが返されます——動画ではありません：

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

次に、status が終態になるまで詳細エンドポイントをポーリングします：

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01M5CW... \
  -H "Authorization: Bearer sk-YOUR_KEY"

タスク実行中は非終態のステータスが表示されます。完了後、data.output[0].url の下でMP4 URLを取得できます：

{
  "code": 200,
  "data": {
    "status": "success",
    "model": "kling-2.5-turbo/image-to-video",
    "storage": "temp",
    "output": [{ "url": "https://temp.hiapi.ai/kling-i2v/tk-hiapi-01M5CW.mp4?expireAt=1761350400" }]
  },
  "message": "success"
}

この output[0].url は一時リンクです——アプリ内で直接ホットリンク参照するのではなく、すぐにダウンロードしてください（本番環境の注意事項を参照）。

最小限の動作例（Python）

SDKは不要です——HiAPIタスクAPIは純粋なHTTPインターフェースなので、標準ライブラリで十分です：

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY", "Content-Type": "application/json"}


def create(image_url: str, prompt: str, duration: int = 5) -> str:
    payload = {
        "model": "kling-2.5-turbo/image-to-video",
        "input": {
            "prompt": prompt,
            "image_urls": [image_url],   # 1–2 items; 2nd = last frame
            "duration": duration,        # 5 or 10 only
        },
    }
    r = requests.post(API, json=payload, headers=HEADERS, timeout=60)
    body = r.json()
    task_id = (body.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: {body}")
    return task_id


def wait(task_id: str, timeout_s: int = 600, interval: int = 5) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30)
        task = r.json().get("data") or {}
        status = task.get("status")
        if status == "success":
            return task["output"][0]["url"]
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(interval)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


task_id = create(
    "https://static.hiapi.ai/gallery/2026/10/4852c542c4447593.jpg",
    "slow orbit around the product, light glints across the glass, petals drift down",
    duration=5,
)
mp4_url = wait(task_id)

# Download immediately — the URL is short-lived.
with requests.get(mp4_url, stream=True, timeout=120) as resp:
    resp.raise_for_status()
    with open("clip.mp4", "wb") as f:
        for chunk in resp.iter_content(1 << 16):
            f.write(chunk)
print("saved clip.mp4")

本番環境の注意事項

ポーリングかコールバックを使用する。 5秒ごとのポーリング（上記の通り）が最もシンプルな方法であり、例で使用している方法です。結果をプッシュ通知で受け取りたい場合は、作成呼び出しがトップレベルの callback オブジェクト——{"url": "https://you/webhook", "when": "final"}——を受け付け、タスクが終態になるとHiAPIがあなたのエンドポイントにPOSTリクエストを送信します。正確なwebhookの契約についてはタスク作成ドキュメントを参照してください。ほとんどの単一クリップタスクでは、タスク詳細エンドポイントのポーリングで十分です。

常に data.status に基づいて分岐し、作成呼び出しのHTTPステータスコードには基づかないでください。 作成が 200 を返すのは受け付けられたという意味であり、レンダリングされたという意味ではありません。詳細エンドポイントが status: "success" を返したときのみ、クリップは実際に存在します。

出力URLは一時リンクとして扱ってください。 storage は temp であり、URLは期限切れになるため、タスク成功後すぐにMP4をダウンロードしてください（または独自のストレージバケットにコピーしてください）。HiAPIのURLをエンドユーザーに直接提供しないでください。

コスト管理。 完了した出力の秒数に対して支払います——$0.06/秒——そのため5秒クリップは$0.30、10秒クリップは$0.60です。プロンプトとファーストフレームを反復する間は5秒でレンダリングし、満足したら10秒で再実行してください。最新の価格は価格ページを参照してください。

実測ノートと注意事項

この記事のすべての内容は、単なるパラメータ表ではなく、実際のエンドポイントへの実際のリクエストに基づいています（スキーマは2026-10-21に再検証済み）：

フィールドは image_urls（複数形）であり、スキーマは閉鎖的です。 自然に見える image_url を送信すると、タスク作成前に失敗します：
```
{ "code": 400, "error_code": "INVALID_REQUEST",
  "message": "invalid input: image_urls: missing required field \"image_urls\"; <root>: additional properties 'image_url' not allowed" }
```
認識できないフィールド（mode、タイポなど）は同様に拒否されます——黙って無視される追加フィールドは存在しません。
duration は列挙型であり、範囲ではありません。 5 と 10 のみ受け付けます。7 は duration: value must be one of 5, 10 を返します。
image_urls は1または2項目を含みます。 1つのURLはファーストフレームです。2つ目のURLは最終フレームを固定し、制御されたトランジションを実現します。3つのURLは maxItems: got 3, want 2 を返します。空の配列は minItems: got 0, want 1 を返します。
実際に存在するオプションフィールド： aspect_ratio は 16:9、9:16、1:1、4:3、3:4、21:9 のみ受け付けます。cfg_scale の上限は 1 です（99 を渡すと cfg_scale: maximum: got 99, want 1 を返します）。negative_prompt は文字列でなければなりません。aspect_ratio を省略すると、モデルはファーストフレームに従います。
作成呼び出しは構造のみを検証し、到達可能性は検証しません——これが最もハマりやすいポイントです。 構文的に有効だがアクセスできない画像URLは 200 と taskId を返し、その後タスクは非同期で失敗に変わります：
```
{ "data": { "status": "fail",
  "error": { "code": "INVALID_REQUEST",
    "message": "The image URL is not readable. Please provide a valid public HTTP(S) URL or an accessible file path and try again." } } }
```
このタスクは output を生成せず、課金もされません——失敗は費用を発生させません——しかし、作成レスポンスだけをチェックすると成功したと誤解してしまいます。これこそがポーリングループで data.status に基づいて判断すべき理由です。

よくある質問

クリップはどのくらいの長さにできますか？ 5秒または10秒です——これらはスキーマが受け付ける唯一の2つの duration 値です。

結末を制御できますか？ はい。image_urls に2つのURLを入れます：1つ目は開始フレーム、2つ目は最終フレームです。モデルはその間を補間してモーションを生成します。

作成は200を返すのに、なぜタスクが fail になるのですか？ 作成呼び出しはJSONがスキーマに準拠しているかどうかだけを検証します。画像はタスク実行時に取得されるため、アクセスできないURLやプライベートURLはタスクを作成した後、タスクを失敗させます。常に詳細エンドポイントから data.status を読み取り、ファーストフレームURLが公開アクセス可能であることを確認してください。

失敗したタスクは課金されますか？ いいえ。完了した出力の秒数に対して課金されるため、入力が無効で失敗したタスクは output を生成せず、課金もされません。

アスペクト比の制御はありますか？ aspect_ratio はオプションで、16:9、9:16、1:1、4:3、3:4、21:9 を受け付けます。空にするとファーストフレームに従います。