チュートリアル
HiAPI API で kling-4.0-flash の image-to-video を使う方法:curl と Python
実践的なリクエストウォークスルー:先頭フレーム画像入力、非同期タスクポーリング、同期音声、エラー調査
- モデル
- kling-4.0-flash
このページの内容
kling-4.0-flash image-to-video エンドポイントの役割
kling-4.0-flash/image-to-video は画像を条件とする動画生成モデルです。画像——つまり先頭フレーム——とテキストプロンプトを渡すと、そのフレームから始まり、あなたの記述に沿って展開する生成動画が返されます。
コードを書く前に最も内面化すべき点:これは 1 回の HTTP 交換で動画バイトを返すリクエスト/レスポンス型の呼び出しではありません。生成には時間がかかるため、このエンドポイントは非同期タスクモデルに従います。最初のリクエストでタスクを送信し、その後タスク状態をポーリングして終了状態になるまで結果を取得します。
次の 3 つの概念を頭の中で区別しておいてください。これらはクライアントの 3 つの異なる部分に対応します:
- 送信——送るペイロード:先頭フレーム画像、プロンプト、生成オプション。
- タスク参照——送信時に返される識別子で、後でそのタスクを問い合わせるために使います。
- 結果取得——状態を繰り返し確認し、最終的に完成した動画(または失敗)を返します。
エンドポイントを RPC ではなくタスクキューとして捉えれば、統合の残りの部分——ポーリング間隔、タイムアウト、リトライ——は特殊ケースではなく普通の非同期パイプラインになります。このウォークスルー以外にもより完全なエンドポイントドキュメントを参照したい場合は、別タブで開いて並べながら操作してください。
リクエストを送る前に
最初の呼び出しの前に 3 つ準備が必要です。
1. API 認証情報
HiAPI API キーが必要です。すべてのリクエストで Authorization ヘッダーに bearer トークンとして送信します。ソース管理に含めないでください——スクリプトに貼り付けるのではなく、環境変数から読み取ります。
export HIAPI_API_KEY="your-api-key-here"
2. エンドポイントパス
すべての呼び出しは統一された HiAPI インターフェース経由で行います。対象となるモデル識別子は kling-4.0-flash/image-to-video です。送信リクエストと後続の状態問い合わせは同じモデル名前空間を指すため、この識別子はコード内の 1 つの定数に置き、文字列リテラルをあちこちに散らばめないようにしてください。
3. 準備された先頭フレーム画像
開始フレームとなる画像が必要です。送信前に 2 点を確定します:
- どのように渡すか——公開アクセス可能な URL としてか、エンコードされた画像データとしてかは、あなたのユースケースでこのエンドポイントが受け付ける形式によります。
- 形式が適切か——形式が正しく、読み取り可能で、リクエストボディが肥大化しない程度の大きさであること。
実用的なルール:リクエストボディは小さく明確に保ちます。URL を渡す場合は、呼び出し元が認証なしでアクセスできることを確認してください。エンコードデータを渡す場合は、エンコードがエンドポイントの期待どおりであることを確認してください。
同時に、短く具体的なプロンプトも用意します。image-to-video のプロンプトは、フレーム内に見えている内容を復唱するのではなく、動きと変化(何が動くか、カメラがどう動くか)を記述するときに最もうまく機能します。
動作する curl リクエスト
以下は完全な送信呼び出しです。プレースホルダーを自分のキー、画像、プロンプトに置き換えてください。
curl -X POST "https://api.hiapi.ai/v1/models/kling-4.0-flash/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Slow dolly-in on the subject as light shifts across the scene",
"image": "https://your-host.example/first-frame.jpg"
}'
項目ごとの説明:
-X POST——送信は書き込み操作であり、クエリではありません。- URL——モデル識別子は統一エンドポイントパスの一部です。モデルを指定するのはここだけです。
Authorization: Bearer $HIAPI_API_KEY——シェルが環境変数から展開するヘッダーです。二重引用符で囲むことで変数展開をしつつ、値を 1 つの引数として保てます。Content-Type: application/json——ボディは JSON です。このヘッダーがないと、一部のゲートウェイはペイロードを拒否したり誤解析したりします。-d '{ ... }'——JSON ボディです。promptは動きを記述し、imageは先頭フレームを提供します。各フィールドは明示的です——位置や見えないデフォルト値に暗黙に依存するものはありません。
送信に成功すると、タスク識別子を含む JSON ボディが返されます。それを捕捉してください——その値がそのタスクを操作するハンドルになります。対話的に探索しているなら、レスポンスを JSON 整形ツールに通して識別子をコピーすると便利です:
curl -s -X POST "https://api.hiapi.ai/v1/models/kling-4.0-flash/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt":"Slow dolly-in as light shifts","image":"https://your-host.example/first-frame.jpg"}' | python -m json.tool
動画がこのレスポンスにあると考えないでください。ありません——このレスポンスはタスクが受け付けられたことだけを伝えます。
同じリクエストを Python で実装する
Python クライアントは curl ペイロードに完全に対応します。言語を変えてもセマンティクスは変わらず、バイトを送る仕組みが変わるだけです。requests を使い、キーは環境変数から読み取ります:
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "kling-4.0-flash/image-to-video"
BASE_URL = "https://api.hiapi.ai/v1/models"
def submit_job(prompt: str, image: str) -> dict:
response = requests.post(
f"{BASE_URL}/{MODEL}",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json={
"prompt": prompt,
"image": image,
},
timeout=30,
)
response.raise_for_status()
return response.json()
job = submit_job(
prompt="Slow dolly-in on the subject as light shifts across the scene",
image="https://your-host.example/first-frame.jpg",
)
print(job)
移植のポイント:
-dの代わりにjson=——dict を渡すとrequestsがボディをシリアライズし、コンテンツタイプを設定します。手書きの JSON なしで、curl の例と同じワイヤーフォーマットになります。raise_for_status()——非 2xx レスポンスを例外に変換し、エラーボディをタスク参照と誤認しないようにします。timeout=30——送信はすぐに終わるはずです。余裕のあるタイムアウトは、本当に遅い呼び出しを覆い隠すことなく、接続のハングを防ぎます。- モデルは 1 つの定数——後でモデルを切り替えるときは 1 行を変えるだけです。
返される dict にはタスク識別子が含まれており、次のセクションでそれを活用します。
非同期タスクのライフサイクルを扱う
統合パターンはまず送信し、次にポーリングです。2 つのフェーズが明確に分かれています。
フェーズ 1:送信して参照を捕捉する
前セクションの submit_job 呼び出しはタスク識別子を含む JSON ボディを返します。それを保存してください。以降のすべての状態確認で必要になり、失えばそのタスクを失います。
フェーズ 2:終了状態になるまでポーリングする
状態確認は同じタスクへの読み取りリクエストです。固定間隔で繰り返し、タスクが終了状態——完了または失敗——に達するまで続けます。試行回数に上限を設けたシンプルなループ:
import time
def wait_for_job(task_id: str, attempts: int = 60, interval: float = 5.0) -> dict:
for _ in range(attempts):
response = requests.get(
f"{BASE_URL}/{MODEL}",
headers={"Authorization": f"Bearer {API_KEY}"},
params={"task_id": task_id},
timeout=30,
)
response.raise_for_status()
status = response.json()
state = status.get("status")
if state in ("succeeded", "failed"):
return status
time.sleep(interval)
raise TimeoutError(f"Job {task_id} did not finish in time")
意図的に下すべき設計判断:
- ループ回数を制限する。無限にポーリングしないでください。最大試行回数と固定間隔により、予測可能な最悪待ち時間が得られます。
- リクエスト内ではなく、チェックの間にスリープする。過度に頻繁なポーリングはクォータを浪費し、レート制限を引き起こす可能性があります。
- 失敗を終了状態として扱う。失敗したタスクは次のポーリングで成功に変わることはありません——停止し、エラーを明らかにします。
- 待機中と完了済みを区別する。終了状態だけがループを終わらせます。それ以外の状態は待機継続を意味します。
- タスク ID を永続化する。プロセスがポーリング途中でクラッシュした場合、再生成ではなく復帰できるようにしたいものです。
本番環境ではポーリングをリクエストスレッドの外に移してください——バックグラウンドワーカーやキューのコンシューマーに任せる——そうすれば長時間の生成で Web リクエストを開いたままにせずに済みます。
同期音声オプションを使う
このエンドポイントは同期音声オプションを提供します。実践的には、これはクライアントにとって 1 つのことを意味します:有効にすると、呼び出しはポーリング用のタスク参照を返すのではなく、生成が完了するまでブロックします。
これは具体的に設計を変えます:
- タイムアウトの予算を増やす必要がある。ブロッキング形式の生成呼び出しは、典型的な API リクエストよりはるかに時間がかかる可能性があります。クライアントのタイムアウトは送信時間ではなく、想定される全体の所要時間をカバーするように設定してください。
- 途中でチェックポイントを置けない。ポーリングではクラッシュしてもタスク ID で復帰できます。ブロッキング呼び出しでは、接続が切れると作業をやり直すことになります。
- スレッドとコネクションプールへの負荷。ブロッキング呼び出しは持続時間全体にわたって 1 つのワーカーを占有します。Web サーバーではこれが並行処理能力を急速に制限します。
ブロッキング呼び出しが許容できるのはいつか?ワンオフスクリプト、CLI ツール、バッチ処理を実行していて、他に結果を待つものがなく、単純さがスループットより優先される場合です。これらのシナリオでは、同期呼び出しはポーリング機構を完全に取り除き、コードも短くなります。
いつ避けるべきか?ユーザー向けのあらゆるリクエストパス、高並行サービス、またはクライアントがタイムアウトしてリトライする可能性があるあらゆる場所です——リトライされたブロッキング呼び出しは作業量を倍にしかねません。これらのシナリオでは、前セクションの非同期送信+ポーリングパターンを維持し、同期オプションをオフにしてください。
よくある失敗をトラブルシュートする
失敗は層ごとに処理してください。最初に見えるエラーは通常最も浅い層のものなので、複数の問題を一度に推測するのではなく、それを修正して再実行します。
認証エラー
401 または 403 は、認証情報が欠落、形式不正、または拒否されたことを意味します。HIAPI_API_KEY がプロセスから見える環境に実際に設定されているか確認してください——あるシェルで export した変数は別のシェルやコンテナには引き継がれません。Authorization ヘッダーが Bearer <key> であり、スペースが 1 つだけで、コピー&ペーストによる余計な引用符がないことを確認してください。
ペイロード形式エラー
400 は通常、ボディが解析できないか必須フィールドが欠けていることを意味します。Content-Type: application/json を送ったか、JSON が有効か(末尾カンマは失敗します)、prompt と image の両方が存在し空でない文字列か、を再確認してください。デバッグ時には、送るつもりの dict ではなく、実際に送ったボディをダンプしてください。
画像入力の問題
これらの問題は通常、明示的な画像エラーではなく検証エラーとして現れます。順番に確認してください:
- 到達可能性——URL を渡す場合は、リクエストの発信元と同じネットワーク環境から取得してください。ブラウザでは動作する URL が、API にとってはファイアウォールで遮断されたり認証で保護されたりしている可能性があります。
- 形式——画像がサポートされた破損のないファイルであることを確認してください。疑わしい場合は再エクスポートしてください。
- サイズ——大きすぎる画像は検証失敗を引き起こしたり、リクエストボディを制限を超えて肥大化させたりします。
- エンコード——エンコードデータを送る場合は、エンコードがエンドポイントの期待と正確に一致することを確認してください。一致しないプレフィックスや余分な空白は失敗の原因になります。
タスクレベルの失敗
送信は成功したがタスクが失敗状態で終了した場合、リクエストは形式が正しくても生成が完了しなかったことを意味します。プロンプトを読み直し、曖昧さや物理的に不合理な動きがないか確認し、先頭フレーム画像が本当に開始点として使えるか確認してください。簡略化したプロンプトで 1 回リトライしてからシステム的な問題を仮定し、タスク ID と失敗情報を記録して後で関連付けられるようにしてください。
ポーリングループのタイムアウト
wait_for_job が投げる TimeoutError は、タスクが死んだのではなく、上限が厳しすぎることを意味します。試行回数または間隔を増やし、より古い終了済み実行のタスク ID をポーリングしていないか確認してください。
最小限のリクエストから始めてください——画像 1 枚、短いプロンプト、オプションフィールドなし——そしてベースラインが動作してから複雑さを加えます。ペイロードが小さく明確であれば、統合の問題のほとんどは解消します。