チュートリアル
HiAPI API で gemini-omni-flash を使って動画を生成する方法
テキストto動画と画像to動画のリクエスト経路、モデル選択、そして実用的な連携チェックリスト
このページの内容
gemini-omni-flash に動画エンドポイントが 2 つある理由
最初のコードを書く前に、最も重要な判断があります。実際に必要なのは 2 つの動画エンドポイントのどちらか、という点です。gemini-omni-flash はモードフラグ付きの単一エンドポイントではなく、HiAPI 上で 2 つの独立したモデルとして提供されています:
gemini-omni-flash/text-to-video—— テキストプロンプトのみから動画を生成します。gemini-omni-flash/image-to-video—— 提供されたソース画像を視覚的なアンカーとし、テキストプロンプトの誘導のもとで動画を生成します。
分割されている理由は、この 2 つのタスクで入力が異なり、検証ルールが異なり、失敗パターンも異なるからです。テキストto動画はプロンプト文字列 1 つの検証だけで済みます。画像to動画はさらにソース画像を取得してデコードする必要があるため、テキスト経路では決して発生しない種類のエラー(URL に到達できない、サポートされない形式、リソースが大きすぎる)が加わります。
経験則:すでに静止画像(商品画像、絵コンテのフレーム、写真)があるなら画像to動画を使ってください。モデルがゼロから創造するのではなく、あなたの視覚コンテンツを起点にするからです。アイデアだけがあり参照素材が何もないなら、テキストto動画を使ってください。
初日からコードベースでこの 2 つのモデル ID を区別してください。それらを 1 つの「動画」概念として扱い、後から if has_image フラグを足すことが、連携が最終的に混乱したペイロードと理解しにくいバグを生む原因になります。
変わらないもの
両エンドポイントは同じ認証方式、同じベース URL、同じ一般的なリクエスト/レスポンスの取り決め、そして同じ課金モデル(動画はリクエスト回数ではなく生成された出力に基づいて課金)を共有します。こうした共通部分があるからこそ、単一のリクエストビルダーが実現可能な選択肢になります——詳細は後述します。
変わるもの
変わるのはペイロード構造と入力検証だけです。差異は、連携コード一式を重複させずに両方のエンドポイントをサポートできるほど小さいものです。
前提条件と API のセットアップ
最初の呼び出しの前に、3 つのものが必要です。
1. API キー
HiAPI アカウントでキーを作成し、ハードコードせず環境変数として保存します:
export HIAPI_API_KEY="your_key_here"
すべてのリクエストは Authorization ヘッダーの bearer トークンで認証されます。個別の署名ステップも、リクエストごとの nonce もありません。
2. ベース URL とモデル命名規則
すべての呼び出しは同じ HiAPI ベース URL に送られ、モデルはリクエストボディの model フィールドで選択されます。モデル ID は family/variant パターンに従うため、動画モデルは gemini-omni-flash/text-to-video と gemini-omni-flash/image-to-video と書きます。エンドポイントを切り替えるにはホストを変えるのではなく、文字列を 1 つ変えるだけです。
3. リクエストを送るツール
curl は接続確認に十分で、Python(requests 併用)は本格的な連携を構築するのに十分です。どちらもベンダー専用 SDK は不要です——この API は HTTPS 上の普通の JSON にすぎません。
接続確認
動画を生成する前に、軽量なエンドポイント(たとえば利用可能なモデルの一覧取得)にアクセスして、キーが使えること、ネットワーク経路が正常であることを確認します。そこで失敗するなら、デバッグ対象は認証情報か接続性であって動画生成ではありません——どちらなのかを突き止めれば大幅に時間を節約できます。
簡単なチェックリスト:
- キーがリクエストを実行するシェルでエクスポートされている。
- ベース URL が記録され、どこでも一貫して使われている(スクリプト間で末尾スラッシュが揺れない)。
- すべての POST に
Content-Type: application/jsonが設定されている。 - 生の JSON レスポンスを切り詰めずに確認できる手段がある。
テキストto動画リクエストの送信
成功する見込みのある最小限のリクエストから始めます。最初からすべての任意パラメータを埋めないでください——最小リクエストが失敗すれば構造的な問題だとわかりますし、成功すれば以降加える各パラメータは個別に原因を特定できる変更になります。
最小構造
テキストto動画リクエストはモデル ID とプロンプトを送ります:
{
"model": "gemini-omni-flash/text-to-video",
"prompt": "夜の雨に濡れたネオン街をゆっくりと前進するショット、濡れたアスファルトの反射、シネマティック"
}
これが完全なペイロードです。これを送り、成功レスポンスオブジェクトを受け取ったことを確認してから内容を充実させ始めます。
リクエストを段階的に進化させる
最小呼び出しが成功したら、パラメータを一度に 1 つ追加し、追加のたびに再検証します。テキスト経路で典型的に追加する項目:
- プロンプトの詳細 —— 被写体、動き、カメラの挙動、照明、雰囲気。あいまいなプロンプトはあいまいな動きを生みます。何が動くのか、カメラがどう動くのかを描写してください。
- 長さ / 出力の長さ —— 動画は生成された出力に基づいて課金されるため、長さはコストに直結します。まだ確認していないデフォルト値に頼らず、明示的に固定してください。
- アスペクト比や解像度(モデルがサポートする場合)、下流のプレーヤーや SNS のフォーマットに合わせるため。
本当に重要なプロンプト作成の要点
テキストto動画の品質は主にプロンプトの具体性で決まります。3 つの良い習慣:
- 内容だけでなく動きを描写する。「紙のボートが排水溝を流れ落ちていく」はモデルにアニメーションできるものを与えますが、「紙のボート」は与えません。
- カメラを明示する。固定、パン、前進、手持ち——カメラ言語は多くのあいまいさを取り除きます。
- 1 つのシーンに限定する。単一の短いクリップで複数のショットを描写すると、しばしばぐちゃぐちゃな結果になります。
テキストto動画の結果が良くないときは、技術パラメータに手を付ける前にまずプロンプトを変えてください。
画像to動画リクエストの送信
画像経路は構造的にはテキスト経路と同じで、1 つだけ追加があります:ソース画像です。学んだ「最小優先」のテスト方法はここでも同じように適用できます。
最小構造
{
"model": "gemini-omni-flash/image-to-video",
"prompt": "穏やかな手持ちのドリフト、被写体がわずかにカメラの方を向く、柔らかな窓の光",
"image": "https://your-cdn.example.com/source-frame.jpg"
}
このときプロンプトが描写するのは画像に対する動きとカメラの挙動であり、シーンの内容ではありません——画像がすでに内容を提供しています。これが最もよくある概念的な誤りです:人々はシーンの完全な説明を書き、出力が自分のソースフレームを無視するのを不思議に思います。
ソース画像の提供方法
画像は参照として渡され、サービスがそれを取得できる必要があります。実務上の帰結は 2 つあります:
- リソースはサービスから公開アクセス可能でなければならない。localhost や VPN の内側、認証付きバケットの背後にあってはいけません。短い有効期限の署名付き URL は、リクエスト実行時にまだ有効であれば問題ありません。
- 形式とサイズがサポートされている必要がある。一般的な Web 形式と妥当なサイズに留めてください。40 MB の TIFF はデバッグを待っているようなものです。
画像がプライベートストレージにある場合は、バケットを公開しようとするのではなく、リクエスト時に短期的な署名付き URL を生成してください。
テキスト経路との実際の違い
- プロンプトの役割がシーンの描写から動きの描写に変わります。
- 検証にリソース取得ステップが加わるため、まったく新しい種類の失敗が生まれます(デバッグの章を参照)。
- 出力の構図はソース画像のアスペクト比に制約され、下流のレイアウト計画に影響します。
まず画像 URL をブラウザでテストしてください。あなたにとってもきれいに読み込めないなら、サービスにとっても同じです。
curl と Python で API を呼び出す
同じリクエストを 2 つの場所で動かしましょう:ターミナル(素早い反復と生の可視性のため)とコードベース(実際の利用のため)です。
curl
curl -sS https://api.hiapi.ai/v1/chat/completions \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-omni-flash/text-to-video",
"prompt": "夜の雨に濡れたネオン街をゆっくりと前進するショット、シネマティック"
}'
model 文字列を gemini-omni-flash/image-to-video に変え、image フィールドを加えれば別のエンドポイントに当たります——他は何も変えません。
-sS を使い、エラーが黙って飲み込まれないようにします。レスポンスを確認するときは JSON フォーマッタにパイプして、ネストしたフィールドを読みやすくしてください。
Python
import os
import requests
BASE_URL = "https://api.hiapi.ai/v1/chat/completions"
HEADERS = {
"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
"Content-Type": "application/json",
}
payload = {
"model": "gemini-omni-flash/text-to-video",
"prompt": "夜の雨に濡れたネオン街をゆっくりと前進するショット、シネマティック",
}
resp = requests.post(BASE_URL, headers=HEADERS, json=payload, timeout=300)
resp.raise_for_status()
print(resp.json())
そのまま真似する価値のある 2 つの細部:キーを環境変数から読み込むこと、そして十分に余裕のあるタイムアウトを設定すること。動画生成は即時リクエストではありません——10 秒のデフォルトタイムアウトは、API エラーのように見えて実はクライアントが早々に諦めただけの偽の失敗を生みます。
画像to動画の場合、1 行追加します:
payload["model"] = "gemini-omni-flash/image-to-video"
payload["image"] = "https://your-cdn.example.com/source-frame.jpg"
非 2xx ステータスコードに遭遇したら、例外を投げる前に必ず生のレスポンスボディを出力またはログに記録してください。エラーテキストは通常、問題のあるフィールドを直接名指しします。
連携コードを整理する
両方の経路がそれぞれ動くようになると、コードベースにほぼ同じ関数を 2 つ残したくなります。少しだけ良い構造はほとんどコストがかからず、2 つ目の動画モデルを追加した瞬間に元が取れます。
2 つの共有コンポーネント
1 つのリクエストビルダー。意図レベルのパラメータを受け取り、ペイロード辞書を返す関数:
def build_video_payload(prompt, image_url=None, duration=None):
if image_url:
payload = {
"model": "gemini-omni-flash/image-to-video",
"prompt": prompt,
"image": image_url,
}
else:
payload = {
"model": "gemini-omni-flash/text-to-video",
"prompt": prompt,
}
if duration:
payload["duration"] = duration
return payload
エンドポイント選択は「画像があるか?」の結果になり、これは実際の製品判断と一致します。呼び出し側はモデル ID に直接触れることは決してありません。
1 つのレスポンスハンドラー。転送エラー、ペイロードエラー、モデルレベルの失敗を分けて処理し、正規化された結果オブジェクト(ステータス、動画参照、ログ用の生レスポンスボディ)を返す関数です。すべての呼び出し側がこれを経由するため、両エンドポイントのエラーセマンティクスが一貫します。
なぜこれだけの価値があるのか
- モデル ID の変更が 1 か所で済む。別の動画モデルへ移行するときは、15 か所の呼び出し箇所ではなくビルダーを編集するだけです。
- 一貫したエラー処理。画像取得の失敗とプロンプト検証の失敗が同じ方法で UI に提示されます。
- ネットワークなしでテストできる。ビルダーは純粋関数です。ペイロード構造を低コストで単体テストできます。
- 課金の可視性。動画は生成された出力に基づいて課金されるため、単一のハンドラーはコスト追跡のために長さと出力サイズを記録する自然な場所です。
ビルダーは薄いままに保ってください。何を生成するかに関するビジネスロジックは呼び出し側に属し、ビルダーはその意図を API の形で表現する方法だけを知っていれば十分です。
よくあるリクエスト失敗のデバッグ
初期の失敗はほぼすべて 3 つのカテゴリのいずれかに収まります。まずカテゴリを特定し、それから修正してください。
カテゴリ 1:リクエスト構造
症状:即座に 4xx が返る、エラーメッセージが欠落または未知のフィールドに言及する、あるいは JSON 形式の誤りを訴える。
順に確認してください:
- JSON は有効か?リクエストボディを linter に貼り付けます。手で編集したペイロードに残った末尾のカンマは定番の問題です。
- モデル ID は完全に一致しているか?
gemini-omni-flash/text-to-videoとgemini-omni-flash-text-to-videoは同じ文字列ではありません。ここでの誤記は認証問題のように読める「モデルが見つからない」エラーを生みます。 - リクエストヘッダーは揃っているか?
AuthorizationとContent-Type: application/jsonの両方が設定されている。 - モデルとエンドポイントは一致しているか?
imageフィールドをテキストエンドポイントに送っても望む結果は得られません——そのフィールドは拒否されるか無視されるかのどちらかで、いずれにせよ誤った結果になります。
カテゴリ 2:入力リソース(画像経路のみ)
症状:リクエストは受け付けられるが、処理中に失敗する、あるいはエラーが画像の取得やデコードに言及する。
確認:
- Cookie のないプライベートブラウザウィンドウで画像 URL を開く。読み込めないなら、サービスも読み込めません。
- URL が localhost アドレス、プライベートネットワークのホスト、期限切れの署名付きリンクでないことを確認する。
- 形式が一般的な Web 形式で、ファイルサイズが妥当であることを確認する。
- レスポンスが本当に画像であることを確認する——200 ステータスコードを返しながら中身が HTML のエラーページという CDN は驚くほどよくある罠です。
カテゴリ 3:モデル呼び出し自体
症状:リクエストは有効でリソースも到達可能だが、生成が失敗または拒否される——多くの場合コンテンツポリシーかキャパシティに関係します。
確認:
- 最小限のプロンプトに縮めて再試行する。成功すれば、あなたのプロンプトが変数です。
- クライアントのタイムアウトが十分長いか確認する——ログ上では、クライアントのタイムアウトはサーバー障害とまったく同じに見えます。レスポンスを一度でも受け取ったかを確認しない限り。
- 完全なリクエスト/レスポンスログを有効にする(キーはマスク)。そうすれば 3 つのカテゴリの問題を一目で区別できます。
効果的なデバッグ順序
最小ペイロード → 検証 → 画像を追加 → 検証 → 任意パラメータを 1 つずつ追加 → 検証。問題が起きたとき、最後に行った変更が原因です。一度に 1 つの変数だけをデバッグすることに徹すれば、連携の苦しみのほとんどは消えます。
各エンドポイントの最小限の動作する呼び出しから始め、共有ビルダーとハンドラーで包み、それから徐々に拡張する——この道筋なら、連携が成長してもテキストto動画と画像to動画の両方を予測可能に保てます。