何かを組み込む必要がなく、ただ動画が欲しいだけなら、開発作業は省略できます。私たちのスタジオは同じモデルを、アップロード時のバリデーション、ブラウザ録音、ストレージ、ダウンロード機能とあわせて提供しています。
OmniHuman 2 APIリクエストの中身
リクエストには必須フィールドが2つ、任意フィールドが1つあります。画像URLはアニメーションにする人物(複数人も可)を指し、音声URLはパフォーマンスを動かす話し声や歌を指します。任意のプロンプトでは、動き、雰囲気、シーンの詳細、カメラワークを指定します。結果は通常、キューを通じて非同期で返されます。リクエストを送るとリクエストIDが返り、ステータスをポーリングするか、動画の完成時にWebhookを受け取ります。
- image_url:必須。アニメーションにする静止画。
- audio_url:必須。長さとリップシンクを決めるMP3またはWAV。
- prompt:任意。英語、中国語、日本語、韓国語、スペイン語(メキシコ)、インドネシア語に対応。
最初にバリデーションすべき入力の制限
リクエストが拒否されると時間を無駄にし、場合によってはお金もかかるので、モデルを呼び出す前に自分の側でバリデーションしておきましょう。画像はJPEG、PNG、WEBP、BMP、TIFF、GIF、HEICなどの一般的な形式で、30MB以下、各辺300〜6000ピクセル、幅と高さの比率が0.4〜2.5である必要があります。音声はWAVまたはMP3で、15MB以下、長さは4〜300秒である必要があります。
ブラウザで録音した音声はたいていWebMやOpusで、モデルはこれらを受け付けません。アップロード前にWAVまたはMP3に変換してください。私たちのスタジオでは録音を22.05kHzモノラルのWAVに再エンコードしており、5分のクリップでもサイズ制限内に収まります。
出力と課金
完了したジョブは、動画ファイルのURLと課金対象の長さを返します。この長さは入力音声の長さと一致します。出力はネイティブ720pのMP4です。プロバイダーのURLは期限切れになることがあるため、本番システムではプロバイダーに直接リンクするのではなく、ジョブ完了後すぐにファイルを自前のストレージにコピーすべきです。
コストは生成した秒数に比例するので、音声の長さはサーバー側で計測しましょう。ブラウザから送られた長さは決して信用してはいけません。また、同時実行のジョブで残高を使いすぎないよう、送信前にコストを確保しておきましょう。
本番運用に耐えるフロー
このサイトですべての生成に使っているパターンです。
- 1非公開ストレージにアップロード短時間だけ有効な署名付きアップロードURLを発行し、ユーザーの写真への長期間有効な公開リンクは決して公開しません。
- 2サーバー側で検証課金の前に、音声の長さを計測し直し、両方のファイルが存在することを確認します。
- 3確保してから送信クレジットをアトミックに確保してジョブを送信し、送信に失敗したら自動で返金します。
- 4冪等に完了処理Webhookまたはポーリングで結果を取得し、MP4を保存して、ジョブの完了処理を一度だけ行います。
ノーコードのスタジオのほうが向いている場合
上記のパイプラインを構築するには、ストレージ、バリデーション、キュー、Webhook、リトライ、課金と、数日がかりの作業が必要です。目的が製品の機能ではなくコンテンツ制作なら、私たちのスタジオでそれらがすべて整った状態で、同じOmniHuman 2.0の出力が得られます。なお、当サービス自体は公開APIを提供していません。このサイトは完成した動画が欲しいクリエイターやマーケター向けに作られています。
失敗とリトライへの対処
すべてのジョブは失敗しうるものとして扱いましょう。プロバイダーが入力を拒否したり、高負荷でタイムアウトしたり、ダウンロードできない結果を返したりすることがあります。ジョブごとにステータス列(キュー待ち、実行中、完了、失敗)を持たせ、重複したWebhookで二重処理されないよう完了処理を冪等にし、失敗時には確保した残高を返金してください。
Webhookを使う場合でも、フォールバックとしてポーリングを併用しましょう。ローカルの開発マシンではWebhookを受け取れませんし、本番でもWebhookがときどき遅れることがあります。
- ユーザーにレスポンスを返す前に、プロバイダーのリクエストIDを保存する。
- 入力URLは、想定されるキュー待ち時間より長い有効期限で署名し直す。
- プロバイダーのエラーはそのままログに残す。超過した制限が具体的に書かれていることがほとんどです。
よくある質問
omnihuman2.aiは公開APIを提供していますか?
いいえ。当サービスはWebスタジオを通じてクリエイター向けにモデルを提供しています。開発者の方は、公式のモデルプロバイダー経由でOmniHuman 2を利用できます。
OmniHuman 2 APIの音声の最大長は?
300秒です。最小は4秒で、ファイルは15MB未満のMP3またはWAVである必要があります。
APIが返す動画の解像度は?
バージョン2.0はネイティブ720pで生成し、MP4ファイルを返します。
APIは同期型ですか?
基本的には違います。ジョブには数分かかるため、プロバイダーはポーリングやWebhookを使ったキュー方式を採用しています。
WebMの録音を送信できますか?
直接はできません。先にWAVまたはMP3に変換してください。ブラウザで録音した音声の多くは再エンコードが必要です。
利用料金はどのように課金されますか?
出力の秒数で課金され、これは入力音声の長さと同じです。
出力動画を自前のストレージにコピーすべきですか?
はい。プロバイダーの結果URLは期限切れになることがあるので、ジョブが完了したらすぐにMP4を自前のストレージにダウンロードしてください。
ジョブには通常どれくらいかかりますか?
クリップの長さとキューの混雑状況によります。私たちのテストでは約5秒のクリップが全体で約2分で完了したので、UIは秒単位ではなく分単位を想定して設計しましょう。