HiAPI
ブログ

チュートリアル

HiAPI API で kling-4.0-flash Reference-to-Video を呼び出す方法:curl と Python の実践

複数参照画像による動画生成の実行可能な呼び出し実践、非同期ポーリング、トラブルシューティングガイド

Nov 12, 2026
カバー画像:淡い紫と墨色の2つの大きな平面色ブロックがまっすぐな硬い境界線に沿って接し、その縁には細く狭い紫の継ぎ目が埋め込まれており、構図は抑制が効いて静かである。
モデル
kling-4.0-flash
このページの内容

参照画像による動画生成を、テキストからの動画生成ではなく使うべき場面

テキストからの動画生成は脚本家のツールだ。シーンを記述すれば、モデルがゼロからすべてを創造する。参照画像による動画生成は監督のツールだ。モデルに 1 枚または複数の画像を渡し、それらの主体、スタイル、構図が識別可能なまま動きのある映像を生成するよう要求する。HiAPI では、この違いはエンドポイントのレベルに現れる——kling-4.0-flash/reference-to-video は通常のテキストからの動画生成呼び出しとは別の独立したルートであり、事前に正しいエンドポイントを選ぶことで、特定の外観を完全に再現できないプロンプトエンジニアリングに陥ることを避けられる。

以下のいずれかに該当する場合は、参照画像による動画生成を選ぶこと:

  • アイデンティティや製品の一貫性が極めて重要。 キャラクター設定画、製品写真、マスコットがあり、出力が一般的な類似イメージに崩れてはならない。
  • 複数のソースを組み合わせる必要がある。 1 つのシーンで、ある画像がキャラクターを決め、別の画像が環境や衣装を決める必要があるかもしれない。複数の参照画像を使えば、散文で説明するのではなく、この構図を明確に表現できる。
  • スタイル転送自体が目的。 与えられた画面の色調、照明、レンダリングスタイルを動きのある映像に持ち込みたい。
  • 特定のショットを反復している。 参照画像があれば、視覚的アンカーが固定されるため、複数回の再実行が比較可能になり、動きに関連するパラメータだけを調整すればよい。

コンセプトを探索している場合、権利が明確な画像をアンカーとして使えない場合、または要件自体が抽象的(「夜明けの霧の中を通過するゆっくりとした空撮」)で、妥当な解釈であればどれでも許容される場合は、引き続きテキストからの動画生成を使うこと。参照画像はモデルを制約するが、制約は本当に必要なときにのみ有益だ。

実用的なルール:特定の物体の正確な外観を説明するために段落全体を書いていることに気づいたら、それはエンドポイントを切り替えて画像を直接提供すべきサインだ。説明はトークンを消費し、それでも崩れる。参照画像こそがアンカーになる。

リクエスト構造:参照画像とコアパラメータ

このエンドポイントは JSON リクエストボディを受け取る。実際に触れる部分は 3 つのカテゴリに分かれる:参照画像、プロンプト、そして出力を形作るパラメータだ。

参照画像

参照画像は配列として渡されるため、同じフィールドで 1 枚から複数枚へ自然に拡張できる。各エントリは、サービスが取得可能な URL だ。設計時に考慮すべき実際の制約:

  • 公開アクセス可能な HTTPS URL、またはあなたのアカウントがアクセス権を持つ URL を使用する。ローカルファイルパスや file:// URI はリモートサービスから取得できない。
  • 数分で期限切れになる署名付きリンクではなく、安定したホスティングを優先する——長時間実行されるタスクは、予想外のタイミングで取得しに行く可能性がある。
  • 各画像は焦点を絞る。散らかったコラージュよりもクリーンな主体画像のほうが役立つ。モデルは見えている内容を識別する必要があるからだ。
  • 順序は参照画像の解釈に影響する可能性があるため、コード内では辞書の反復順序に依存せず、配列の順序を決定的に保つこと。

プロンプト

参照画像を提供したら、プロンプトは外観ではなく動き、カメラワーク、雰囲気を記述すべきだ。主体がどう動くか、カメラがどう動くか、テンポがどう感じられるかを説明する。参照画像を再記述することはプロンプトの予算を無駄にし、今提供したアンカーと衝突する可能性がある。

出力を形作るパラメータ

prompt と参照画像配列に加えて、リクエストボディには通常、出力形式や生成動作を制御するフィールドが含まれる。これらは最後に調整するノブと考えること:まずデフォルト値で呼び出しを成功させ、参照画像が実際に従われていることを確認してから、出力設定を調整する。フィールド名と許容値はエンドポイントリファレンスで定義されており、認識されないフィールドを送信することはリクエストボディが拒否される一般的な原因なので、推測ではなく文書のスキーマに従って検証すること。

メンタルモデルは単純だ:参照画像は何を、プロンプトはどう動くか、パラメータは何が返ってくるかを説明する。

動作する curl リクエスト

クライアントコードを書く前に、リクエストボディを確認する最も信頼できる方法は 1 回の curl 呼び出しだ。認証情報と入力をシェル変数に設定し、JSON を読みやすく保ち、リクエストを送信する。

API_KEY="$HIAPI_API_KEY"
BASE_URL="https://api.hiapi.ai"   # コンソールに表示されるベース URL を使用

curl -sS -X POST "$BASE_URL/v1/kling-4.0-flash/reference-to-video" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "キャラクターが窓のほうへ向きを変え、カメラがゆっくりと近づく。柔らかな朝の光、落ち着いたテンポ。",
    "reference_images": [
      "https://your-cdn.example.com/refs/character-front.png",
      "https://your-cdn.example.com/refs/location-window.jpg"
    ]
  }'

実行前に 3 点を確認すること:

  1. パスとバージョンプレフィックス。 アカウントのエンドポイント文書と照らして正確なルートを確認する。パスにはバージョン番号が含まれ、古いプレフィックスは検証エラーではなく未検出を返す。
  2. 認証ヘッダー。 キーはベアラートークンとして Authorization ヘッダーに入れる。リクエストボディやクエリ文字列に入れないこと。ログに漏れる。
  3. プレースホルダー。 置き換える必要がある値はすべて明らかにプレースホルダーだ——ベース URL のコメント、2 つの CDN URL、プロンプト。本番利用可能と宣言する前に、リクエスト内で example.com を検索すること。

送信に成功すると、完成した動画ではなくタスク識別子が返る。レスポンスボディからその識別子を取得すること。次のステップのポーリングで使う。レスポンスを JSON フォーマッタ(| jq .)に通すとタスク ID がひと目で分かり、習慣にする価値がある。

同じ呼び出しの Python 版

Python 版の主な違いはリクエストボディの構築方法にある:dict を構築し、一度シリアライズし、リクエスト関数とポーリングロジックを分離して、それぞれ独立してテストできるようにする。

import os
import requests

BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai")
API_KEY = os.environ["HIAPI_API_KEY"]

REFERENCE_IMAGES = [
    "https://your-cdn.example.com/refs/character-front.png",
    "https://your-cdn.example.com/refs/location-window.jpg",
]

def submit_reference_video(prompt: str) -> str:
    payload = {
        "prompt": prompt,
        "reference_images": REFERENCE_IMAGES,
    }
    response = requests.post(
        f"{BASE_URL}/v1/kling-4.0-flash/reference-to-video",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()["task_id"]

if __name__ == "__main__":
    task_id = submit_reference_video(
        "キャラクターが窓のほうへ向きを変え、カメラがゆっくりと近づく。"
    )
    print("submitted:", task_id)

以下の注意点で不要な苦しみを避けられる:

  • キーは環境変数から読み取る。ハードコードされたキーは最終的に git 履歴やスクリーンショットに残る。
  • data= ではなく json= を使う。クライアントがコンテンツタイプを正しく設定し、リクエストボディをエスケープする。
  • 明示的な timeout を設定する。デフォルトの無限待機は、停滞した接続をハングしたワーカープロセスに変える。
  • パース前に raise_for_status() を呼び出す。4xx レスポンスボディが HTTP エラーとして報告され、レスポンス JSON 上で混乱を招く KeyError が発生しない。
  • タスク識別子のレスポンスフィールド名を task_id と仮定せず、文書で確認する。抽出行をそれに合わせて調整する。

submit_reference_video は ID だけを返すようにする。ポーリングは独立した関心事であり、独自の関数に置くべきだ。

非同期タスクのライフサイクルを扱う

動画生成には時間がかかるため、このエンドポイントは設計上非同期だ。送信呼び出しは素早くタスク識別子を返し、実際の処理はその後に行われる。あなたの統合はこれをモデル化する必要があり、最も単純な正しいモデルには 3 つの状態がある:pending または processing(待機を続ける)、succeeded(出力を取得)、failed(エラーを読み取って停止)。

タスクエンドポイントを間隔を置いてポーリングし、総待機時間に上限を設ける:

import time

def wait_for_task(task_id: str, interval: float = 5.0, max_wait: float = 600.0) -> dict:
    deadline = time.monotonic() + max_wait
    url = f"{BASE_URL}/v1/tasks/{task_id}"
    while time.monotonic() < deadline:
        r = requests.get(url, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30)
        r.raise_for_status()
        data = r.json()
        status = data.get("status")
        if status in ("succeeded", "failed"):
            return data
        time.sleep(interval)
    raise TimeoutError(f"task {task_id} did not finish within {max_wait}s")

状態文字列とタスクパスは文書の規定に合わせて調整すること——上記の構造はあくまでパターンであり、この領域での失敗のほとんどは存在しない状態ラベルを仮定したことに起因する。

早い段階で採用する価値のあるポーリングのマナー:

  • 徐々にバックオフする。 固定の短い間隔は無意味に API を繰り返し叩く。適度な値から始め、各試行間のスリープ時間を増やす。
  • 常にループを制限する。 リモートタスクを囲む while True は故障を待っているに等しい。上記の期限はハングするのではなく例外を投げる。
  • タスク ID を永続化する。 送信後にプロセスがクラッシュした場合、その ID は 2 回目の生成に課金せずに結果を回復する唯一の手段だ。
  • failed を終端状態として扱う。 失敗したタスクを再度ポーリングしてリトライしない。エラーを読み取り、適切な場合は修正したリクエストボディで再送信する。
  • 期限切れを明示的に処理する。 タスク結果が永久に取得できるとは限らないため、タスクが成功したらすぐに出力をダウンロードして保存する。

よくあるエラーと修正方法

初回統合の失敗のほとんどは少数のカテゴリに収まる。コードを変更する前に、症状と原因を対応付けること。

認証と認可の失敗

401 または 403 はほとんど常に、認証情報が誤っている、欠けている、またはスコープが正しくないことを意味する。ヘッダーが正確に Authorization: Bearer <key> であること、その環境変数が呼び出しを行うプロセスで実際に設定されていること(シェルの export は systemd ユニットには伝わらない)、キーがローテーションまたは取り消されていないことを確認する。

参照画像の問題

画像が理由でリクエストが拒否されたり、生成時に参照画像が無視されたりする場合、容疑者は URL だ。リンクがあなたのマシンの外部から解決できることを確認する——内部ホスト名や localhost アドレスはサービスから到達できない。署名付き URL の有効期限を確認し、ファイルが実際に画像であり、ステータス 200 で返される HTML エラーページではないこと、サイズと形式の制限を確認する。複数画像配列の 1 つの不良エントリがリクエスト全体を失敗させる可能性があるため、デバッグ時は参照画像を 1 枚ずつテストすること。

無効なリクエストボディ

検証メッセージ付きの 400 は通常、リクエストボディの形式が誤っていることを意味する:トップレベルがオブジェクトではなく配列、必須フィールドの欠落、reference_images が配列ではなく引用符付き文字列で送信されている、またはパラメータ名が認識されていない。リクエストボディを文書のスキーマとフィールドごとに比較し、送信した正確なリクエストボディを記録する——欠陥はしばしばテストパスと本番パスの間のシリアライズ差異だ。

ルートまたはメソッドの誤り

404 は通常、モデルが利用不能なのではなくパスが誤っていることを意味する。バージョンプレフィックスとエンドポイント名を文書と照らして再確認し、送信が POST、タスク状態の照会が GET であることを確認する。

タイムアウトとポーリングの誤り

送信自体がタイムアウトする場合、クライアントのタイムアウトを適度に増やしてリトライする——ただしタスクが既に受け付けられている場合は、盲目的に再送信しないこと。重複生成に課金される。ポーリングが決して終わらない場合、状態チェックが誤った文字列を比較している可能性が高い。最初の数回のポーリングで生の状態値をログに記録し、実際に何が返るかを確認する。

レート制限

429 は速度を落とす必要があることを意味する。即座にリトライするのではなく指定された間隔を守り、並列ワーカープロセスが同期的にリトライしないよう、ジッター付きの指数バックオフを適用する。

本番公開前のチェックリスト

ノートブックで動くコードは信頼できる統合とは同じではない。このエンドポイントをユーザーに公開する前に、運用上の境界を固めること。

  • 設定。 ベース URL と API キーは環境変数またはシークレット管理に保存し、ソースコードには決して書かない。エンドポイントパスを定数にすれば、バージョンアップは 1 行の変更で済む。
  • バックオフ付きリトライ。 一時的な障害——接続リセット、429、5xx——には指数バックオフとジッターを使ってリトライする。4xx の検証エラーはリトライしない。同じように失敗する。
  • 冪等性の規律。 送信したすべてのタスク ID とその入力を記録する。再起動時は新しいタスクを送信するのではなく、既存タスクのポーリングを再開する。
  • 有界な待機。 HTTP クライアントとポーリングループの両方に明示的なタイムアウトを設定し、タイムアウトは静かに破棄するのではなく、人手で確認できるデッドレターパスにルーティングする。
  • 構造化ログ。 タスク ID、タイムスタンプ付きの状態遷移、送信と完了のタイミング、失敗時のエラーボディを記録する。キーをマスクし、プロンプトにユーザーデータが含まれる場合は切り詰める。
  • 出力処理。 タスク成功後すぐに生成メディアを自分のストレージにダウンロードし、ユーザーに表示する前に結果を検証する。
  • コストの可視性。 課金は利用量に応じて変わるため、機能ごと、ユーザーごとに送信したタスク数を追跡する。不確実性のもとで再送信するリトライループは、予期せぬ支出の最も一般的な原因だ。
  • 入力の衛生。 参照 URL とプロンプト長を自分の側で先に検証する。不良 URL をローカルで捕捉するほうが、往復 1 回より速く安い。

これらを完了すれば、統合は軽量で予測可能な層になる:リクエストボディを構築し、送信し、ポーリングし、保存する。エンドポイントリファレンスから始め、curl の例を 1 回実行し、同じリクエストボディを Python に移す——シェルで動くリクエストは、あなたのサービスでも動く。

永続的なAIアーティファクトで開発を始める

APIキーを取得して、タスクベースの1つのAPIで画像・動画・音声モデルを呼び出せます。

APIドキュメントを読む