HiAPI
ブログ

チュートリアル

HiAPI API で minimax-h3-max-turbo/image-to-video を使用する方法:curl、Python、および利用可能なリクエスト例

Nov 17, 2026
テラコッタとアンバー色の横長の階段状の帯が暖かな砂色の背景を横切って下降する、フラットな印刷エッジの抽象的なカバーアート。
このページの内容

このエンドポイントが行うことと、いつ使うべきか

minimax-h3-max-turbo/image-to-video は、ソース画像とテキストプロンプトを受け取り、その画像を起点とした短い動画を返します。画像は最初のフレーム(または視覚的なアンカー)として機能するため、出力はその構図、色調、被写体の同一性を受け継ぎます。その後、プロンプトで次に起こるべきこと——カメラの動き、被写体の動作、雰囲気——を記述します。

テキスト・トゥ・ビデオではなくこれを選ぶべき場面

参照となる視覚素材がなく、モデルにすべてを創造させたい場合はテキスト・トゥ・ビデオが適したツールです。最初のフレームそのものが要点である場合は、イメージ・トゥ・ビデオが正しい選択です。承認済みの製品画像、絵コンテのキーフレーム、キャラクターデザイン、またはユーザーがアップロードした写真があり、それを識別可能なまま動かしたい場合に使います。具体的には、チームは次のような場合にこのエンドポイントを使用します。

  • 最初のフレームが契約上の要件である。 マーケティングチームは、似た画像ではなく正確なメイン画像で開始する必要があります。
  • クリップ間の一貫性が重要である。 同じソース画像を再利用することで、キャラクターや製品が一連のクリップを通じて安定します。
  • ユーザーコンテンツを動かしたい。 エンドユーザーがアップロードした写真は、再解釈されるのではなく、アニメーション化されるべきです。
  • プロンプトの範囲を絞りたい。 シーン全体をゼロから記述するよりも動きを記述する方が簡単なので、プロンプトは短く予測可能に保たれます。

このエンドポイントは非同期です。タスクを送信し、後でレンダリングされた動画を取得します。この形態はキュー駆動のバックエンドに適しており、詳細は後述します。完全なパラメータの範囲については、モデルページを参照してください。

前提条件とリクエスト構造

エンドポイントを呼び出す前に、4 つの項目を確認してください。

  1. API キー。 HiAPI アカウントで作成し、ベアラートークンとして送信します。機密情報として扱い、クライアントコードに埋め込まないでください。
  2. ベース URL。 すべてのリクエストは HiAPI の統合 API ホストに送信され、エンドポイントパスがモデル識別子になります。
  3. ソース画像——アクセス可能またはエンコード可能なもの。公開 HTTPS URL か base64 ペイロードのいずれかで、リクエストスキーマが受け入れる形式によります。
  4. HTTP クライアント——スモークテスト用の curl、および実際の統合では任意の標準ライブラリまたは Python の requests。

リクエストの構成要素

どの言語を使っても、各タスク送信には同じ概念的な構成要素が含まれます。

  • モデル / エンドポイント——minimax-h3-max-turbo/image-to-video。リクエストパスの一部であり、明確にするためリクエストボディにも繰り返し記載します。
  • ソース画像——最初のフレーム。イメージ・トゥ・ビデオとテキスト・トゥ・ビデオを区別するフィールドであり、検証エラーが最も発生しやすいフィールドです。
  • プロンプト——動きとシーンの記述。画像にすでに存在する内容ではなく、変化する内容だけを記述します。
  • オプションの生成ヒント——エンドポイントが提供する場合、長さや解像度スタイルの制御。スキーマドキュメントに記載されたパラメータのみを送信してください。未知のキーは 4xx レスポンスのよくある原因です。

送信するとタスク識別子とステータスが返されます。動画自体は後の 2 回目のリクエストで取得します。だからこそ、以下のポーリングのセクションは送信呼び出しと同じくらい重要です。

動作する curl リクエスト

次のコマンドはイメージ・トゥ・ビデオタスクを送信します。実行前に、プレースホルダー——山かっこ内の大文字のマーカー——を自分の値に置き換えてください。

curl -X POST "https://api.hiapi.ai/v1/<ENDPOINT_PATH>" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3-max-turbo/image-to-video",
    "image": "https://<YOUR_PUBLIC_IMAGE_HOST>/first-frame.jpg",
    "prompt": "Slow push-in on the product, soft studio light shifting across the surface, shallow depth of field."
  }'

このコマンドに関する実用的な注意点:

  • キーは環境変数から読み取る。 $HIAPI_API_KEY は、インラインで貼り付けるのではなくエクスポートすれば、キーがシェル履歴に残るのを防ぎます。
  • 最初のテストには公開画像 URL を使う。 これにより base64 エンコードの要素を排除しつつ、認証と接続が正常に機能することを確認できます。
  • JSON ボディを小さく保つ。 -d ペイロードがリクエスト全体です。ここでカンマが 1 つ欠けると、明確なスキーマエラーではなく紛らわしい 400 が発生します。
  • プロンプトを引用符で囲む。 句読点を含むプロンプトは、引用符で囲まないシェル文字列を壊します。

レスポンスは動画ではなくタスクオブジェクトです。そこからタスク ID を取得してください。この ID をポーリングリクエストに使用します。呼び出しがすぐに失敗する場合は、トラブルシューティングのセクションに進んでください。認証とペイロードのエラーは、後ではなくこのステップで明らかになります。

同じリクエストを Python で

以下は requests を使用した Python の同等の送信呼び出しです。環境変数に HIAPI_API_KEY が設定されていることを前提としています。

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1/<ENDPOINT_PATH>"

payload = {
    "model": "minimax-h3-max-turbo/image-to-video",
    "image": "https://<YOUR_PUBLIC_IMAGE_HOST>/first-frame.jpg",
    "prompt": (
        "Slow push-in on the product, soft studio light shifting "
        "across the surface, shallow depth of field."
    ),
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

response = requests.post(BASE_URL, json=payload, headers=headers, timeout=30)
response.raise_for_status()
job = response.json()
print(job["id"], job.get("status"))

このスニペットを改変する際に守るべきポイント:

  • タイムアウトは任意ではない。 送信は高速ですが、Web リクエストハンドラ内でソケットがハングすると、ワーカーも巻き添えになります。
  • 解析前に raise_for_status() を呼ぶ。 これにより、サイレントな 401 が実際にログ記録できる例外に変わります。
  • レスポンスではなくタスク ID を返す。 サービスでは、送信関数は識別子を返し、別のポーラー——またはバックグラウンドタスク——が待機を担当するようにします。
  • ペイロードを変数に保持する。 呼び出しが成功した後、画像 URL を署名付きアップロード URL や base64 文字列に置き換えるのは 1 行の変更で済みます。

ここでは意図的にラッパーライブラリではなく素の HTTP クライアントを使用しています。リクエストの形式こそが契約であり、技術スタックで使用するどの言語でも再現できるべきだからです。

画像と最初のフレームの準備

失敗するイメージ・トゥ・ビデオタスクのほとんどは、プロンプトではなく画像で失敗します。いくつかの習慣を身につければこれを避けられます。

形式と配信

標準的で広くサポートされているラスタ形式——JPEG または PNG——を使用し、URL が Cookie なしで公開取得でき、ログインページにリダイレクトせず、送信後に生成される期限切れの署名にも依存しないことを確認してください。アセットがプライベートバケットにある場合は、タスクの想定実行時間より明らかに長い有効期間の署名付き URL を生成してください。base64 ペイロードの場合、スキーマが生のエンコード済みバイトを期待するなら data URI プレフィックスを外し、エンコード後のサイズがドキュメントの制限を十分下回ることを確認してください。

サイズと構図

モデルは固定の出力サイズで動画をレンダリングするため、ソース画像はフィットされます。2 つの結果があります。

  • 望むアスペクト比に合わせる。 縦向きのポートレート写真を横向きのレンダリングに渡すと、クロップされるか黒帯が付き、被写体が中心から外れる可能性があります。
  • 動きのための余白を残す。 プロンプトがカメラの押し込みや被写体の上方向への移動を記述する場合、ソース画像のその方向にスペースを残してください。

最初のフレームをそのまま保つ

冒頭のフレームは主に画像自体に依存します。プロンプトは、最初のフレームの後に何が起こるかへの指示として書いてください。カメラの挙動、被写体の動作、照明の変化を記述します。シーンの再記述は避けてください。画像がすでに「白い床の上の赤い椅子」を示している場合、繰り返し記述すると忠実度ではなくドリフトが増えることがよくあります。結果がソース画像から逸脱する場合は、まずプロンプトを短くし、それから画像の変更を検討してください。

ドキュメント化されていないパラメータが存在すると仮定しないでください。望む制御項目がスキーマにない場合は、プロンプトまたは画像の準備を通じて実現してください。

非同期タスクのライフサイクルを処理する

イメージ・トゥ・ビデオタスクは同期ではありません。パターンは送信 → ポーリング → 取得であり、本番統合では 3 つのステップすべてを明示的に実装すべきです。

1. 送信して永続化する

リクエストを送信し、返されたタスク ID をすぐに保存します。できれば独自の相関 ID、リクエストペイロードのハッシュ、タイムスタンプと一緒に保存してください。送信と保存の間にプロセスが停止すると、取得できないタスクに対して料金を支払うことになります。

2. バックオフ付きのポーリング

保存した ID を使ってタスクステータスエンドポイントをポーリングします。動画のレンダリングは画像生成より明らかに時間がかかるため:

  • 適度な間隔——数秒——から始め、タスクの経過時間が増えるにつれて間隔を広げ、固定レートでエンドポイントを叩き続けないようにします。
  • 総待機時間をタスクに適した上限に制限し、その後タスクをタイムアウトとして扱い、再試行するかどうかを決定します。
  • 終端状態は終端状態として扱います。タスクが成功または失敗を報告したら、ポーリングを停止します。
import time

def wait_for_job(poll_fn, job_id, max_wait=600):
    deadline = time.time() + max_wait
    interval = 5
    while time.time() < deadline:
        job = poll_fn(job_id)
        if job["status"] in ("succeeded", "failed"):
            return job
        time.sleep(interval)
        interval = min(interval * 1.5, 30)
    raise TimeoutError(f"job {job_id} did not finish in {max_wait}s")

3. 出力を取得して保存する

成功すると、タスクオブジェクトは結果の場所を持ちます。動画を速やかにダウンロードし、自分のストレージにコピーしてください。出力 URL は一時的なリソースとして扱い、永続的なアセットライブラリとは見なさないでください。タスク ID を保存ファイルのそばに記録し、サポート担当が任意のクリップをそのリクエストまで追跡できるようにします。

再試行については、保存した ID を持つタスクを再ポーリングするだけにしてください。盲目的に再送信すると、重複レンダリングと重複課金が発生します。

よくあるエラーのトラブルシューティング

認証失敗(401 / 403)

まず Authorization ヘッダを確認してください。Bearer という語、スペース 1 つ、その後にキーがあり、キーのコピーに伴う末尾の改行がないこと。キーがアクティブで、意図したアカウントに属していることを確認してください。curl は動くが Python は動かない場合は、ヘッダの長さを出力してください。空の環境変数は、有効に見えるが役に立たないトークンを生成します。

不正な形式またはサポートされていない画像ペイロード(400 / 422)

最も一般的な非認証の失敗です。順に確認してください。

  • 画像 URL が正常に解決され、HTML ログインページにリダイレクトしない。
  • 形式が JPEG または PNG であり、WebP、HEIC、PDF のサムネイルではない。
  • エンコードまたはダウンロード後のサイズがドキュメントの制限内である。
  • base64 ペイロードに data: プレフィックスがなく、改行による空白もない。
  • 画像が破損していない——API を責める前に、自分で取得して開いて確認する。

未知または無効なパラメータ

フィールド名の誤記、またはエンドポイントが公開していないパラメータは、通常そのフィールドを指摘する検証エラーを返します。推測的なパラメータを削除し、ドキュメントで規定された最小限の要件から再構築してください。

レート制限(429)

指数バックオフを行い、レスポンスに再試行のヒントがあればそれに従ってください。タイトなループで再試行しないでください。制限が悪化します。頻繁に発生する場合は、ユーザーリクエストからインラインでトリガーするのではなく、キューを通じてバッチ送信してください。

タスクのタイムアウトとポーリングの停滞

タスクが予算内で終端状態に達しない場合は、タスク ID とステータス履歴を記録してポーリングを停止してください。持続的なタイムアウトは通常、送信時に画像が大きすぎるか異常であったことを示すため、画像準備のセクションを見直してください。試行回数の上限を設定せずに自動再送信しないでください。

本番稼働前のチェックリスト

このエンドポイントが実際のトラフィックに近づく前に、以下を検証してください。

  • すべての箇所にタイムアウトがある。 送信には短いタイムアウト、ポーリングには総待機上限、再試行にはハードリミットを設定します。無制限の while True ループはありません。
  • バックオフ付きの再試行。 429 と一時的な 5xx レスポンスは再試行します。検証エラーは決して再試行しないでください。同じように失敗します。
  • ログにタスク ID がある。 各リクエストについて、タスク ID、独自の相関 ID、最終ステータスを記録します。これは保持できる最も有用なデバッグ成果物です。
  • 出力は自分のストレージに保存する。 完了した動画を返された URL から永続ストレージにコピーし、再現性のためにソース画像の参照を保持します。
  • エッジでの画像検証。 誤った形式や過大なアップロードを API に到達する前に拒否し、ユーザーが数分後の非同期失敗ではなく、即座に明確なエラーを受け取れるようにします。
  • コスト意識。 生成はレンダリングされた動画の出力ごとに課金されるため、ユーザーまたは機能ごとのタスク量と長さを追跡してください。仮定をコードやドキュメントにハードコードするのではなく、現在の価格パネルを確認してください。
  • カナリアプロンプト。 テストスイートに既知の良好な画像とプロンプトのセットを保持し、統合を変更するたびにそれを実行して、リクエスト契約が依然として成立することを確認します。

非同期ライフサイクル——送信、永続化、ポーリング、保存——を正しく処理すれば、このエンドポイントは非常にシンプルです。モデルページから正確なスキーマを取得し、上記の送信とポーリングのパターンに組み込んでください。

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

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

APIドキュメントを読む