チュートリアル

AI動画における最初のフレームと最後のフレームの制御：hiapi でモデルをまたいだ正確なモーションのガイド

Sep 4, 2026

ほとんどの画像から動画を生成する API は、静止画像を 1 枚受け取って、その後の動きを即興で生成するだけです。ごく一部のモデルだけが、カメラの終点を起点だけでなく固定できるようにしています。最初のフレームと最後のフレームを提供すると、モデルがその間を補間して動きを生成します。これが「この写真を動かす」ことと「このトランジションを正確に実現する」ことの違いです。

問題は、最後のフレームの制御への対応がモデルごとに一貫していないことです。同じベンダーの製品ライン内でも、フラッグシップ tier と高速/ターボ tier で異なる場合があります。本チュートリアルでは、どの hiapi 動画モデルが最初のフレームのみの制御に対応し、どれが最初のフレーム＋最後のフレームの制御に対応しているかを明確に説明し、それぞれの実際の（そして統一されていない）入力フィールドを示します。これにより、選択したモデルが最後のフレームをこっそり無視していたことに、ひと苦労した末に気づく、という事態を避けられます。

1. 必要なもの

コンソールから取得した hiapi API key（sk-...）と、対象モデルが取得できる 2 枚の画像 URL（公開 HTTPS URL——タスクエンドポイントはローカルファイルのアップロードに対応していません）。以下の各モデルはすべて同じ統合された task API を通じて呼び出されるため、いずれかのモデルで key が使えれば、すべてのモデルで使えます。

2. 最小限の実行可能な例

hiapi の動画生成はすべて同じエンドポイントを使用します：タスクを作成し、終了状態になるまでポーリングします（またはコールバックを使用——本番パターンを参照）。

# 1. Create the task
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0-omni/image-to-video",
    "input": {
      "prompt": "the subject turns toward the camera and smiles",
      "image_urls": [
        "https://your-cdn.example.com/first-frame.jpg",
        "https://your-cdn.example.com/last-frame.jpg"
      ],
      "resolution": "720p",
      "duration": 5,
      "sound": false
    }
  }'
# -> {"data": {"id": "task_...", "status": "pending"}}

# 2. Poll until terminal
curl -s https://api.hiapi.ai/v1/tasks/task_... \
  -H "Authorization: Bearer sk-<your-key>"
# -> {"data": {"id": "task_...", "status": "succeeded",
#              "output": [{"url": "https://...mp4", "expireAt": "..."}]}}

kling-3.0-omni/image-to-video はこのパターンの最も典型的な例です：input.image_urls は1 枚または 2 枚の画像 URL を受け取ります。1 枚を渡すと、モデルは最初のフレームだけをアンカーとし、残りは自由に生成します。2 枚を渡すと、2 番目の URL が強制の最後のフレームになります——モデルはカメラがどこに着地しなければならないかを指示されます。duration は 3〜15（秒）の整数で、resolution は 720p / 1080p / 4k、オプションの sound ブール値は生成された雰囲気音声を追加します。ここには aspect_ratio フィールドはありません——出力のアスペクト比は提供したフレームに従います。

すべてのモデルがこの構造というわけではありません。seedance-2.5/image-to-video は配列ではなく、2 つの別々に命名されたフィールドで同じ効果を実現します：

{
  "model": "seedance-2.5/image-to-video",
  "input": {
    "prompt": "smooth camera push toward the subject",
    "first_frame_url": "https://your-cdn.example.com/first-frame.jpg",
    "last_frame_url": "https://your-cdn.example.com/last-frame.jpg",
    "resolution": "720p",
    "duration": 6,
    "aspect_ratio": "adaptive",
    "generate_audio": false
  }
}

last_frame_url は first_frame_url と組み合わせた場合にのみ意味を持ちます——first_frame_url だけを送信して最初のフレームのみのショットにできますが、その逆はできません。このモデルの duration 範囲は 4〜30 秒で、解像度は最大 720p/1080p のみ（4K tier はありません）、また aspect_ratio はデフォルトで adaptive、つまり明示的な 16:9/9:16 の値ではなく最初のフレームに従います。

モデルごとにフィールド名は確かに異なります——image_urls と first_frame_url/last_frame_url——そのため、モデルを切り替えるたびに schema の変更として扱うべきであり、そのまま置き換え可能なものと見なすべきではありません。

すべてのモデルが対応しているわけではない

veo-3.1/image-to-video は単一の image_url 文字列を受け取り、最後のフレームのパラメータはまったくありません——aspect_ratio（auto/16:9/9:16）、resolution、および固定の duration 列挙（4、6、8 秒）を設定できますが、終了フレームを固定することはできません。Kling 製品ラインの 1 つ下の tier も同じ状況です：kling-3.0-turbo/image-to-video（kling-3.0-omni の高速/低コスト版）の image_urls は最大 1 項目しか受け付けません——最後のフレームもなく、4K 解像度もありません。最後のフレームの制御が必要な場合は、モデルファミリー名から当然と決めつけるのではなく、フラッグシップ tier か、そのために構築されたモデル（seedance-2.5 など）を選ぶべきです。

3. 本番パターン

大規模な場面ではポーリングの代わりにコールバックを使用します。 ループ内でポーリングするのではなく、同じリクエストボディに callback オブジェクトを渡します：

{
  "model": "kling-3.0-omni/image-to-video",
  "input": { "...": "..." },
  "callback": { "url": "https://your-service.example.com/hooks/hiapi", "when": "final" }
}

when: "final" は、タスクがいずれかの終了状態に達したときに 1 回だけ発火します——succeeded も failed も終了状態であるため、webhook ハンドラはコールバックが成功のみを表すと仮定せず、taskId で重複排除すべきです。GET /v1/tasks/:id のポーリングは、ローカルでのデバッグ、低頻度の単発呼び出し、またはコールバックが結局届かなかった場合（ネットワークの揺らぎ、あなたのエンドポイントが一時的にダウンしていたなど）の照合のフォールバックとして適しています。

冪等性。 タイムアウトや接続中断後のリトライは、不注意だと重複タスクを作成する可能性があります——作成呼び出しが返したタスク id を記録し、新しいタスクを送信する前に、その id に対して GET を実行してリトライしてください。

出力 URL は期限切れになります。 各出力エントリの expireAt フィールドは飾りではありません——コールバックでもポーリングでもタスクの成功を知ったら、できるだけ早く動画をダウンロードして永続化（自分のストレージに保存）してください。

認証失敗。 誤った key または欠落した key は HTTP 401 と {"error": {"code": "permission_denied", ...}} を返します。2xx 以外はすべて生成自体の失敗だと仮定せず、このステータス/エラーコードを明示的にチェックしてください——「自分の key が間違っている」と「モデルが入力を拒否した」をエラー処理で区別することには価値があります。修正方法がまったく異なるからです。

4. 関連ページ

Kling 3.0 Omni 画像から動画へのモデルページ —— 上記の例で使用したモデルの料金、オンライン体験、完全なパラメータリファレンス。
Seedance 2.5 画像から動画へのモデルページ —— first_frame_url/last_frame_url のバリアント。
認証ドキュメント —— Authorization: Bearer sk-... ヘッダーと key スコープの仕組み。
タスク作成ドキュメント —— コールバックオプションを含む完全な /v1/tasks のリクエスト/レスポンスリファレンス。
hiapi の料金 —— 現在の秒単位および解像度単位の価格（課金はモデルと解像度によって異なるため、固定の数値ではなく最新のページを確認してください）。

5. よくある質問

どの hiapi 動画モデルが最後のフレームの制御に対応していますか？ kling-3.0-omni/image-to-video（2 項目を含む image_urls 配列経由）と seedance-2.5/image-to-video（first_frame_url + last_frame_url 経由）が現在対応しています。veo-3.1/image-to-video と kling-3.0-turbo/image-to-video は対応していません——これらは単一の開始フレームのみを受け付けます。

最後のフレームだけを指定し、prompt を提供しなくてもよいですか？ 両モデルとも、フレームに加えて prompt を提供することを依然として受け入れます（通常は期待もします）——これは内容だけでなく2 つのフレーム間の動きを導きます。すべてのモデルが空または欠落した prompt を直接拒否するわけではありませんが、トランジションを明示的に記述すると動きがより予測可能になります。

2 つのフレームは同じアスペクト比である必要がありますか？ kling-3.0-omni/image-to-video と seedance-2.5/image-to-video のどちらも、画像とは別に明示的な aspect_ratio を提供していません——出力のアスペクト比は入力フレームに従うため、最初のフレームと最後のフレームのアスペクト比が一致しないと、エラーではなく明らかに不自然な結果が生じます。送信前に、両方のフレームを同じ比率にトリミングするかパディングしてください。

最初のフレームを送らずに最後のフレームだけを送るとどうなりますか？ 両モデルとも対応していません——seedance-2.5 では、last_frame_url は first_frame_url と一緒にのみ使用できます。kling-3.0-omni の配列は位置で読み取られます（最初の項目 = 最初のフレーム）。終了フレームだけを指定する「逆方向」モードは存在しません。

最後のフレームの制御は動画から動画へのモーション転送と同等ですか？ 同等ではありません——それは別の機能です（hiapi の seedance-2.5/reference-to-video で、2 枚の静止画ではなく参照動画を受け取って動きやカメラワークを駆動します）。最初/最後のフレームの制御は 2 枚の画像の間を補間しますが、参照動画から動画へは既存のクリップの動きのパターンを模倣します。

最後のフレームを追加すると、最初のフレームのみの生成より高くつきますか？ 両モデルとも秒単位/解像度単位で課金され、入力画像単位では課金されないため、最後のフレームを追加すること自体でコストは増えません——現在の料金については料金ページを確認してください。