Vidu API ガイド：MoE モデルと Q シリーズへのアクセス

一言でまとめるなら：難しいプロンプトロジックには Vidu MoE、最終出力には Q3 Pro、低コストのテストには Q3 Turbo を、1 つの APIMart 設定を通じて使います。

すぐに実行できる手短な要点は次のとおりです：

• Vidu MoE、Vidu Q3 Pro、Vidu Q3 Turbo に、APIMart から 1 つの API キーと 1 つの主なリクエストフローでアクセスできます。
• 中核エンドポイントは POST https://api.apimart.ai/v1/videos/generations です。
• 動画ジョブは非同期なので、まず task_id を取得し、それから GET /v1/tasks/{task_id} をポーリングするか callback_url を使います。
• Vidu は次に対応します：
  • テキストから動画
  • 画像から動画
  • リファレンスベースの動画
  • 最初と最後のフレームのトランジション
• Q3 モデルは、対話・効果音・音楽のような内蔵音声を追加します。
• クリップは最大 16 秒まで実行でき、540p、720p、または 1080p の出力です。
• 記事の APIMart 料金は次のとおりです：
  • Q3 Pro： 720p で約 $0.12/秒
  • Q3 Turbo： 720p で約 $0.048/秒
• 出力リンクは 24 時間後に失効するため、成功後すぐにファイルをダウンロードすべきです。

クイック比較

私にとって際立つのは、切り替えがいかにシンプルかということです：ほとんどの場合、model フィールドを変えるだけで、残りの設定は同じに保ちます。それにより、この記事はセットアップ作業というより、コスト・待ち時間・出力品質に合わせて適切なモデルを選ぶことが主題になります。

Vidu モデル解説：MoE vs. Q シリーズ

Vidu の MoE モデル：何であり、いつ使うか

MoE（Mixture of Experts） モデルは、生成タスクの異なる部分を、動き・シーンの一貫性・プロンプト制御の専門エキスパートに振り分けます。生のスピードよりも一貫性が重要なマルチシーンや長いプロンプトで最も理にかなっています。

ただし、落とし穴があります。MoE は Q シリーズよりも多くの計算を要し、ターンアラウンドが遅いです ^[7]。シンプルなプロンプトには、たいてい必要以上です。

Vidu Q シリーズと Vidu Q3 Pro：本番利用のパフォーマンス

MoE がスペシャリストなら、Q シリーズは本番作業のために作られたオプションです。Vidu Q3 Pro は、仕上げられたシネマティック出力とストーリーボード駆動の動画向けに設計されています ^[7]。1080p 動画、最大 16 秒のクリップ、そして対話と効果音が同期した音声と動画の生成に対応します ^[1][2][4]。APIMart では、Q3 Pro は $0.12/秒から始まります ^[2][3]。

Vidu Q3 Turbo は、より速いシーン切り替えとともに、スピードと低コストの方に傾いています ^[6][7]。APIMart では、Q3 Turbo は $0.048/秒から始まります ^[3]。

ワークフローに合わせて MoE と Q シリーズの間で選ぶ方法

この選択は主に、プロンプトの複雑さ、ターンアラウンド時間、予算に帰着します。ワークフローが厳密な指示追従とマルチシーンロジックに依存するなら、MoE を選びます。音声と視覚の同期を伴う仕上げられた出力が必要なら、Q3 Pro がより適しています。あるいは、Kling V3 がシネマティックな AI 動画向けの別の高忠実度オプションを提供します。主な目標が高速イテレーションやクリップ単価の低さなら、Q3 Turbo が実用的な選択です。

下の表は、各モデルを最も得意とする作業の種類に対応づけています。ハイエンドのオプションを比較している方には、Sora 2 が同期音声を伴う同様のシネマティック機能を提供します。

次に、APIMart を通じてモデルを選択し、認証し、リクエストを送る方法を見ていきます。

APIMart を通じて Vidu にアクセスする方法

アカウント設定、認証、API キーの扱い

モデルを選んだら、1 つの API キーで APIMart を通じてジョブを送れます。まず、APIMart アカウントを作成し、ダッシュボードの API キー管理ページからキーを生成します ^[2][3]。

各リクエストを Authorization ヘッダーの Bearer トークンとともに送信します：

Authorization: Bearer YOUR_API_KEY

保管については、キーを環境変数や AWS Secrets Manager や GCP Secret Manager のようなシークレットマネージャーに保持します。開発、ステージング、本番に別々のキーを使うのも役立ちます。キーが露出したら、すぐにローテーションします。定期的なスケジュールでも同じことを行います。そしてリクエストをログに記録するときは、task_id だけを保存し、トークン自体は決して保存しないでください ^[5]。

APIMart で Vidu モデル、料金、入力スキーマを見つける

サインインしたら、何かを送る前にカタログを確認します。そこでモデル名、対応入力、現在の料金を確認できます。APIMart のカタログでは、Vidu モデルは Video Generation の下に掲載されています。同じカテゴリで MiniMax-Hailuo-02 のような他の高性能モデルも見つけられます。そのページを使って、MoE、Q3 Pro、Q3 Turbo にわたる入力スキーマ、解像度、秒単価を比較します ^[2][3]。

注目すべき主なフィールドは次のとおりです：

• model
• prompt
• duration
• resolution
• aspect_ratio

テキストから動画のジョブには aspect_ratio を使います。画像ベースのジョブでは、システムは代わりにソース画像の比率を使います ^[2]。テキストプロンプトは 2,000 文字に制限されています ^[2][3]。

エンドポイント、リクエスト構造、非同期ジョブ処理

モデルを選んだら、生成リクエストを送信し、返された task_id で非同期ジョブを追跡します。https://api.apimart.ai/v1/videos/generations に POST リクエストを送り、それから GET https://api.apimart.ai/v1/tasks/{task_id} でジョブステータスをポーリングします ^[2][5]。

ジョブは次の状態を経て進みます：

• submitted
• queueing
• processing
• success または failed

ジョブが完了したときに APIMart にアプリへ通知させたい場合は、callback_url を追加して Webhook で結果を受け取ります ^[5]。ジョブが成功に達したら、すぐにファイルをダウンロードします。そこから、リクエストフィールドをテキストから動画のフロー、またはリファレンスベースのフローのいずれかにマッピングできます。

テキストから動画とリファレンスベース動画のステップバイステップ統合

モデル選択を伴う基本的なテキストから動画のフロー

カタログからモデルを選んだら、テキストから動画のフローはかなりシンプルです。API キーをサーバー側から Authorization ヘッダーで Bearer {your_api_key} として送ります。

以下は viduq3-pro でのテキストから動画ジョブの最小限のペイロードです：

{
  "model": "viduq3-pro",
  "prompt": "A red fox running through a snowy forest at dusk, cinematic slow motion",
  "duration": 8,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "audio": true
}

レスポンスには task_id と、submitted、queueing、または processing のようなステータスが含まれます。その後、返された task_id で GET /v1/tasks/{task_id} をポーリングするか、リクエストに callback_url を渡して、ジョブが success または failed に達したときにプラットフォームがアプリに通知できるようにします ^[1][7][10]。viduq3-turbo に切り替えたい場合は、主に model フィールドを変えるだけです。

非同期パターンはモード間で同じままです。変わるのは入力フィールドです。

画像やリファレンス入力と高度な制御の追加

画像から動画では、image_urls 配列に画像 URL を 1 つ渡します。テキストから動画には 0 枚、画像から動画には 1 枚、最初と最後のフレームモードには 2 枚の画像を使います ^[2]。画像ベースのモードでは、出力アスペクト比はソース画像から来るため、aspect_ratio は省略できます ^[2]。URL の代わりにファイルを直接アップロードする場合は、各画像を PNG、JPEG、または WebP 形式で 50 MB 未満に保ち、HTTP ボディ全体を 20 MB 未満に保ちます ^[9][8]。

リファレンスベースの生成には、subjects 配列を伴う /reference2video エンドポイントを使います。各サブジェクトを name とその images で定義し、プロンプト内で @subjectname として呼び出します。Q3 モデルは subjects 機能で最大 7 枚のリファレンス画像またはテキスト説明を許可します ^[6]。最初と最後のフレームモードを使う場合は、失敗を減らすために両方の画像のアスペクト比を近く、理想的には 0.8 から 1.25 の比率内に保ちます ^[8]。顔や手が関わる場合は、歪みアーティファクトを減らすために動きのプロンプトを控えめに保ちます ^[5]。

下の表は、両フローにわたる主なパラメータを示します：

実行をまたいで同じ視覚結果が欲しい場合は、テスト中に固定の seed を設定します ^[2][9]。緊急でないバッチジョブには、off_peak を true に設定します。それらのタスクは通常 48 時間以内に完了し、より少ないクレジットを使います ^[1][6]。

使用量、コスト、本番の信頼性を追跡する

リクエストが動作したら、次の仕事は本番でコストと信頼性を管理し続けることです。

すべてのリクエストの task_id とタイムスタンプをログに記録します。それにより、機密の認証情報を保存せずに安全にデバッグできます ^[5]。キュー時間と生成時間を別々に追跡するのも役立ち、プラットフォームの遅延とモデルのレイテンシの違いを見分けられます。

コスト見積もりについては、APIMart で Vidu Q3 Pro は 720p で約 $0.12/秒、Q3 Turbo は約 $0.048/秒のコストです ^[3]。支出が手に負えなくならないよう、月間予算上限の 50%、80%、100% で自動アラートを設定します ^[5]。

リトライも重要です。5xx エラーでは、指数バックオフを使います：2 秒、次に 5 秒、次に 15 秒でリトライしてから、ユーザーにエラーを表示します ^[5]。Vidu Q3 シリーズのモデルは本番ワークロード向けに 99.9% の SLA を備えています ^[3] が、短命の失敗は依然として起こるため、リトライはあらゆる出荷ビルドの一部であるべきです。

モデル選択チェックリストと要点

開発者・クリエイター・プロダクトチーム向けユースケースチェックリスト

3 つのことに基づいて選びます：プロンプトの複雑さ、速度、出力品質。下の表は、モデル比較を実用的な出荷の選択に変えます。

行を選んだら、統合セクションと同じリクエストスキーマを保ちます。平たく言えば：アイデアを Q3 Turbo で始め、それから最終 1080p レンダリングを Q3 Pro に移します。シンプルなワークフローで、必要以上に支出せず高速に動くのに役立ちます。

動きの忠実度が最も重要なクリップでは、16 秒の最大まで引き伸ばすのではなく、5～10 秒を目指します。短いクリップはたいてい、より引き締まった動きと、より少ない悩みを与えます。

出荷前に覚えておくべき要点

MoE は複雑なマルチシーンロジックの選択です。Q3 Pro は高忠実度のシネマティック 1080p 出力を与えます ^[3]。Q3 Turbo は 720p で $0.048/秒の低コストオプションです ^[3]。

APIMart では、これらのモデル間の切り替えは単一の model パラメータの変更だけです。リクエスト内のそれ以外はすべて同じままです ^[3]。つまり、あるモデルをテストし、別のモデルに交換し、統合作業を安定させられます。

毎回同じ非同期フローを使います：

• リクエストを送信
• task_id を取得
• ステータスをポーリングするか callback_url を使う

また、生成された動画は準備でき次第すぐにダウンロードします。出力リンクは 24 時間後に失効します ^[3][11]。

よくある質問

どの Vidu モデルから始めるべきですか？

速度、音声、視覚制御のニーズに合うモデルから始めてください。

• viduq3-pro：音声と視覚の同期、ショット分割に最適
• viduq3-turbo：pro バージョンより速い生成
• viduq1 または viduq2：安定した動画制作と信頼できるカメラの動きに堅実な選択

送信後に動画ジョブをどう追跡しますか？

動画生成タスクは 2 つの方法で追跡できます。

本番利用では、最善のオプションは最初のリクエストに callback_url を含めることです。そうすると、Vidu API はタスクの更新と結果のメタデータをあなたの URL に自動で直接送ります。つまり、自分でタスクステータスを確認し続ける必要がありません。

もう 1 つのオプションは、送信後に得られる task_id でステータス照会 API をポーリングすることです。タスクの状態が success に変わると、レスポンスに動画ダウンロード URL とその他の関連メタデータが含まれます。

統合前に知っておくべき入力と制限は何ですか？

Vidu API を統合する前に、入力が次の制限内に収まることを確認してください：

• 画像：PNG、JPEG、JPG、または WebP のみ；各ファイルは 50 MB 未満で、少なくとも 128×128 ピクセル
• HTTP リクエストボディ全体：最大 20 MB
• テキストプロンプト：最大 5,000 文字
• ペイロードパススルーデータ：最大 1,048,576 文字

再生時間の制限は使うモデルによって異なります。Q3 は 1～16 秒、Q2 は 1～10 秒、Q1 は 5 秒に対応します。

また、API キーを安全に保ってください。クライアントサイドのコードで露出させないでください。代わりにサーバーサイドの仲介を通じてリクエストを送ります。