チュートリアル
HiAPI API で minimax-h3 を使用する方法:curl、Python、実行可能なリクエスト
このページの内容
minimax-h3 統合のエンドツーエンドの流れ
動画生成は瞬時に完了する操作ではありません。minimax-h3 はプロンプトやソース画像を受け取り、GPU プール上でタスクをスケジュールし、フレームをエンコードして出力ファイルを組み立てます。このプロセスは長さと解像度に応じて、数秒から数分かかる場合があります。もし HiAPI エンドポイントがファイルの準備完了までブロックするなら、HTTP クライアントはその間ずっと接続を開いたままになります。これはリトライ時に脆弱で、サーバーレスの時間制限にも優しくなく、リクエスト/レスポンス型の Web ハンドラ内でも動作しません。
そのため、統合は先に送信して後からポーリングという形になります。これは非同期メディア API の標準パターンです:
- 送信。タスクを記述する JSON ペイロード(プロンプト、任意の画像、長さ、アスペクト比、モデル固有のパラメータなど)を
POSTします。API は検証後、タスク識別子と初期状態を直ちに返します。 - ポーリング。その識別子を使って、短い間隔でタスク状態エンドポイントを呼び出します。状態はキュー待ち、処理中を経て、成功または失敗などの状態に遷移します。
- 取得。状態が終了状態になると、レスポンスには結果が含まれます。通常は生成された動画のダウンロード可能な URL です。
このモデルは 3 つの帰結をもたらし、それが本ガイドの以降すべてを決定づけます:
- タスク ID が唯一のハンドルです。永続化してください。これを失うとタスクを取得できず、再送信して作業に再び料金を払うしかありません。
- コードには 1 つではなく 2 つの失敗面があります。送信は失敗する可能性があり(認証、ペイロード形式の誤り)、ポーリングも失敗する可能性があります(タイムアウト、一時的なネットワークエラー、タスクが失敗で終了)。これらは分けて扱ってください。
- ポーリングのリズムは設計上の判断です。攻めすぎるとリクエストを浪費し、遅すぎるとユーザーを既に準備完了した状態のために待たせます。
本記事では、すべての呼び出しを HiAPI の統一 API に送ります。HiAPI アカウントから API キーを取得し、ペイロード内でモデルを minimax-h3 として参照する必要があります。それ以外のすべて——認証ヘッダー、ベース URL、ポーリングエンドポイント——はプラットフォーム全体で共有されるため、ここで学んだパターンはクライアントを再構築せずに他のモデルにも移行できます。
このメンタルモデルを踏まえると、設定を確認する最速の方法は単一の curl 呼び出しです。
最初の実行可能な curl リクエスト
アプリケーションコードを書く前に、キーが有効で API にアクセスできることを確認してください。ワンショットの curl コマンドは、認証の問題とペイロードの問題を区別する最も安価な方法です。
まずキーをエクスポートして、シェル履歴にリテラルで残らないようにします:
export HIAPI_API_KEY="your-api-key-here"
次に、最小限のテキストから動画へのタスクを送信します:
curl -sS -X POST "https://api.hiapi.ai/v1/video/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "minimax-h3",
"prompt": "A slow aerial shot over a fog-covered pine forest at sunrise",
"duration": 5,
"aspect_ratio": "16:9"
}'
成功レスポンスは、タスク識別子と状態を含む JSON オブジェクトを返します。構造は概ね次のようになります:
{
"id": "task_abc123xyz",
"status": "queued",
"model": "minimax-h3",
"created_at": "2024-01-01T00:00:00Z"
}
この時点ではまだ動画 URL はありません。これは想定内です——タスクは単に受け付けられただけです。実際のレスポンスのフィールド名は上記と多少異なる場合があります。仮定せずにレスポンスボディを読み取り、開発中は全体を記録してください。
リクエストの各部分の役割
- URL は HiAPI プラットフォーム上の動画生成リソースを指します。すべてのモデル呼び出しがこのベースを共有するため、モデルの切り替えはペイロードの変更だけで済み、コードの書き直しにはなりません。
Authorization: Bearerは API キーを運びます。これが最も一般的な失敗源なので、問題が起きたらまずこれを検証してください。Content-Type: application/jsonは必須です。これがないと、サーバーはリクエストボディを拒否したり誤って解析したりする可能性があります。modelは minimax-h3 を明示的に選択します。決して省略しないでください——プラットフォームはこの値に基づいてルーティングします。promptはクリエイティブな指示です。被写体、カメラの動き、照明を具体的に指定してください。曖昧なプロンプトは曖昧な動画を生みます。durationとaspect_ratioは出力を制約します。モデルがサポートする範囲内に保ってください。範囲外の値はサーバー障害ではなくペイロード検証エラーです。
タスクが存在することを確認する
送信直後に一度タスクを取得して、ID が有効であることを証明します:
curl -sS "https://api.hiapi.ai/v1/tasks/task_abc123xyz" \
-H "Authorization: Bearer $HIAPI_API_KEY"
task_abc123xyz を送信レスポンスの ID に置き換えてください。これが状態を返せば、キー、エンドポイント、タスクハンドルはすべて正しい——Python に進めます。
ここで 2 つの習慣を身につける価値があります。curl を -sS 付きで実行してエラーを静かに飲み込まず表面化させること、そして常に URL を引用符で囲むことです。JSON ペイロードでの予期しないシェル展開は、引用符自体よりもはるかに多くの時間を費やすデバッグの罠です。
同じリクエストを Python で構築する
curl 呼び出しは契約を証明しました。Python は再利用可能なものを構築する場所です。ポーリングループに直接飛び込むのではなく、送信と結果取得を 2 つの明確なメソッドとして扱う小さなクライアントクラスから始めてください。この分離により、非同期ロジックがトランスポート層の外に保たれます。
requests を使用します(非同期を好むなら httpx)。どちらも形は同じです。
import os
import time
import requests
BASE_URL = "https://api.hiapi.ai/v1"
class MiniMaxH3Client:
def __init__(self, api_key: str | None = None):
self.api_key = api_key or os.environ["HIAPI_API_KEY"]
self.session = requests.Session()
self.session.headers.update({
"Authorization": f"Bearer {self.api_key}",
"Content-Type": "application/json",
})
def submit(self, prompt: str, duration: int = 5,
aspect_ratio: str = "16:9", **extra) -> str:
payload = {
"model": "minimax-h3",
"prompt": prompt,
"duration": duration,
"aspect_ratio": aspect_ratio,
**extra,
}
resp = self.session.post(
f"{BASE_URL}/video/generations",
json=payload,
timeout=30,
)
resp.raise_for_status()
data = resp.json()
return data["id"]
ここには意図的な選択がいくつかあり、指摘する価値があります。
生の requests ではなく session を使う。requests.Session を再利用すると、送信呼び出しとポーリング呼び出しの間で接続が維持されます。同じホストを繰り返しポーリングする場合に重要です。またヘッダーを一元管理できるため、認証ヘッダーは一度だけ定義されます。
送信時にはハードタイムアウトを設定する。ほぼ即座に返るはずのリクエストには、30 秒は余裕があります。タイムアウトがないと、ネットワークの揺らぎでプロセスが無限にハングします。リモート API 呼び出しでは決して timeout なしにしないでください。
解析前に raise_for_status() を呼ぶ。非 2xx レスポンスのレスポンスボディは、成功レスポンスとは形が異なることがよくあります。先にステータスコードを確認すれば、エラーハンドリングは整ったエラーメッセージを読み取れ、id キーがないことでクラッシュすることはありません。
**extra のパススルー。モデル固有のオプションは進化します。余分なキーワード引数をパススルーすれば、メソッドシグネチャを毎回編集せずに新しいパラメータを試せます。
使ってみる
client = MiniMaxH3Client()
task_id = client.submit(
"A slow aerial shot over a fog-covered pine forest at sunrise"
)
print(f"submitted: {task_id}")
これが送信パスのすべてです。クライアントは文字列——タスクハンドル——だけを返し、それ以外は何も返しません。submit に結果も待たせる誘惑に抗ってください。送信と待機を 1 つのメソッドに混ぜると、リトライが曖昧になります。失敗時、タスクが作成されたかどうか判断できず、重複生成のリスクがあります。分離したままにして、呼び出し元に戦略を決めさせてください。
API を叩きすぎずに結果をポーリングする
ポーリングは不注意に書かれがちな部分です。遅延のない素朴な while True ループは、2 分かかるタスクに対して数百のリクエストを送り、しかもタスクが既に失敗した後も送り続けます。
正しいポーリングループには 4 つの責務があります:状態を確認する、待つ、終了状態で停止する、最終的に諦める。
TERMINAL = {"succeeded", "failed", "cancelled"}
def wait_for(self, task_id: str, interval: float = 3.0,
max_wait: float = 600.0) -> dict:
deadline = time.monotonic() + max_wait
while time.monotonic() < deadline:
resp = self.session.get(f"{BASE_URL}/tasks/{task_id}", timeout=30)
resp.raise_for_status()
data = resp.json()
status = data.get("status", "unknown")
if status in TERMINAL:
return data
time.sleep(interval)
raise TimeoutError(f"task {task_id} did not finish in {max_wait}s")
間隔の選び方
動画生成では、固定の数秒が妥当なデフォルトです。タスクは最初の数秒で完了することはありません——モデルの読み込みとフレームのエンコードには実際の時間がかかります——そのため 200 ミリ秒ごとのポーリングは負荷以外何も得ません。丁寧かつ効率的にしたいなら、上限付きの指数バックオフを使用してください。1〜2 秒から始め、各ラウンドで約 1.5 倍し、5〜10 秒に達したらそこに保ちます。早期のポーリングは素早い失敗を迅速に捉え、後期のポーリングは長時間のレンダリング中にコストを抑えます。
正しく停止する
認識できない状態は非終了状態として扱い、待機を続けてください——ただしある限界までです。重要な停止条件は 2 つあります:
- 終了状態。成功時には直ちに返します。失敗時には、空の結果を返すのではなくレスポンスからエラーメッセージを表面化させてください。原因はログにとって重要です。
- 実時間の予算。壁時計時間ではなく単調時計を使い、システム時計の調整でループが早く終了したり永遠に実行されたりしないようにします。選択した長さと解像度で現実的な最長タスクを余裕をもって上回る上限を選び、そこに達したら対処すべき操作エラーとして扱ってください。
結果を返す
状態が成功で終了すると、レスポンスは生成された動画の URL を運びます。速やかにダウンロードしてください——結果 URL には通常有効期限があります——永続的なアクセスが必要なら、自前のオブジェクトストレージに保存してください。ベンダーの URL をエンドユーザーに直接渡して永遠に存在すると仮定しないでください。
もう 1 つ実用的なヒント:デバッグレベルで各ポーリングのタスク ID、状態、経過時間を記録し、情報レベルで終了結果を記録してください。タスクが予想より長くかかったとき、そのタイムラインが 5 分での診断と 1 時間の推測の差になります。
テキストから動画と画像から動画のリクエスト形態
2 つの生成モードはペイロードの大部分を共有します。違いはクリエイティブな入力にあり、その違いはどのような失敗を予期すべきかに下流の影響を与えます。
テキストから動画
これは前のセクションで示した形態です:プロンプトと出力制約。モデルは構図、動き、照明、被写体の詳細などすべてを発明します。ペイロードには次を含めます:
model:minimax-h3prompt:シーンの説明duration、aspect_ratio、およびその他の出力制御
アンカーとなるものがないため、プロンプトの品質が結果を支配します。品質に関する形容詞を積み重ねるのではなく、カメラの動作(「ゆっくりとしたプッシュイン」、「固定三脚ショット」)と照明(「ゴールデンアワーの逆光」)を記述してください。曖昧な最上級の形容詞はほとんど効果がなく、具体的な物理的記述は大きく効果があります。
画像から動画
画像から動画の変種は、同じリクエストにソース画像の参照を追加します。通常はプロンプトの隣の画像フィールドに画像 URL またはアップロード済みリソース識別子を提供し、モデルはその開始フレームからアニメーション化します。
client.submit(
"Gentle wind moves the hair, subtle camera push forward",
duration=5,
image_url="https://example.com/portraits/source.jpg",
)
プロンプトは今や異なる役割を果たします。視覚内容は画像で固定されているため、内容ではなく動きとカメラを指示します。完全なシーン記述を書くことはしばしば逆効果です——モデルは画面に存在しないものを追加できません。動きのプロンプトは短く具体的に保ってください。
画像モードで正確なフィールド名と受け付けられる画像形式、および両モードでの長さとアスペクト比の有効範囲については、リクエストリファレンスを参照してください。これらの制約こそがペイロード検証エラーを引き起こすものなので、一度読めば後のデバッグの 1 ラウンドを節約できます。
実用的な経験則
新しいシーンが必要なときはテキストから動画を選んでください——B-roll、ムード映像、コンセプトの可視化。一貫性が重要なときは画像から動画を選んでください:製品写真をアニメーション化する、キャラクターの肖像を生き生きとさせる、絵コンテのフレームを動くショットに変換するなど。モードはペイロードの違いであり統合の違いではないため、1 つのクライアントクラスがオプションの画像パラメータを受け入れるだけで両方に対応できます。
よくあるエラーのデバッグ
minimax-h3 の呼び出しが失敗するとき、原因はほぼ常に 4 つの場所のいずれかにあります。この順序でトラブルシューティングしてください。
1. 認証
症状:401 または 403 レスポンス、または資格情報が無効であると述べるエラーボディ。
Authorizationヘッダーが存在し、Bearer <key>の形式で、間にスペースが 1 つあることを確認します。- 環境変数が実際に値を持っているか確認します——環境変数に貼り付けた末尾の改行は、ログでは見えない形でヘッダーを壊します。
- キーが期待するのと同じ HiAPI プロジェクトに属し、ローテーションされていないことを確認します。
最速のテスト:先ほどの生の curl を再実行します。curl が動いて Python が動かないなら、バグはアカウントではなくクライアントにあります。
2. 形式の誤ったペイロード
症状:400 または 422 レスポンス、または名前付きパラメータの検証メッセージ。
Content-Type: application/jsonがあり、ボディが有効な JSON であることを確認します——余分な末尾のカンマが典型的な犯人です。modelが正確にminimax-h3であることを確認します。durationとaspect_ratioがモデルのサポート範囲内であることを確認します。- 画像モードでは、画像参照にアクセス可能で受け付けられる形式であることを確認します。
エラーメッセージを文字通りに読んでください。検証エラーは通常、違反したフィールドを名指しします。開発者はしばしばこれを飛ばして、ペイロードの無関係な部分を書き直し始めます。
3. ポーリングが完了しない
症状:妥当な時間が経っても状態がキュー待ちまたは処理中のまま、または永遠にループする。
- 完全な状態レスポンスを記録します——状態値がコードの仮定と異なる可能性があります。
- 読み取っているフィールドを確認します。終了セットが
"completed"をチェックしているのに API が"succeeded"を返すなら、ループは永遠に実行されます。開発の早い段階で生のレスポンスを 1 つ出力してください。 - タスク ID が切り捨てや空白なしで正確にコピーされていることを確認します。
- 実時間の締め切りを追加します。上限のないスタックしたループは API ではなくコードのバグです。
4. タイムアウトと一時的なネットワークエラー
症状:接続エラー、読み取りタイムアウト、または送信やポーリング時の 5xx レスポンス。
- すべての呼び出しに明示的な
timeoutを渡すようにします——多くのクライアントのデフォルトはなしで、スタックしたソケットが永遠にブロックする可能性があります。 - 接続タイムアウトと読み取りタイムアウトを区別します。読み取りタイムアウトした送信は実際にはタスクを作成している可能性があります。リクエスト ID が返されたなら、レスポンスヘッダーからそれを記録し、盲目的に再送信する前にタスクが現れていないか確認してください。
- ポーリングの 5xx はリトライしてください——タスクは問題ない可能性があります。送信の 5xx は、重複生成を避けるためにタスクが作成されていないことを確認してください。
素早いトリアージの習慣:プロジェクトの隣に下書きの curl ファイルを置き、送信とポーリングのコマンドを環境変数から事前入力しておきます。アプリケーションコードの外でバグを再現するのは数秒で済み、問題がトランスポートかロジックかを即座に教えてくれます。
本番環境対応にする
実行可能なスクリプトは実行可能なサービスではありません。動画タスクは十分に遅く、本番トラフィックは重なり、リトライし、時には単発の手動実行では決して明らかにならない形で失敗します。4 つのパターンが重荷の大部分を担います。
バックオフ付きリトライ——ただし安全な場所でのみ
リトライ戦略はどの呼び出しが失敗したかに依存します:
- ポーリングは本質的に安全にリトライできます。失敗した状態チェックには副作用がないため、ジッター付きの指数バックオフでリトライし、数回の試行に制限します。
- 送信は盲目的にリトライできません。タイムアウトはタスクが作成されなかったことを意味しません。再送信する前に、そのリクエストのタスクが既に存在するか確認します(利用可能ならレスポンスヘッダーのリクエスト ID、または短い照合ウィンドウを使用)。あるいは、ペイロードのハッシュでタスク ID をキャッシュして送信を冪等にすれば、リトライされたリクエストは新しいレンダリングを開始するのではなく既存のタスクを返します。
- モデルレベルの失敗——終了状態
failed——は、通常、同じペイロードで自動リトライすべきではありません。同じ入力は同じように失敗する傾向があります。記録し、アラートを出し、人間や修正されたプロンプトに委ねてください。
各バックオフのスリープにジッターを追加してください。それがなければ、同期してリトライするワーカーのバッチが同期したスパイクを生み、悪い状況をさらに悪化させます。
タスク ID を至る所で記録する
タスク ID は、あなたのシステムと生成された動画の間の唯一の永続的なリンクです。送信が成功した瞬間に、構造化フィールド——task_id、モデル、長さ、送信タイムスタンプ——を使ってログに書き込んでください。ユーザーが動画の紛失を報告したとき、タスク ID で検索すれば数秒で完全な履歴が見つかります。また終了状態と経過時間も記録し、「これは通常どれくらいかかるか」に記憶ではなくデータで答えられるようにしてください。
明示的なタイムアウト予算を設定する
リクエストごとのタイムアウトだけでなく、操作全体の総予算として考えてください。タスクには 3 つの段階——送信、待機、ダウンロード——があり、それぞれに境界が必要です。妥当な構造:
- 死んだ接続を素早く検出するための、送信とポーリングリクエストの短いタイムアウト。
- サポートする最長の長さと解像度に余裕を持たせて設定した、ポーリングの総実時間上限。
- 大きなファイルがメモリを食い尽くしたりワーカーをハングさせたりしないための、ストリーミング書き込みを伴う有界ダウンロード。
予算を使い切ったら、タスクをきれいに失敗させ、並行スロットを解放し、明確なエラーを報告してください。予測可能な失敗は、プラットフォームがコンテナを再起動するまでハングするリクエストに勝ります。
送信と消費を分離する
先に送信して後からポーリングする設計は、自然にキューアーキテクチャにマッピングされます:Web ハンドラは送信してタスク ID を返し、バックグラウンドワーカーがポーリングして結果を保存し、クライアントはあなたの状態エンドポイントをポーリングします。これによりユーザー向けのレイテンシがレンダリング時間から切り離され、並行制限が実施しやすくなり、送信の急増が Web 層のスレッドプールを枯渇させないことを意味します。
この 4 点を正しく行えば、minimax-h3 の非同期の形はあなたと対立するのではなく協力します:タスクは追跡され、リトライは安全で、失敗は可視化され、何も無限にハングしません。