チュートリアル
HiAPI API で minimax-h3-max-turbo のテキスト読み上げ動画を呼び出す方法
- モデル
- minimax-h3-max-turbo
このページの内容
このエンドポイントの機能と適用シーン
minimax-h3-max-turbo/text-to-video は HiAPI API で公開されているテキスト読み上げ動画モデルのエンドポイントです。目標とするシーンを記述したテキストプロンプトに、出力形態を制御する少数のパラメータを加えて送信すると、HiAPI が生成された動画を返します。素材となるソースがなく、テキストの記述だけがある場合に最適です。マーケティング用の短編、ソーシャルメディア向けのトランジションショット、絵コンテのプレビュー、アプリの背景ループ動画、あるいは同一のクリエイティブコンセプトのバリエーションを大量に生成する用途に向いています。
コードを書く前に、いくつか注目すべき特性があります:
- これは生成エンドポイントであり、テンプレートではありません。 出力は構造的には予測可能(動画が1本得られる)ですが、内容自体は予測できません。各タスクは新規レンダリングとして扱い、再利用性を意識してプロンプトを設計してください。
- 非同期です。 タスクを送信する呼び出しは完成した動画のバイト列を直接返しません。まずタスクハンドルを受け取り、その後で結果をポーリングします。同期レスポンスを前提とした統合は、最初のタイムアウトで失敗します。
- 出力はリクエストパラメータで決まります。 再生時間と解像度はレンダリングコストと実際の所要時間を変えるため、選択するパラメータは同時にレイテンシと予算の意思決定でもあります。
- ソースメディアは不要です。 動画や画像をアップロードする必要はなく、プロンプトとパラメータが入力面のすべてです。
いつ別の手段を使うべきでしょうか? すでに素材があり、スタイルを変更したり延長したりしたい場合は、これは適切なエンドポイントではありません。カメラワークや正確な構図をフレーム単位で制御する必要がある場合、テキストプロンプトでは緩すぎます。静止画が1枚だけ必要な場合は、テキスト読み上げ画像のエンドポイントの方が安くて速いです。プロンプトがショット仕様として十分な場合は、minimax-h3-max-turbo/text-to-video を使用してください。
本ガイドの残りの部分では、認証、実行可能な curl 呼び出し、同等の Python 呼び出し、タスクライフサイクル、主要パラメータ、遭遇するエラー、そして公開前の堅牢化手順を順に説明します。
前提条件と認証
初回リクエストの前に、3つのものを準備する必要があります:
- HiAPI アカウントの API キー。 機密として扱ってください。環境変数から読み込み、コードベースにコミットせず、漏洩したら即座にローテーションします。
- HiAPI のベース URL。 本ガイドのすべての呼び出しは同じベースホストに送信されます。モデルはパスセグメントで選択され、モデルごとに異なるドメインを使うわけではありません。
- HTTP クライアント。 スモークテストには curl、サービスコードには任意の標準ライブラリや HTTP クライアントを使います。
キーの渡し方
HiAPI は Authorization ヘッダーの bearer トークンでリクエストを認証します。形式は常に同じです:
export HIAPI_API_KEY="your_api_key_here"
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json
2つの習慣がデバッグ時間を大幅に節約します:
- ヘッダーの綴りは正確に。
Authorizationの A は大文字、Bearerの後にスペースが1つ、その後にキーが続きます。スペースが1つ足りないのが、不可解な 401 の最も一般的な原因です。 - 常に
Content-Type: application/jsonを送信する。 JSON を期待するサーバーはこのヘッダーのないリクエストボディを拒否したり誤って解析したりしますが、受け取るエラーは多くの場合、真の原因ではなく特定のフィールドが欠けていると述べます。
開発前に検証する
いきなり動画エンドポイントを使わないでください。まず安価で高速な呼び出しを行い、キーとベース URL が正しく解決されることを確認してから進めます。この健全性チェックが失敗した場合、下流のすべてが機能せず、誤ったレイヤーでデバッグすることになります。キーはコードベース内の1か所、小さなクライアントモジュールに置いてください。そうすれば後のローテーションは1行の変更で済みます。
実行可能な curl リクエスト
送信呼び出しは、プロンプトとパラメータを JSON リクエストボディとしてモデルパスに送信します。以下が最小の実行可能な呼び出しです:
curl -sS -X POST "$HIAPI_BASE_URL/minimax-h3-max-turbo/text-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "日の出の時刻、霧に包まれた松林の上をゆっくりと空中から押し込むショット、柔らかなボリュームライト、シネマティック",
"duration": 5,
"resolution": "720p"
}'
各部分の役割:
-X POST—— 生成タスクは POST で作成されます。- URL —— ベースホストに
minimax-h3-max-turbo/text-to-videoパスを加えたもの。ベースホストを変数に入れておけば、テストと本番が同じコードパスを指せます。 Authorization—— 前節で説明した bearer トークン。Content-Type—— JSON リクエストボディを宣言します。prompt—— 唯一必須のクリエイティブ入力。ショットの説明として書いてください:被写体、カメラの挙動、照明、雰囲気。短い名詞句は曖昧な結果を生みます。具体的な視覚的方向を示す1〜2文の方がはるかに良い結果になります。durationとresolution—— 出力形態を制御するパラメータで、以下に専用のセクションがあります。
-sS を使って curl を静かにしつつエラーは出力させ、探索段階では整形ツールでレスポンスを出力してください。レスポンスはタスク識別子を含む JSON です。完成した動画をポーリングするために必要なので保存してください。このレスポンスに動画のバイト列は含まれないと想定してください。
デバッグ時に何が送信されたかを正確に見たい場合は -v で詳細出力を得られますが、詳細出力にはヘッダーが含まれる可能性があるため、ログを共有する前に削除してください。
同等の Python リクエスト
Python 版は同じリクエストで、キーを環境から読み込み、レスポンスを解析するだけです。以下は小さな再利用可能なクライアントです:
import os
import time
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
MODEL_PATH = "/minimax-h3-max-turbo/text-to-video"
def submit_video(prompt: str, duration: int = 5, resolution: str = "720p") -> dict:
payload = {"prompt": prompt, "duration": duration, "resolution": resolution}
resp = requests.post(
f"{BASE_URL}{MODEL_PATH}",
headers=HEADERS,
json=payload,
timeout=30,
)
resp.raise_for_status()
return resp.json()
if __name__ == "__main__":
job = submit_video(
"日の出の時刻、霧に包まれた松林の上をゆっくりと空中から押し込むショット、柔らかなボリュームライト、シネマティック"
)
print(job)
適応時の注意点:
json=payloadはリクエストボディとコンテンツタイプを同時に設定します。手動でシリアライズしないでください。timeout=30は送信呼び出しの時間を制限します。送信は速く、レンダリングは速くないので、ここではタイムアウトを短く設定し、待機はポーリングに任せます。raise_for_status()は非 2xx レスポンスを例外に変換し、認証や検証の失敗を即座に明らかにします。エラーレスポンスボディを黙って返し、後でタスクとして誤って解析することを防ぎます。- 解析済みの JSON を辞書として返すので、呼び出し側でタスク識別子を抽出します。これによりヘルパー関数は汎用的なまま、オーケストレーションコードがその扱いを決められます。
非同期スタックを使っている場合も、同じ形が選択した HTTP クライアントに適用されます:ヘッダーを1回構築し、リクエストボディを POST し、ステータスを確認し、解析済みのレスポンスボディを返します。
非同期タスクのライフサイクル処理
生成には時間がかかるため、エンドポイントは送信とポーリングに分かれています。ライフサイクルは常に:送信、タスク識別子の受信、タスクが終態を報告するまでポーリング、そして出力の取得です。
送信
前述の POST を送信し、レスポンスからタスク識別子を読み取ります。直ちに記録し、自分のリクエスト ID と関連付けてください。そうすれば後でポーリングが失敗したときに元のプロンプトまで遡れます。
バックオフ付きポーリング
タイトなループでポーリングしないでください。短い間隔から始めてバックオフします:
def wait_for_job(job_id: str, max_wait: int = 600) -> dict:
deadline = time.time() + max_wait
interval = 2.0
while time.time() < deadline:
resp = requests.get(
f"{BASE_URL}{MODEL_PATH}/{job_id}",
headers=HEADERS,
timeout=30,
)
resp.raise_for_status()
job = resp.json()
status = job.get("status")
if status in ("succeeded", "failed"):
return job
time.sleep(interval)
interval = min(interval * 1.5, 15.0)
raise TimeoutError(f"job {job_id} did not finish in {max_wait}s")
3つの詳細がこのコードを信頼できるものにします。第一に期限:永遠にポーリングするのではなく、最終的に諦めてタイムアウトを投げるようにしてください。第二に上限付きバックオフ:数秒から始めて段階的に倍増し、間隔に上限を設けることで、進捗を保ちながら API を頻繁に叩きません。第三に終態処理:成功と失敗のみを終態とみなし、タスクオブジェクトを返して呼び出し側が分岐できるようにします。
結果の取得
タスクが成功を報告したら、レスポンスには完成した動画の場所が含まれます。できるだけ早く自分のストレージにダウンロードまたはストリーミングし、URL をタスク ID と一緒に記録してください。リンクが永久に有効だと仮定せず、ポーリングの各イテレーションで動画を取得しないでください。タスクステータスをポーリングし、成功時に一度だけ取得します。
duration と resolution パラメータ
2つのリクエストパラメータが出力を決定し、同時にレンダリング時間と呼び出しコストも決定します。
duration
生成クリップの長さ。クリップが長いほどレンダリング時間は比例して増加し、ポーリングウィンドウが長くなり、クライアントのタイムアウトが発動する確率が高まります。実用的なアドバイス:
- ユースケースに長さを合わせる。 ソーシャルメディアのトランジションショットは短く、背景ループは許容できる程度にループするだけの長さで十分です。実際の表示より長い内容を生成するのは純粋な無駄です。
- イテレーション時は小さく始める。 短い長さでプロンプトを調整し、勝ち残ったプロンプトを最終的な長さで再レンダリングします。
- コストは出力規模に比例して増えることを忘れない。 課金は出力の長さに基づくため、長さはクリエイティブなレバーであると同時に予算のレバーでもあります。
resolution
出力の空間品質。解像度が高いほど詳細が増えますが、レンダリング時間と費用も増えます。推奨:
- スペック表ではなく納品シーンで選ぶ。 動画がフィードや小さなプレーヤーに表示されるなら、そのシーン以上の解像度で生成しても何の利益もありません。
- 低解像度でイテレーション、高解像度で出荷。 プロンプトを修正している間は低解像度でプレビューし、承認されたプロンプトを納品解像度で再送信します。
- 高い設定はより長い待ち時間を意味する。 ポーリングの期限は許容する最大の組み合わせに合わせて設定し、最小の組み合わせに合わせないでください。
これら2つの値をコードのあちこちに散らばせるのではなく、同じ設定オブジェクトに入れてください。そうすればプレビューから本番への切り替えは、忘れられたリテラルではなく、意図的で可視的な編集になります。
よくあるエラーのデバッグ
ほとんどの失敗は4つのカテゴリに分類できます。コードを変更する前に、症状をカテゴリに照合してください。
認証失敗
401 は HiAPI があなたの資格情報を受け入れないことを意味します。順に確認してください:Authorization ヘッダーが存在し正しく綴られているか。Bearer の後にちょうど1つのスペースがあるか。キーが現在有効で、他のプロジェクトのものではないか。環境変数が実際に読み込まれているか(キーを貼り付けた際の末尾の改行は定番の問題です)。キー自体ではなく変数の長さをエコーして確認してください。
検証失敗
401 以外の 4xx は通常、リクエストボディに誤りがあることを意味します。Content-Type が欠けているか application/json でない。prompt が欠けているか空。duration や resolution が許可されたセットを超えている。エラーメッセージを文字通りに読んでください。通常は問題のあるフィールドを指摘します。curl 版で再現してください。そこにはリクエストボディを覆い隠すライブラリ層がありません。
タイムアウト
2種類の異なるタイムアウトがあります。送信タイムアウトは POST 自体が返らないことを意味し、通常はネットワークパスや過度に積極的なクライアントタイムアウトを指します。ポーリングタイムアウトはタスクが期限までに終態に達しなかったことを意味します。レンダリングが実際により長くかかっているか、期限が本番設定ではなくプレビュー設定に基づいているかのどちらかです。後者の修正は、ポーリング間隔を短くするのではなく、大きな duration と resolution に対して max_wait を増やすことです。
ポーリングエラー
より隠れたものです。スリープせずにポーリングするとクォータを浪費し、レート制限を招きます。固定の短い間隔でのポーリングも同じ効果があります。誤ったタスク ID のポーリングは、通常、複数の送信間で変数を再利用したことが原因です。中間状態をエラーとして扱う。そして各イテレーションで動画 URL を取得し、成功時に一度だけ取得しない。タスク ID と観察された各状態を記録してください。シーケンスを見れば、どれに該当したかがすぐにわかります。
公開前の本番チェックリスト
動作するスクリプトから無人で稼働するサービスへ移行するには、同じリクエストの周りにいくつかのレイヤーを追加する必要があります。
- ジッター付きリトライ。 一時的なネットワークエラーと 5xx レスポンスに対して、指数バックオフとランダム化を伴うリトライを行います。検証エラーは決してリトライしないでください。同じように失敗し、クォータを消費するだけです。
- いたるところに有界タイムアウト。 送信には短いタイムアウト、ポーリングにはより長い期限(許容する最大の duration と resolution に設定)、動画ダウンロードにもタイムアウトを設定します。
- 構造化ログ。 自分のリクエスト ID、タスク ID、観察された各状態遷移、最終結果を記録しますが、API キーや完全なヘッダーは記録しないでください。深夜3時に問題が起きたとき、このログが唯一の証拠です。
- 自分のレイヤーで冪等性を。 自分のリクエスト ID からタスク ID へのマッピングを維持し、クライアントのリトライが黙って2回目のレンダリングを生成しないようにします。
- コスト管理。 課金は出力の長さに基づくため、サービスが受け入れる最大の duration と resolution に上限を設け、人間またはルールによる最終レンダリング承認の前に、プロンプトプレビューを低い設定に保ちます。
- キーの衛生。 シークレットストアからキーを読み込み、計画通りにローテーションし、テストと本番で異なるキーを使い、漏洩したテストキーが本番予算を消費できないようにします。
- 結果の帰属。 タスクが成功したら直ちに完成した動画を自分が管理するストレージにコピーし、配信 URL は一時的なリンクとして扱います。
これらを実装すれば、エンドポイントは予期せぬ事態の源ではなく、予測可能な依存関係になります。まず上記の curl リクエストで資格情報を確認し、次に Python クライアントをサービスに導入し、このチェックリストの検査で包み込んでください。