1つの明確な製品画像、Claude Code、AIHubMix APIを使用することで、Seedreamでキャラクターリファレンスを生成し、それらをバーチャルパーソンアセットとして登録し、Seedanceを使用してAI製品広告を作成できます。
このチュートリアルは実際のアロエミストキャンペーンに基づいており、プロジェクト構造、設定、コマンド、完全なビデオプロンプトが含まれています。ターゲット出力は、 20秒、720p、9:16の縦型広告 で、AI生成の人物と設定を持っています。
Claude CodeとAIHubMixがフルワークフローを支えています。Claude Codeはプロジェクトブリーフを読み、プロンプトを修正し、実行を整理します。AIHubMixは、同じプロジェクト内で画像とビデオ生成が動作できるように、1つのモデルエントリポイントを提供します。
モデルID、パラメータ、エラーハンドリングは2026年9月16日付のプロジェクトスナップショットから取得されます。再利用する前に現在のAPIを確認してください。コマンドは含まれている flow.py を使用し、プロジェクトルートから実行する必要があります。完全なスターターをダウンロード
コード、プロンプト、設定、サンプル画像をダウンロード
解凍後、 seedance-starter ディレクトリに入ります。このパッケージには flow.py 、2つのスキーマスナップショット、5つのプロンプトファイル、製品画像、3つのリファレンス画像が含まれています。Pythonスクリプトは標準ライブラリのみを使用します。
- ビデオステージから始める: 含まれている3つのリファレンスを使用し、キーを設定し、ステップ4から始めます。
- 自分の製品から始める: 製品画像とプロンプトの詳細を置き換え、含まれているリファレンス画像を
assets/から移動し、ステップ3から始めます。
.env.example を .env にコピーし、自分のAPIキーを追加します。アカウントは関連するモデルへのアクセス、必要な非同期タスクの権限、および十分なクォータが必要です。API生成には使用料金が発生します。
1. 製品画像とプロジェクトの準備
例の製品はNature Republic Aloe Vera Mistです。ワークフローを適応させる際は、画像、製品説明、使用アクションを更新してください。
| ファイル | 目的 |
|---|---|
assets/product.png | 元の製品画像 |
prompts/prompt-a.txt | メインキャラクターのポートレートプロンプト |
prompts/prompt-b.txt | 製品を持つキャラクタープロンプト |
prompts/prompt-c.txt | 製品使用プロンプト |
prompts/prompt-video.txt | ビデオのタイムライン、カメラ、音声要件 |
prompts.json | 寸法、持続時間、リファレンス依存関係、プロンプトパス |
flow.py | APIリクエスト、アセット登録、ポーリング、ダウンロード |
seedream.schema.json, seedance.schema.json | キャッシュされたAPIスキーマスナップショット |
Claude Codeはプロジェクトブリーフを読み、設定とプロンプトを修正するのに役立ちます。 flow.py は実際のリクエストをAIHubMixを通じて送信します。
なぜAIHubMixがこのワークフローに適しているのか
AI製品広告のワークフローは通常、1つ以上のモデルを必要とします。画像モデルは人物と製品リファレンスを作成し、ビデオモデルは動きとカメラの動作を作成します。AIHubMixはほとんどの主流モデルをカバーしているため、各プロバイダーのために別々のアカウント、認証、およびリクエストエントリポイントを維持するのではなく、1つのAPIサービスを通じてタスクごとにモデルを選択できます。
AIHubMixは複数のサプライヤーにも接続し、利用可能な低遅延ルートを自動的に選択します。これにより、画像生成、アセット処理、ビデオ生成を順番に完了しなければならないワークフローに対する単一のサプライヤーの不安定性の影響を軽減できます。モデルの可用性、ルーティング、応答時間は、依然として現在のサービス条件に依存します。
プロジェクトルートに .env を作成するか、環境内で同じ変数を提供します:
AIHUBMIX_API_KEY=replace_with_your_api_key
プロジェクトは .gitignore を通じて .env を除外します。実際のキーを共有するのではなく、変数名と例のみを共有してください。
全体のワークフローは1つの明確な製品画像から始まります。
2. 出力ターゲットを設定し、画像とビデオのパラメータを分離する
prompts.json の関連部分は次のようになります。実際のファイルを編集する際は、既存の stills 配列と他のフィールドを保持してください。
{
"size": "1080x1920",
"aspect_ratio": "9:16",
"duration": 20,
"resolution": "720p",
"generate_audio": true,
"video_prompt_file": "prompts/prompt-video.txt"
}
size は画像生成に属します。 aspect_ratio 、 duration 、 resolution 、および generate_audio はビデオ生成に属します。スクリプトは、全体の設定オブジェクトを両方のエンドポイントに送信するのではなく、別々のリクエストを構築します。
プロジェクトは次のモデルIDを使用します:
- Seedream:
doubao-seedream-5-0-pro-260628 - Seedance:
doubao-seedance-2-5-260628
バンドルされたスキーマスナップショットは、画像エンドポイントが size を受け入れるのに対し、ビデオエンドポイントが aspect_ratio を受け入れることを示しています。これらを混合すると拒否されます。 flow.py はリクエストを送信する前にキャッシュされたスキーマプロパティをチェックしますが、これは完全なパラメータ検証ではありません。
3. 順番に3つのキャラクタリファレンスを生成する
各画像には異なる役割があり、後の画像は前の画像に依存します:
| リファレンス | 内容 | 入力 |
|---|---|---|
| A: キャラクターポートレート | 顔、髪、衣装、部屋、照明を設定する | この例ではテキストプロンプトのみ |
| B: 製品を持つ | 同じ人物がボトルを持ち、ラベルがカメラに向いている | 製品画像 + A |
| C: 製品を使用する | 同じ人物がスプレーポンプを押す | 製品画像 + B |
プロンプトはキャラクターの詳細を繰り返し、製品の形状、色、ラベルのレイアウト、自然な取り扱いを説明します。
実行:
python3 flow.py stills
結果は assets/frame-01.jpg 、 frame-02.jpg 、および frame-03.jpg として保存されます。キャラクターの一貫性、パッケージの忠実度、使用アクションのリアリズムを確認してください。
スクリプトは既存のファイルをスキップします。 プロンプトを変更した場合は、バックアップを取り、対応する出力を移動してから再実行してください。Aを変更すると、BとCを再生成する必要がある場合もあります。
リファレンスはキャラクターのアイデンティティ、製品のプレゼンテーション、製品の使用を確立します。
4. 画像をホストし、バーチャルポートレートアセットを登録する
スターターには著者のアカウントからのアセットIDは含まれていません。リファレンスを自分のアカウントに登録してください。
このプロジェクトは、登録のために公開画像URLを使用します。ソースワークフローは、コミットSHAに固定されたGitHubの生URLを使用しましたが、認証なしで画像を直接返すホスティングであればどれでも機能します。
GitHubの /blob/ URLはHTMLページを返し、画像URLとして使用できません。
このプレースホルダーホストをアップロードしたファイルの実際の場所に置き換えます:
IMAGE_BASE='https://your-public-image-host.example/campaign'
python3 flow.py check "$IMAGE_BASE/frame-01.jpg" "$IMAGE_BASE/frame-02.jpg" "$IMAGE_BASE/frame-03.jpg"
python3 flow.py assets "$IMAGE_BASE/frame-01.jpg" "$IMAGE_BASE/frame-02.jpg" "$IMAGE_BASE/frame-03.jpg"
check はHTTP 200と画像のContent-Typeを確認します。 assets は virtual_portrait アセットグループを作成または再利用し、各画像を登録し、 active になるまで待機し、アセットIDを state.json に書き込みます。
このステップは、プロジェクト内での実際の失敗から来ています: フォトリアリスティックなキャラクターURLを直接ビデオエンドポイントに渡すと、 doubao_real_person_required が返されました。このキャンペーンの人物はAI生成されたため、 virtual_portrait が正しい分類でした。実際の人物の写真は、対応する検証プロセスに従う必要があり、バーチャルとしてラベル付けされてはいけません。
1つのビデオリクエストで使用されるすべてのアセットは、同じグループに属する必要があります。
リファレンスは生成され、すべての3つのアセットがアクティブであった; このスクリーンショットがキャプチャされたとき、ビデオタスクはまだ実行中でした。
5. カメラの制限を持つタイムラインとしてビデオプロンプトを書く
最終的なプロジェクトプロンプトは、1つの連続した20秒のショットを4つのフェーズに分けます:
| 時間 | キャラクターアクション | 製品の位置 |
|---|---|---|
| 0〜5秒 | カメラを見てボトルを提示する | 彼女の顔の横、ラベルがカメラに向いている |
| 5〜10秒 | ボトルを目の高さまで持ち上げ、ポンプを押す | フレーム内に留まる |
| 10〜15秒 | 目を閉じて霧が落ち着くのを感じる | フレームの下の三分の一に留まる |
| 15〜20秒 | 目を開けて再び製品を提示する | 彼女の顔の横に戻り、ラベルがカメラに向いている |
以前の結果ではカメラが近すぎて製品が見えなくなりました。したがって、最終プロンプトは移動を中近距離ショットに制限し、製品が見えるようにし、最初と最後の3秒間にラベルが読みやすいように要求します。
ここに完全な prompts/prompt-video.txt があります。他の製品の場合は、ブランド、パッケージの説明、使用アクションを更新してください。これらの指示は生成ターゲットであり、出力レビューが必要です。
One continuous 20-second vertical beauty commercial take, no cuts, in a sunlit minimalist vanity corner.
0-5s: the same 24-year-old East Asian woman in an oversized sage-green linen shirt over a white ribbed tank top stands at the vanity holding the translucent light-green Nature Republic Aloe Vera 92% Soothing Gel Mist beside her cheek, the label facing camera and fully legible. She looks to camera with a warm, easy smile and turns the bottle slightly so the label catches the morning light.
5-10s: she lifts the bottle just above eye level and presses the fine-mist pump. A soft cone of aloe mist sprays across her face and catches the light as a faint sparkle of micro-droplets.
10-15s: her eyes close and her chin lifts into a small contented smile as the mist settles, tiny droplets resting on her cheekbone and brow. The bottle stays visible in the lower third of the frame throughout this beat.
15-20s: she opens her eyes, brings the bottle back up beside her cheek with the label square to camera, and holds a final calm look at the lens.
Camera: one slow, smooth push-in from a chest-up framing to a mid-close framing ONLY. Do not push past a mid-close shot. The product must stay inside the frame for the entire take, and the label must be clearly legible in both the first three seconds and the last three seconds.
Look: soft diffused morning sunlight from camera left, photorealistic skin texture with real moisture on the skin, mist rendered as genuinely photographed spray rather than digital particles, premium K-beauty advertising. Keep the product packaging, colours, materials, label layout and label text exactly as in the reference images; do not redesign or re-letter the product. No text overlays, no captions, no watermarks.
Audio: a quiet bright room, one soft short pump-spray hiss, a gentle breath. No music, no voiceover.
音声生成は有効ですが、プロンプトは部屋のトーン、1つのスプレー音、穏やかな呼吸のみを要求しています—音楽やナレーションはありません。
6. ビデオを生成して保存する
アセット登録後、 asset:// リファレンスを提出します。このコマンドは保存されたIDを読み取り、各IDを別々の引数として渡します:
python3 - <<'PYCODE'
import json
import subprocess
import sys
from pathlib import Path
state = json.loads(Path("state.json").read_text())
refs = ["asset://" + asset_id for asset_id in state["asset_ids"]]
subprocess.run([sys.executable, "flow.py", "video", *refs], check=True)
PYCODE
引数リストを使用することで、ソースプロジェクトからのzshの問題を回避できます。複数のIDが1つのプレーンな文字列に保存されていると、スクリプトには無効な引数として到達する可能性があります。
スクリプトはビデオタスクIDを保存し、 completed になるまでポーリングし、出力を out/video.mp4 にダウンロードします。別のダウンロードがそのパスを上書きする可能性があるため、比較したいバージョンはバックアップしてください。
既存のタスクを再開するか、その結果を再ダウンロードするには:
python3 flow.py status
作成応答が失われた場合は、最近のタスクをリストし、関連するIDを再開します:
python3 flow.py tasks
python3 flow.py status VIDEO_TASK_ID
新しいタスクを作成する前に既存のタスクを探すことで、偶発的な重複生成を防ぎます。
7. 出力をレビューし、反復する
ソースプロジェクトは video-v1-10s.mp4 と最終的な video.mp4 を保持します。最初のバージョンはわずか10秒で、製品の使用が十分に示されていなかったため、ワークフローは2回目のプロンプト反復を経ました。
すべての結果をこのチェックリストに照らしてレビューしてください:
- [ ] 持続時間、解像度、アスペクト比がターゲットと一致している。
- [ ] キャラクターの顔、衣装、設定が一貫している。
- [ ] 製品が見え、ラベルが最初と最後に読める。
- [ ] 取り扱いとスプレーアクションが製品の実際の使用に一致している。
- [ ] ボトルの形状、パッケージング、テキストが目立って変わらない。
- [ ] カメラが近づきすぎず、音声がリクエストに一致している。
持続時間が間違っている場合は、設定と実際のリクエストの両方を確認してください。製品がフレームから外れる場合は、カメラの制限を強化します。使用アクションが短すぎる場合は、時間と動作をより明示的に割り当てます。 prompts/prompt-video.txt のみを編集する場合は、リファレンス画像を再生成する必要はありません。視覚的リファレンスを変更する必要がある場合のみ、再生成して登録してください。
よくある質問
なぜ正しく見えるモデル名が404を返すのか
短縮されたSeedream名は、ソースプロジェクトで model_not_found を返しました。マーケティング表示名がAPI識別子でもあると仮定するのではなく、現在のエンドポイントで受け入れられる完全なAPIモデルIDを使用してください。
なぜブラウザで画像を開けるのに、登録に失敗するのか
URLがHTML、共有ページ、またはサインインページではなく、画像自体を返すことを確認してください。登録の前に python3 flow.py check URL... を使用してください。
なぜプロンプトを変更してもリファレンス画像が変わらないのか
stills は既存のファイルをスキップします。再生成が必要な画像をバックアップして移動し、下流のリファレンスも再生成する必要があるか確認してください。
HTTP 200はビデオが終了したことを意味するのか
いいえ。スクリプトはタスクの status に分岐し、タスクが completed に達した後のみダウンロードします。
最初のバージョンを開始する
1つの製品画像を準備し、AIHubMixアクセスを設定し、画像とビデオモデルを選択します。その後、Claude Codeに製品説明とプロンプトを適応させます。3つのリファレンスを生成し、レビューして登録し、ビデオを作成し、チェックリストを使用して次の反復を決定します。
将来のプロジェクトで別のモデルが必要な場合は、同じファイル構造とワークフローを維持し、AIHubMixモデルの選択とモデル固有のパラメータを更新してください。これが、複数のAIモデルを使用するコンテンツチームにとって統一されたAPIサービスの実用的な価値です: モデルはタスクによって変更できますが、ワークフローは再利用可能なままです。
