MiniMax H3 Max APIの使い方：テキストと画像から動画を生成する

このガイドは、リクエストを成功させる最短経路に加え、本番に必要な検証、ポーリング、コールバック、ストレージ、フォールバックを扱います。H3 Max専用ドキュメントが公開されるまでは、モデルページの最新ルート仕様で正確なフィールドを確認してください。

EvoLink APIキーを作成し、MiniMax H3 Maxモデルページでライブ見積もりを確認してください。ワークフローが2Kやより広い参照素材を必要とする可能性がある場合は、H3 Max vs H3 ガイドを手元に置いておいてください。

前提条件

最初のリクエストを行う前に、次の点を確認してください。

正しいH3 MaxモデルIDを選ぶ

ステップ1：テキストから動画のリクエストを送る

curl --request POST \
  --url https://api.evolink.ai/v1/videos/generations \
  --header "Authorization: Bearer $EVOLINK_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "minimax-h3-max-text-to-video",
    "prompt": "A premium running shoe rotates on a clean studio pedestal while soft daylight moves across the fabric. Slow camera push-in, realistic material detail, no text or logos added.",
    "duration": 5,
    "quality": "768p",
    "aspect_ratio": "16:9"
  }'

主なT2Vパラメータは次のとおりです。

{
  "id": "task-unified-1774857405-abc123",
  "model": "minimax-h3-max-text-to-video",
  "object": "video.generation.task",
  "progress": 0,
  "status": "pending",
  "type": "video"
}

ステップ2：開始/終了フレームの画像から動画リクエストを送る

curl --request POST \
  --url https://api.evolink.ai/v1/videos/generations \
  --header "Authorization: Bearer $EVOLINK_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "minimax-h3-max-image-to-video",
    "prompt": "The camera makes a slow half-orbit as the box opens and the product rises smoothly. Preserve the packaging shape, colors, and lighting; end exactly on the supplied final composition.",
    "image_start": "https://cdn.example.com/h3-max/start.webp",
    "image_end": "https://cdn.example.com/h3-max/end.webp",
    "duration": 8,
    "quality": "768p"
  }'

指定する各画像は直接アクセスできるHTTP(S) URLを使い、現在の契約に従う必要があります。

• JPG、JPEG、PNG、WEBP、HEIC、またはHEIF。
• 画像1枚あたり最大30 MB。
• 幅と高さは256から5,760ピクセルの範囲。
• 幅と高さの比率は0.4から2.5の範囲。
• 開始フレームは最大1枚、終了フレームは最大1枚。
• JSONボディ全体は64 MB以下；Base64と mm_file:// は受け付けない。

ステップ3：タスクのステータスをポーリングする

同じBearerトークンでタスクを照会します。

curl --request GET \
  --url "https://api.evolink.ai/v1/tasks/task-unified-1774857405-abc123" \
  --header "Authorization: Bearer $EVOLINK_API_KEY"

{
  "id": "task-unified-1774857405-abc123",
  "model": "minimax-h3-max-text-to-video",
  "object": "video.generation.task",
  "progress": 100,
  "status": "completed",
  "results": ["https://files.example.com/generated-video.mp4"],
  "type": "video"
}

シンプルなポーリングポリシーでは、継続的に照会するのではなく、ジッター付きの上限のある指数バックオフを使うべきです。たとえば、2秒付近から始めて10-15秒に向けて間隔を伸ばし、アプリケーションで定義した期限で停止し、保存したタスクIDを使って後のワーカーが再開できるようにします。APIの契約ではH3 Maxのキャンセルは提供されないため、クライアントのタイムアウトを上流のキャンセルと取り違えないでください。

ステップ4：本番向けにコールバックを追加する

{
  "model": "minimax-h3-max-text-to-video",
  "prompt": "A cinematic overhead shot of a city block transitioning from morning to night.",
  "duration": 5,
  "quality": "768p",
  "aspect_ratio": "16:9",
  "callback_url": "https://api.example.com/webhooks/evolink/video"
}

現在のEvoLinkの契約ではHTTPSが必須で、プライベートIPの宛先は拒否され、最大10秒待機し、失敗したコールバックは最大3回再試行されます。ハンドラーは次のようにしてください。

1. アプリケーションで設定した検証メカニズムでリクエストを認証する。
2. タスクIDを冪等キーとして使う。
3. 2xxレスポンスを素早く返す。
4. ダウンロードと重い後処理はキューに移す。
5. 必要に応じて、最終的な顧客への納品前にコールバックの状態をタスクエンドポイントと突き合わせる。

ポーリングは復旧経路として使える状態に保ってください。Webhookは遅延したり、ネットワークポリシーで拒否されたり、アプリケーション基盤で二重に処理されたりすることがあります。

送信前にリクエストを検証する

カテゴリ別にエラーを処理する

HTTPエラーと非同期タスクの失敗は分けてください。作成呼び出しが成功しても、後で生成が失敗することがあります。タスクID、ルート、入力クラス、長さ、画質、最終ステータス、エラーコード、再試行回数、フォールバック結果をログに記録し、シークレットや機密性のあるソースURLはログに残さないでください。

本番への引き渡しを設計する

リクエストとタスクの関係を保存する

送信前に独自のジョブIDを作成します。EvoLinkのタスクID、モデルID、正規化したパラメータ、顧客/ワークスペースID、タイムスタンプ、納品状態を保存します。これにより、ワーカーが再起動しても再試行、監査、サポートが可能になります。

完了した結果を速やかにダウンロードする

H3 Maxの結果URLは24時間利用できます。合格した結果を永続ストレージにコピーし、チェックサムまたはオブジェクトキーを記録します。一時的なソースURLを恒久的な顧客アセットにしないでください。

再試行を明示的にする

ポーリングリクエストがタイムアウトしたからといって新しい生成を送信しないでください。まず保存したタスクIDを照会します。元のタスクが終端の失敗に達し、再試行ポリシーが課金される追加の試行を許可する場合にのみ、新しいタスクを作成します。

呼び出し前に互換性のないジョブをルーティングする

合格出力を測定する

追跡する項目：

• タスク成功率と完了レイテンシ；
• 初回合格率と再試行率；
• 合格クリップ単価；
• プロンプト、同一性、キーフレームへの追従；
• モデレーションと無効リクエストの比率；
• フォールバックの頻度と復旧率；
• URL失効前のダウンロード完了率。

よくある統合の間違い

リリース前チェックリスト

1. APIキーはサーバーサイドにあり、ローテーションできる。
2. T2VとI2Vは別々の検証スキーマを使う。
3. 長さ、画質、アスペクト比、画像の制限をローカルで強制する。
4. ワーカーが終了する前に作成レスポンスの id を保存する。
5. ポーリングは上限のあるバックオフを使い、再開できる。
6. コールバック処理は冪等で、ポーリングも利用可能なまま。
7. 完成したMP4ファイルを24時間以内にコピーする。
8. ログはリクエストエラー、タスク失敗、レビュー却下を区別する。
9. 価格はハードコードしたブログの値ではなく、現在のモデルページまたは価格サービスから取得する。
10. 互換性のないジョブや失敗したジョブに備えて、H3と独立したフォールバックを1つテストする。

よくある質問

EvoLinkでMiniMax H3 Maxが使うエンドポイントは？

どのモデルIDを使うべきですか？

H3 Max APIは同期的ですか？

4秒のH3 Max動画を生成できますか？

いいえ。対応する長さは5から15秒の整数です。EvoLinkで4秒の下限に対応するのはH3 MaxではなくMiniMax H3です。

終了フレームだけを使えますか？

はい。画像から動画のモデルは、開始フレームのみ、終了フレームのみ、開始・終了フレーム両方のリクエストを受け付けます。

Base64の画像を送れますか？

画像から動画はアスペクト比を受け付けますか？

送らないでください。出力は指定したフレームの比率に従います。想定する納品フォーマットに合わせてソースフレームを準備してください。

結果URLはどのくらい有効ですか？

24時間です。納品ワークフローの一部として、完成したMP4ファイルを永続ストレージにコピーしてください。

現在の価格はどこで確認できますか？

H3 Max製品ページのライブ価格セクションと見積もりツールを使ってください。ブログの料率を本番の予算にハードコードしないでください。

APIリファレンスと検証範囲

• EvoLink MiniMax H3 Max モデルページと現在のルート仕様
• EvoLink 非同期タスクステータスリファレンス
• MiniMax公式 Video Generation V2 ドキュメント