使用ガイド
flux-3-max/keyframes-to-video 入門ガイド：機能、料金、導入実践
機能の範囲と適用シーン
flux-3-max/keyframes-to-video は Black Forest Labs が提供する image-to-video モデルで、出力は動画です。入力は静止画像（1フレーム目として）とテキストプロンプトで、出力は連続した動画です。つまりこれは「ゼロから動画を想像する」のではなく、「すでに確定した1枚の画面を動的なショットへと拡張する」ものだと理解してください。この位置づけを押さえておけば、その後のパラメータ設計やコスト見積もりがぐっと明確になります。
得意な領域
- 1フレーム目の制御性：1フレーム目を提供するため、画面の構図・被写体・色調は最初から固定されます。モデルは時間軸方向に拡張するだけでよいため、スタイルのドリフトリスクは純粋な text-to-video よりはるかに低くなります。
- 短尺動画ショット：広告素材、製品紹介、SNS 向けの数秒から十数秒のクリップに適しており、特に静止画がすでに作り込まれている場面に向いています。
- 軽い動き：カメラのプッシュ・プル、被写体のわずかな移動、環境要素（光、霧、水面の波紋）のゆっくりした変化といった「抑制の効いた動き」は、比較的安定する領域です。
苦手な領域
- 複数被写体の複雑なインタラクション：2〜3人のキャラクターが互いに戦う、物をやり取りする、正確に位置合わせするなど、時空間の一貫性が求められる場面は失敗率が明らかに上がります。
- 大幅なカット切り替え：1ショット内のカメラワークは得意ですが、数秒のうちにマルチカメラへ切り替えるような要求では、通常望む結果は得られません。
- 1フレーム目にない情報：1フレーム目に存在しない物体をプロンプトで要求すると、モデルは「推測」するしかなく、結果は不自然になりがちです。
したがって、使うべきかどうかを判断する簡単なセルフチェックがあります。手元にすでに満足のいく静止画があり、それを「動かしたい」だけではないですか？ 答えが「はい」なら適切な選択です。画面そのものがまだ決まっていないなら、まず画像モデルで1フレーム目をしっかり作り込むべきです。
注意が必要なのは、1フレーム目の画像品質が出力品質の上限を直接決めることです。低解像度、圧縮ノイズが激しい、構図が乱れた1フレーム目は、その欠陥を動画にも持ち込み、しかもフレームごとに拡大されるため、通常は元画像より見栄えが悪くなります。本番化の前に、1フレーム目の仕様（解像度、被写体の占有率、余白）をテンプレートとして固定しておくことをおすすめします。
秒単位の課金：コストを設計に組み込む
このモデルの課金基準は出力秒数に応じた課金です。つまり1回の呼び出し費用は生成動画の長さに比例し、プロンプトの長さや入力画像のサイズには関係しません。リアルタイムの単価はサイトの料金パネルを基準にしてください。本記事では具体的な数字は書かず、コストをどう設計に組み込むかだけを説明します。
秒課金が製品設計に与える影響
秒課金とはコストが線形に増幅することを意味します。長さが2倍になれば費用も2倍です。これには2つの直接的な帰結があります。
第一に、「長く生成してから切り出す」のは無駄です。長い動画を一度生成してから使える部分を切り出す習慣のあるチームがありますが、秒課金のモデルでは捨てた秒数分もすべて支払っています。より得な方法は、まず短い長さでプロンプトと1フレーム目の組み合わせが正しいか確認し、確認できてから目標の長さで一度に生成することです。
第二に、リトライコストを予算に計上する必要があることです。生成失敗や結果への不満で再実行が必要になり、再実行のたびに完全な課金が発生します。したがって「無駄なリトライを減らす」ことを体験の最適化だけでなく、エンジニアリング目標として扱うことが非常に重要です。前述のキーフレームとプロンプトの制御も、本質的にはコスト管理手段です。
実用的な見積もり方法
コードを書き始める前に、おおまかな容量見積もりを行いましょう：
- 1本の完成動画の目標秒数を決める。これが「単位コスト」になります。
- 1本あたりの平均リトライ回数を見積もる（初期は高めで、安定後は下がる傾向があります）。
- 「単位コスト × 平均試行回数 × 日次呼び出し量」で日次費用を見積もり、予算上限と照らし合わせる。
この式は正確である必要はありません。価値は導入初日から動画の長さは製品上の意思決定であり、単なるパラメータではないと意識できることにあります。ビジネスがSNS向けショート動画なら数秒のクリップで十分なことが多いですし、展示型コンテンツであっても「増やした数秒が本当に情報量を増やしているか」をまず問うべきです。視聴者の長い動画への許容度は画像よりはるかに低いからです。
コストを抑える具体的な方法
- 短い長さでパイプラインとプロンプトを通し、その後長い長さで最終成果物を生成する。
- プロンプトと1フレーム目の組み合わせを小批量で検証し、大規模並列で誤った方向に走るのを避ける。
- 失敗リクエストを分類集計し、「パラメータ誤り」と「結果への不満」を区別する。前者はバリデーションで弾くべきで、課金を発生させてはいけない。
最後に、コスト監視は呼び出し単位で行うべきです。モデル別、長さ別、ビジネスライン別にそれぞれ集計して初めて、どの種類のリクエストが密かに予算を食っているかが分かります。
導入フローとパラメータの要点
導入経路はとても短いです。HiAPI.ai で API Key を取得し、統一インターフェースでタスクを送信し、ポーリングまたはコールバック待ちで動画結果を取得します。詳細はすべてプラットフォームのドキュメントを基準とし、以下では最小経路と重点的に確認すべきパラメータを示します。
最小導入経路
- 認証情報の取得：コンソールで API Key を作成し、リクエストヘッダーに含めます。
- タスクの送信：動画生成エンドポイントに1フレーム目画像とプロンプトを送信し、タスク識別子を取得します。
- ステータスのポーリング：動画生成は非同期なので、返されたタスク識別子で進捗を照会し、ステータスが完了になるまで待ちます。
- 結果の取得：レスポンスから動画URLまたはファイルを読み取り、ダウンロードして自社ストレージに保存します。
汎用的な呼び出しの骨組み（フィールド名はプラットフォームのドキュメントを基準にしてください）：
curl -X POST "https://api.hiapi.ai/v1/video/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "flux-3-max/keyframes-to-video",
"image": "<1フレーム目画像の URL または base64>",
"prompt": "slow camera push-in, gentle light shift",
"duration": <目標秒数>
}'
タスク識別子を取得したら、同じ認証ヘッダーでタスクステータスを照会し、完了してから結果を取得します。本番環境ではポーリングをバックオフ付きのリトライとして実装し、固定間隔の無限ループにしないことをおすすめします。
重点的に確認すべきパラメータ
- 1フレーム目画像：これが最も重要な「パラメータ」です。被写体が明確で、構図が安定し、解像度が基準を満たす画像を優先してください。URL 方式は手軽ですが、タスク実行中にリンクへアクセス可能であることを保証する必要があります。そうでないと送信は成功しても生成が失敗します。
- プロンプト：画面を再説明するのではなく、動きを記述します。「カメラがゆっくり近づき、光が暖色から寒色へ変わる」と書く方が、「美しい部屋」と書くよりはるかに有用です。
- 長さ：短い長さから始め、効果を確認してから長くします。
- 動き関連パラメータ（あれば）：振幅が大きいほど画面が崩れる確率が高くなるため、初期は保守的な値をとります。
エンジニアリング上の推奨
「タスクの送信」と「結果の取得」を2つの独立したステップに分け、間にタスクテーブルで状態を永続化します。こうすればサービス再起動時も生成中のタスクを失いません。同時にポーリングを1つのバックグラウンド worker に集約し、各リクエストが個別にスレッドを占有するのを避けられます。並列制御もこの層に置き、キューでピークを平準化する方が、入口で直接リクエストを拒否するより体験が良くなります。
キーフレームで画面の動きを導く
初めて導入する開発者の多くは、長い画面描写を書いてしまい、結果としてモデルが出す動きが想像と大きく異なります。問題は通常モデル側ではなく、プロンプトの書き方にあります。このモデルの役割は「既存の画面を動かす」ことなので、プロンプトは動きと変化に焦点を当て、内容と構図には焦点を当てるべきではありません。
プロンプトの三段構成
安定した構造は、カメラ動作＋被写体動作＋環境変化です。
- カメラ動作：プッシュ、プル、パン、移動、軽い手持ち感。1回に主要なカメラワークを1つだけ書きます。マルチカメラ切り替えはこのモデルの能力範囲外です。
- 被写体動作：髪がなびく、衣服が揺れる、人物が軽く首を回す、製品がゆっくり回転する。振幅の記述は具体的に。「そっと」と「激しく」では全く異なる結果になります。
- 環境変化：光の方向の変化、霧の流れ、水面の波紋、背景ボケの程度の変化。これらはリアリティを高める低コストな項目です。
例えば、カメラがゆっくり近づき、被写体が軽く首を回し、背景光が暖色から寒色へ変わると書く方が、形容詞を並べるより効果的です。
「時点」ではなく「リズム」で書く
プロンプトに「2秒目に何が起きる」とは書かないでください。こうした時間を離散的に記述する表現はモデルが字面通りに実行せず、かえって混乱を招きます。より良いのは動きのリズムを記述することです。ゆっくり、等速、最初速く後半遅くなど。リズムはモデルが知覚できる連続量で、長さパラメータとも連動しやすいです。
無駄なリトライを減らすための経験則
- 1回に1変数だけ変える：リトライ時にプロンプトと長さを同時に変えると、どちらが効いたか判断できません。
- 1フレーム目と動きの方向を一致させる：1フレーム目が正面の半身像なら、大きな振り向きを要求しないこと。1フレーム目の構図がタイトなら、大幅なズームアウトを要求しないこと。フレーム外に情報がないため、モデルは推測するしかありません。
- 保守的に始める：まず1文の動き記述と短めの長さで試作し、構図と色彩が安定したことを確認してから環境変化を重ねます。
- テンプレートライブラリを作る：検証済みのプロンプトをシーン（製品、人物、風景）別にアーカイブし、類似のニーズでそのまま再利用します。毎回パラメータを調整し直すよりずっと安上がりです。
最後に1つの現実を受け入れる必要があります。image-to-video には固有の不可制御性があり、同じ入力でも複数回の生成で差異が出ます。「満足いく結果を引き当てる」ことをプロセスに組み込み、そのためのリトライ予算を確保する方が、一発で当てるプロンプトを求めるより現実的です。
よくある失敗と調査の考え方
導入中に遭遇するエラーや異常のほとんどは、いくつかの固定カテゴリに収まります。いきなりプロンプトを変えるのではなく、以下の順序で項目ごとに調査することをおすすめします。
第一層：リクエスト自体が合法か
- 認証失敗：API Key が正しく含まれているか、期限切れでないか、そのモデルの呼び出し権限があるかを確認します。
- パラメータの欠落や型エラー：必須フィールドがそろっているか、長さなどの数値フィールドに文字列ではなく数値を渡しているかを確認します。
- 画像にアクセス不可：URL 方式を使う場合、リンクがサーバー側から到達可能か、期限切れでないか、ホットリンク防止制限がないかを確認します。これは最も頻度の高い失敗原因の1つで、エラーメッセージも分かりにくいことが多いです。
第二層：タスクが本当に動いているか
- ステータスが終わらない：まず正しいタスク識別子をポーリングしているか確認し、次にタイムアウトでポーリングを諦めていないか確認します。
- タスク失敗：ステータスフィールドだけでなく、エラーコードとエラーメッセージを読みます。
- 結果リンクの期限切れ：動画URLは通常有効期限があるため、取得後すぐに自社のオブジェクトストレージへ転送保存し、長期的なリソースアドレスとしてデータベースに書き込まないでください。
第三層：結果の品質が基準に達しない
この層はエラーを出しませんが、最も費用がかかります。調査順序は次のとおりです：
- 1フレーム目を見る：入力画像を単独で開いて確認します。ぼけ、ノイズ、被写体が小さすぎる、構図のバランス崩れは、すべて動画に直接反映されます。
- プロンプトを見る：マルチカメラの要求、1フレーム目にない物体、激しい動きの記述がないか。項目ごとに削減します。
- 長さを見る：長すぎる長さは動きが徐々に制御不能になるため、短くしてから観察します。
- 動き振幅パラメータを見る：低くしてから試します。
可観測性の構築
各呼び出しのモデル名、プロンプト、1フレーム目の出所、長さ、ステータス、エラーコードをすべてログに記録し、エラーカテゴリ別に集計します。こうすれば、ある日突然失敗率が上昇したとき、プラットフォーム側の問題か、画像ソースの問題か、あるいはあるプロンプトテンプレートの変更が原因かを即座に切り分けられます。この記録がなければ、調査は試行錯誤の繰り返しに退化し、しかもこのモデルでは試行錯誤が秒課金です。
本番化前のチェックリスト
前述の内容を本番前のセルフチェックリストにまとめ、項目ごとにチェックしてからスケールさせてください。
機能とシーン
- ビジネスシーンが「静止画を1フレーム目とする短尺動画」であり、複雑な複数被写体インタラクションではないことを確認済み。
- 1フレーム目画像の仕様（解像度、被写体占有率、構図）がテンプレートとして固定化され、品質チェック工程がある。
- 1本の完成動画の目標長さがビジネス側で確認済みであり、技術側が適当に決めたものではない。
コスト
- 「1本の長さ × 平均試行回数 × 日次呼び出し量」で容量見積もりを行い、予算と照らし合わせ済み。
- リアルタイム単価はサイトの料金パネルを基準とすることをチーム内で明確化済み。
- モデル、長さ、ビジネスラインの3次元でコスト統計を構築済み。
- 「長く生成してから切り出す」非効率な戦略を使っていない。
導入
- API Key は環境変数で注入され、コードベースにハードコードされていない。
- 送信と結果取得が分離され、タスク状態が永続化され、サービス再起動でもタスクを失わない。
- ポーリングにはバックオフ戦略があり、タイムアウト上限も設定済み。
- 生成された動画は自社ストレージへ転送保存され、一時リンクに依存していない。
プロンプトと品質
- プロンプトは「カメラ＋被写体＋環境」構造を採用し、1回に主要なカメラワークを1つだけ記述している。
- 検証済みのプロンプトテンプレートがアーカイブされ、チームで再利用可能。
- リトライフローでは1回に1変数だけ変えると規定されている。
可観測性
- 各呼び出しでモデル名、プロンプト、1フレーム目の出所、長さ、ステータス、エラーコードを記録済み。
- 失敗がカテゴリ別に集計され、パラメータ誤り、画像到達不可、結果への不満の3種類を区別できる。
チェックリスト自体は複雑ではありません。価値は「コスト意識」と「無駄なリトライの削減」という2つを個人の経験に頼らず、プロセスの一部に変えることにあります。モデルの導入と課金基準についてさらに知りたい場合は、HiAPI.ai のモデルページで flux-3-max/keyframes-to-video の最新説明を確認してください。価格と可用性はパネルの表示を基準とします。導入が順調に進みますように。
