使用ガイド
HiAPI API で happyhorse-1.1/reference-to-video を使う：プロンプトレシピとショート動画ワークフロー
開発者ガイド：HiAPI で参照画像を構成し、アイデンティティの一貫性を保つプロンプトを書き、ショート動画のテンポを制御する方法
このページの内容
reference-to-video がワークフローにもたらす変化
テキストのみからの動画生成では、モデルは説明に基づいて主体をゼロから作り出す必要があり、実行のたびに顔、服装、製品の形状が異なる可能性があります。reference-to-video はその逆です。1 枚または複数の画像を提供すると、モデルはそれらを画面に登場する内容の視覚的基準として扱います。プロンプトはキャスティング要件ではなく、演出指示書になるのです。
ショート動画のワークフローでは、これによって作業の重心が変わります。テキストのみの生成では、主に言葉遣いを繰り返し調整します。happyhorse-1.1/reference-to-video では、まず参照画像セットを反復調整し、その次にプロンプトを調整します。主体がおかしく見える場合、解決策は通常、より長い形容詞のリストを積み上げることではなく、より良い画像に差し替えるか画像の順序を調整することです。
適用される位置づけ
典型的なサイクルはおおよそ次のとおりです：
- 主体とシーンのための小さな参照画像セットを収集し選別する。
- 重要度順に並べる（次の節で詳述）。
- ショット順に並べたプロンプトを書き、安定した属性とテンポを明示する。
- 生成し、参照画像と照らし合わせてレビューし、画像を変えるかテキストを変えるかを決める。
実際の利点はシリーズコンテンツの一貫性にあります。同じ人物、製品、マスコットを含む複数の動画を制作する場合、安定した参照画像セットこそが第 3 話を第 1 話らしく見せ続ける鍵です。画像は使い捨てのアップロードファイルではなく、リポジトリ内のバージョン管理されたアセットとして扱いましょう。
参照画像セットを構成する
モデルはあなたの画像を優先度付きの信号として読み取ります。並べ替えと選別自体がプロンプトの一部であるため、意図的に決める必要があります。
メイン主体の画像を 1 枚選ぶ
最初の画像は、主体が最も明確で最も代表的なビューであるべきです：正面を向き、照明が良く、遮るものがなく、背景に気を散らす雑物がないもの。この画像がアイデンティティを固定します。残りの画像は補助情報にすぎません。
本当に価値がある場合にのみ第 2 の視点を追加する
2 枚目の画像が、1 枚目では解消できない曖昧さを解決する場合——たとえば側面ビュー、異なる服装の状態、製品の背面——にのみ有用です。相反するディテールを持ち込む場合、たとえば 2 つの髪型や 2 つのロゴがある場合は有害です。モデルに両方を平均化してほしくないなら、両方を同時に入れないでください。
主体と環境を分離する
シーンが重要な場合は、主体と注意を奪い合わない形で設定を示す環境参照画像を加えます。モデルが混同しないよう、主体画像とは視覚的にはっきり区別できるようにしましょう。
シンプルな並べ方の経験則
- 第 1 位：メイン主体。クリーンで標準的。
- 第 2 位：主体の補助的な視点。必要な場合にのみ追加。
- 第 3 位以降：環境またはスタイリングの参照。
何度もの反復を節約する規範
- 参照画像セットは小さく、内部的に一貫させる。
- 主体が小さすぎる画像、奇妙なトリミング、フィルターが強すぎる画像は避ける。
- アスペクト比はできるだけ統一する。大きく異なる構図はモデルが異なるビューを調和させるのを難しくする。
- ファイル名は役割に応じて付ける（
subject-primary.png、scene-street.png）。チームがそれらを 1 セットの素材として扱えるようにする。
迷ったら、画像を 1 枚追加するのではなく、1 枚削除しましょう。
主体の一貫性を保つプロンプトを書く
アイデンティティのドリフトは通常、曖昧な表現から生じます。「ある人」や「おしゃれな服装」といった漠然とした記述は、モデルに即興の余地を与えてしまいます。解決策は、安定していて観察可能な属性を明示し、各文の間でそれを変えないことです。
変わってはいけない内容を指摘する
主体を定義する属性を列挙します：服装の色とシルエット、髪型、象徴的なアクセサリー、製品の形状、ロゴの位置。連続性を前提とせず、各ショットの記述で重要な項目を繰り返します。
「固定」と「可変」を区別する
プロンプトを頭の中で 2 つのブロックに分けます：固定された主体属性、その後にショットごとのアクションとカメラワーク。こうすると、矛盾を誤って持ち込んだときに気づきやすくなります。たとえば第 1 ショットでは赤いジャケット、第 3 ショットではグレーのジャケットと書いてしまうようなケースです。
効果的な表現パターン
- まず固定する：冒頭で主体とその固定属性を書き、その後で動きを記述する。
- 名詞を一貫させる：参照画像がトレンチコートを示しているなら、毎回それをトレンチコートと呼び、「ジャケット」と言った後に「コート」と言い換えない。
- 評価より具体：「美しい髪」より「ダークなショートヘア、サイドパート」のほうが良い。
- 動きの中で変わらない部分を説明する：「主体が振り向いてもコートは元のシルエットを保つ」は、モデルが自分で推測することを期待するより有用です。
- 類義語を積み重ねない：形容詞を重ねると信号が薄まります。
簡単な比較
弱い例：「おしゃれな女性が街を歩く、シネマティック。」
強い例：「参照画像の女性——ダークなショートヘア、サイドパート、キャメルのトレンチコート、黒いブーツ——が安定した歩調でカメラに向かって歩いてくる。コートとブーツは最後まで一貫している。」
2 番目のバージョンはモデルに雰囲気ではなくチェックリストを与えます。
1 つのプロンプトでカメラワークとテンポを指示する
ショート動画の成否はテンポにあります。単一の静止した記述では、構造がなく流れに任せた動画が生成されます。プロンプトは順序立ったショットのシーケンスとして書き、明確なテンポの手がかりを与えましょう。
ビートで構成する
2〜4 つのビートを記述し、各ビートに主体の状態、アクション、カメラのメモを含めます。各ビートは簡潔に保ちます。モデルは、長い 1 段落よりも明確な 3 拍のシーケンスをうまく処理します。
テンポを明示的に書く
テンポを示す言葉は強い効果があります：「素早いカット」「ゆっくりとしたズームイン」「一拍止まる」「急激なズーム」「安定した締め」。これらをカメラワーク（ドリー、パン、手持ち）と組み合わせ、動きと時間感覚を相互に強化しましょう。
ビートのテンプレート
ショット 1（0〜2 秒）：[主体 + 固定属性] [アクション]、[カメラの動き]、[テンポのヒント]。
ショット 2（2〜4 秒）：[主体の状態変化] [アクション]、[カメラの動き]、[テンポのヒント]。
ショット 3（4〜6 秒）：[締めのビート]、[カメラの安定]、[テンポのヒント]。
正確なタイムスタンプは不要ですが、秒単位で考えることで各ビートに理由を与えることが強制されます。ビートに明確な視覚的変化がない場合は削除しましょう。
よくあるテンポの誤り
- ショート動画にビートを詰め込みすぎ、モデルにすべてを急がせる。
- カメラの指示がなく、平板で静止した構図になる。
- 同じ行に矛盾するテンポのヒント（「ゆっくりだが力強く」）。
シーケンスを書いたら声に出して読み、映像内容を変えない部分は削除しましょう。
解像度、尺、予算のトレードオフ
バッチ生成の前に、どのリソースを使うかを決めます：ピクセル、秒数、それとも反復回数か。これらは互いに競合します。
核心となるトレードオフ
より高い出力解像度（たとえば 1080P）とより長い尺は、どちらも生成ごとのコストを増やします。課金はリクエストした出力——解像度とクリップの長さを含む——に追随するため、長い 1080P 動画は要求できる中で最も高価なものです。ショート動画では、両方を最大限にする必要はほとんどありません。
効果的な意思決定の順序
- まず尺を決める。ショート動画は通常、コンパクトな時間枠を意味します。プラットフォームが必要とする長さを固定し、それ以外はすべて調整可能な項目として扱います。
- 納品先に応じて解像度を選ぶ。クリップがフィード内で圧縮される場合、低い解像度のほうが賢明なデフォルトであり、予算をより多くの試行に回せます。
- 予算は成果物だけでなく反復に使う。少し低い解像度で 3 回生成し最良の結果を選ぶ動画は、高価でやり直しのできない 1 回の試行にしばしば勝ります。
実用的なアドバイス
- まず低い解像度でプロトタイプを作り、プロンプトと参照画像セットを検証する。
- ショットのシーケンスとアイデンティティの一貫性が合格してから 1080P に引き上げる。
- 尺には正直に：コンパクトでビートが明確な短編は、冗長で埋め草の多い長編より見栄えが良い。
正確な料率については現在の料金パネルを確認してください。数字は変わるため、スクリプトにハードコードすべきではありません。リクエストを構築する際は、解像度と尺をコードに埋め込んだ定数ではなく、切り替え可能なパラメータにしましょう。
実行可能なリクエストとプロンプトレシピ集
以下は HiAPI API 経由で happyhorse-1.1/reference-to-video を呼び出すリクエスト構造で、その後に上記のワークフローに対応するそのままコピー可能なプロンプトレシピが続きます。パラメータ名は SDK のバージョンによって多少異なる場合があります。正式なスキーマはモデルページを確認してください。
リクエスト構造
import os, requests
resp = requests.post(
"https://api.hiapi.ai/v1/video/generations",
headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
json={
"model": "happyhorse-1.1/reference-to-video",
"reference_images": [
"https://your-cdn.example/subject-primary.png",
"https://your-cdn.example/subject-angle.png",
"https://your-cdn.example/scene-street.png",
],
"prompt": "...レシピ本文...",
"resolution": "1080P",
"duration": 6,
},
)
print(resp.json())
参照画像は安定した URL に保ち、前述の順序で並べます：メイン主体、補助的な視点、環境。
レシピ 1：製品メインビジュアル、単一ビート
参照画像の製品——マットブラックのボトル、カッパー色のキャップ、正面ラベル——を石の表面に中央配置。ラベルへゆっくりズームイン、柔らかなスタジオ照明、カットなし。ボトルとキャップは最後まで正確な形状と色を保つ。
レシピ 2：人物の歩行、3 ビート
ショット 1（0〜2 秒）：参照画像の女性——ダークなショートヘア、サイドパート、キャメルのトレンチコート、黒いブーツ——がカメラに向かって歩いてくる、ミディアムショット、安定した手持ち、軽快な歩調。
ショット 2（2〜4 秒）：素早く側面へカット。彼女が振り向くとトレンチコートが揺れ、カメラは横に追従、同じ軽快なテンポ。
ショット 3（4〜6 秒）：彼女が立ち止まり正面を向く。カメラはゆっくりとしたズームインに安定し、静かな締め。髪、トレンチコート、ブーツはすべてのショットで一貫している。
レシピ 3：環境で導くオープニング
ショット 1（0〜2 秒）：環境参照画像の街路のワイドショット、朝の光、ゆっくりと左へパン。
ショット 2（2〜4 秒）：参照画像の主体が画面右から入ってくる——同じジャケットとバッグ——カメラは固定、自然なテンポ。
ショット 3（4〜6 秒）：ミディアムショットに寄り、彼女がカメラを見る。ジャケットとバッグは参照画像と完全に一致する。
プロンプト本文を変更せずに、クリップごとに尺と解像度を調整できます。完全な例を含む専用ガイドがドキュメントに用意されています。
出力をレビューして反復する
レビューは品質向上の大部分が起こる場所であり、重要な規律はどの種類の問題に直面しているかを見極めることです。
記憶ではなく参照画像と照らして評価する
参照画像セットを出力の横に開いておきます。アイデンティティ属性を 1 項目ずつ確認します：顔と髪、服装の色とシルエット、製品の形状、ロゴの位置。名前を付けられるドリフトは、修正できるドリフトです。
失敗を 2 つのカテゴリに分ける
- アイデンティティや外観の問題は通常、参照画像セットが弱い、一貫していない、または順序が不適切であることを意味します。まず画像を直しましょう。プロンプトをより強く書いても、自己矛盾した参照画像セットを救えることはほとんどありません。
- 構図、動き、テンポの問題は通常、プロンプトの改善が必要であることを意味します：より明確なビート、より強いカメラのメモ、よりコンパクトな尺。
短いレビューサイクル
- アイデンティティ、構図、テンポをそれぞれ採点する。
- アイデンティティが不合格なら、まず参照画像を調整し、その後でプロンプトに触れる。
- テンポが不合格なら、ビートのシーケンスを書き直し、ビートを 1 つ削除する。
- 各反復では変数を 1 つだけ変え、何が効いたかを把握できるようにする。
- 低い解像度で安定したら、最終版のために 1080P に引き上げる。
合格したクリップごとに、プロンプトのバージョンと参照画像セットのバージョンの短いログを残しましょう。シリーズの中で、このログはあなたの本当のレシピ集になります：信頼できるプロンプト、信頼できる画像、予測可能な出力。参照画像セットとテキストを反復し、残りはモデルに任せましょう。
