AIHubMixのリアルヒューマン・アセットでSeedance 2.5に実在の顔を使う方法

AI動画は、画面に映る人物が場面をまたいでも認識できる状態を保てると、はるかに役立ちます。AIHubMixのリアルヒューマン・アセットは、承諾に基づいた方法で承認済みの顔をSeedanceの動画生成に使えるようにしつつ、認可、アセットの処理、生成を、それぞれ検証可能な別個のステップとして扱います。

このガイドでは、リアルヒューマン動画とは何か、AIHubMixのワークフローの仕組み、その利点、そして実在の顔からSeedance 2.5の動画を作成する手順を説明します。また、ネイティブのSeedance 2.5 APIと、互換性のあるSeedance 2.0の連携との違いについても解説します。

リアルヒューマン動画とは

リアルヒューマン動画とは、認可を受けた人物を身元の参照として使うAI生成動画のことです。モデルは、人物の認識できる外見を保ったまま、背景、服装、動作、カメラの動き、音声、言語を変更できます。

これは一般的なテキストから動画を生成する方法とは異なります。テキストのプロンプトは何が起きるべきかを記述しますが、特定の実在の人物を確実に識別するものではありません。リアルヒューマン・アセットは、承認済みの視覚的な参照をモデルに与え、それを複数の動画で再利用できます。

代表的な用途には、クリエイターのアバター、バーチャルプレゼンター、製品の解説動画、地域ごとのキャンペーン、研修動画、ブランドのキャラクター、ショート動画向けのSNSコンテンツなどがあります。

AIHubMixワークフローの仕組み

ワークフローは主に5つの段階から成ります。

1人分のアセットグループを作成する。
画像内の人物に認可フローを完了してもらう。
ポートレートを追加し、アセットが有効になるまで待つ。
有効なアセットをasset://のURIで参照する。
Seedanceの動画タスクを送信し、完了するまでポーリングする。

この分離は意図的なものです。認可は生成の前に行われ、アセットの準備状態は独立して確認でき、重要な各段階はアプリケーションが監視できるステータスを示します。

なぜAIHubMixを使うのか

ワークフロー全体を1つのAPIで

AIHubMixは、アセットグループ、認証セッション、人物アセット、非同期の動画生成のためのエンドポイントを提供します。同じアカウントとAPIキーで、パイプライン全体を管理できます。

明示的な認可

ポートレートの人物が認可ページを完了します。これにより、画像を再利用可能なリアルヒューマン参照として使う前に、明確な承諾の手順が設けられます。

再利用可能な身元アセット

画像が有効になると、アプリケーションは毎回元の画像をアップロードする代わりに、そのアセットIDを複数の動画リクエストで再利用できます。

Seedanceに対応した生成

ネイティブのSeedance 2.5エンドポイントは、テキスト、画像、動画、音声の参照に対応し、長さ、解像度、アスペクト比、音声生成を制御できます。

監視しやすく、本番運用に適した状態

アプリケーションは、操作が完了したかどうかを推測するのではなく、verified、active、completedの状態を待つことができます。これにより、再試行やエラー処理を実装しやすくなります。

ステップごとのチュートリアル

ステップ1：APIキーとポートレートを準備する

AIHubMix ConsoleでAPIキーを作成します。キーは秘密に保管してください。ターミナルで環境変数として設定します。

export AIHUBMIX_API_KEY="your_api_key"

直接アクセスできるHTTPSの画像URLを用意します。このURLは、ログインやカスタムヘッダーなしで画像ファイルを返す必要があり、AIHubMixが処理している間も利用可能な状態を保たなければなりません。

推奨される画像の要件：

JPEG、PNG、WebP、BMP、TIFF、GIF、HEIC、HEIF
30 MB未満
幅と高さは300ピクセルより大きく、6000ピクセルより小さいこと
アスペクト比は0.4より大きく、2.5より小さいこと
認可を完了する本人がはっきり写っているポートレート

ステップ2：リアルヒューマン・アセットグループを作成する

ターミナルで次のコマンドを実行します。

curl -sS -X POST "https://aihubmix.com/ai/v1/asset-groups" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"My real-human asset"}'

ag_...の形式の、返されたidを保存します。

GROUP_ID="ag_your_group_id"

新しいグループは通常、pending_authの状態から始まります。

ステップ3：認可セッションを作成する

グループIDを使って認証セッションを要求します。

curl -sS -X POST \
  "https://aihubmix.com/ai/v1/asset-groups/$GROUP_ID/verification-sessions" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

レスポンスには一時的なverification_urlが含まれます。そのURLをブラウザで開き、ポートレートの人物に目的を確認してもらい、認可フローを完了してもらいます。

このURLは機密情報であり、一時的なものです。公開したり、リポジトリにコミットしたり、スクリーンショットに含めたりしないでください。

ステップ4：認可とグループの状態を確認する

人物がブラウザでの手順を終えたら、両方のリソースを照会します。

curl -sS "https://aihubmix.com/ai/v1/verification-sessions/$SESSION_ID" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

curl -sS "https://aihubmix.com/ai/v1/asset-groups/$GROUP_ID" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

認証セッションがverifiedになり、アセットグループがactiveになった場合にのみ先へ進みます。ブラウザのエラーページは最終的な結果を示さないため、APIのステータスを使用してください。

ステップ5：ポートレートを追加する

直接アクセスできる画像URLを送信します。

curl -sS -X POST \
  "https://aihubmix.com/ai/v1/asset-groups/$GROUP_ID/assets" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: portrait-001" \
  -d '{
    "url":"https://cdn.example.com/portrait.jpg",
    "asset_type":"image",
    "client_reference_id":"portrait-001"
  }'

返されたアセットIDを保存し、そのIDをポーリングします。

ASSET_ID="ast_your_asset_id"
curl -sS "https://aihubmix.com/ai/v1/assets/$ASSET_ID" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

アセットのステータスがactiveの場合にのみ使用します。creatingとprocessingは、まだ準備ができていないことを意味します。

ステップ6：Seedance 2.5の動画を生成する

リアルヒューマン・アセットはinput_references[].urlに指定します。プロンプトのテキストに貼り付けてはいけません。

curl -sS -X POST "https://aihubmix.com/ai/v1/videos" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\":\"doubao-seedance-2-5-260628\",
    \"prompt\":\"A realistic vertical vlog. The person smiles, waves, and says in Japanese: やっほー！今日も笑顔でね！ Keep the face consistent, synchronize lip movement, use natural hand motion, and add no subtitles.\",
    \"duration\":5,
    \"resolution\":\"720p\",
    \"aspect_ratio\":\"3:4\",
    \"generate_audio\":true,
    \"input_references\":[{\"type\":\"image_url\",\"url\":\"asset://$ASSET_ID\"}]
  }"

レスポンスで動画タスクIDが返されます。タスクがcompletedになるまでGET /ai/v1/videos/{id}をポーリングし、その後、動画のURLは一時的なものなので、速やかに出力をダウンロードしてください。

Seedance 2.5とSeedance 2.0

Seedance 2.5は、上記で説明したネイティブの/ai/v1/videosエンドポイントを使用します。従来の連携では、互換性のある/v1/videosプロトコルと異なるコンテンツ構造を使ってSeedance 2.0を利用している場合があります。

2つのリクエスト形式を混在させないでください。本番環境で使用する前に、対応する長さ、解像度、参照の種類、音声の動作、エンドポイントのパスについて、稼働中のモデルスキーマを確認してください。

プロンプトのベストプラクティス

環境、動作、タイミング、カメラの動き、音声、制約を記述します。例えば、着物、舞い散る桜の花びら、ゆるやかに手を振る動作、日本語の会話、口の動きの同期、自然な髪の揺れ、字幕なしと指定できます。

短い挨拶であれば5秒がよく機能します。動画に複数の動作や長い文章が含まれる場合は、より長い尺を使うか、台本を短くして、演技が急ぎすぎた印象にならないようにしてください。

簡単なテストでは、身元の参照は1つだけ使ってください。追加の参照は、モデルスキーマが対応しており、それぞれのアセットが同じアセットグループに属している場合にのみ加えてください。

よくある問題

グループが有効ではない：認証セッションがverifiedになり、グループがactiveになるまで待ってください。
アセットが処理中である：元のアセットIDをポーリングしてください。新しいIDで重複を作成しないでください。
画像URLが失敗する：ローカルパス、ログインページ、共有ページではなく、公開されているHTTPSのファイルURLを使用してください。
動画がアセットを拒否する：アセットがactiveであり、同じアカウントに属し、正しいメディアタイプを使用していることを確認してください。
Playgroundにasset://が表示されない：Playgroundでの画像アップロードとリアルヒューマン・アセットの登録は別のワークフローです。登録済みアセットにはAPIリファレンスのフィールドを使用してください。

最終チェックリスト

APIキーを安全に設定済みである。
アセットグループを作成済みである。
人物の認可が完了している。
グループのステータスがactiveである。
ポートレートのアセットのステータスがactiveである。
動画リクエストがasset://<asset_id>を使用している。
動画タスクがcompletedになるまでポーリングされている。

AIHubMixのリアルヒューマン・アセットは、開発者が、承諾に基づき、身元の一貫性を保った動画体験をSeedanceで構築するための実用的な方法を提供します。承認済みのポートレート1枚と短いテスト動画から始め、同じワークフローをクリエイター向けツール、ブランドコンテンツ、本番運用のアプリケーションへと広げてください。