Higgsfield Generate は何をしますか？

任意の Higgsfield モデルにジョブを送信します。higgsfield CLI をラップします。汎用的な画像/動画生成とマーケティングスタジオ（ブランド広告、アバター、商品、フック、設定）をカバーします。

ステップ 0 — ブートストラップ

他のコマンドを実行する前に、CLI がインストールされ認証済みであることを確認してください：

higgsfield が $PATH 上にない場合、以下を実行してインストールします：
```
curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh
```
higgsfield account status が Session expired / Not authenticated で失敗した場合、ユーザーに higgsfield auth login（対話型、ブラウザが開きます）を実行するよう依頼し、確認が完了するのを待ってから続行してください。

higgsfield account status が既にアカウント情報を表示している場合は、どちらのチェックもスキップします。

UX ルール

簡潔に。生の ID や JSON ダンプをチャットに出力しないでください。準備ができたら結果 URL を表示します。
内部の専門用語は使用しないでください。「higgsfield を呼び出し中」、「ジョブをポーリング中」などとは説明しないでください。
最初のメッセージからユーザーの言語を検出し、その言語で返信してください。技術的な引数（--aspect_ratio 16:9 など）は英語のままにします。
一度に複数の質問をしないでください。適切なデフォルトモデルを選択し、本当に不足している場合にのみ一度に一つずつ質問してください。
コストを事前に見積もらないでください。ユーザーが尋ねない限り、単にジョブを送信してください。
generate create に --wait を渡して、コマンドが完了するまでブロックし、結果URL自体を出力するようにしてください。create → wait の2段階パターンは避けてください。

ワークフロー — 汎用生成

モデルを選択します。 実運用での実用的なデフォルト：

画像：
- ブランド商品ビジュアル（Pinterest ピン、ライフスタイル、ヒーローバナー、広告パック、バーチャル試着）→ 代わりに higgsfield-product-photoshoot を使用してください。このスキルは使いません。
- アバター + 商品を使ったブランド広告画像（マーケティングスタジオ形式）→ マーケティングスタジオ画像（以下のマーケティングスタジオを参照）
- 美しい UGC / ファッションエディトリアル / ライフスタイルキャラクター → Soul 2.0
- シネマティックな静止画 → Soul Cinema
- 特徴的なクリエイティブなペルソナ（テキストのみ、個性的） → Soul Cast
- ロケーション / 環境 / 人物なしのシーン → Soul Location（最高品質）
- ベクターイラストまたは顔編集 + 複雑なシーン置き換え → Seedream 4.5
- Soul Character（higgsfield-soul-id からの参照ID） → 静止画は Soul 2.0、シネマティックは Soul Cinema
- 高速で安価な反復 → Z Image
- キャラクターまたは漫画スタイルの作業 → Nano Banana 2；難しい場合は Nano Banana Pro にアップ
- その他すべてのデフォルト → GPT Image 2。 グラフィックデザイン、UI、バナー、タイポグラフィ、高忠実度の汎用生成。
動画：
- すべての広告 / 商用 / ブランド広告動画 → マーケティングスタジオ（以下のマーケティングスタジオを参照）
- デフォルトの汎用本格動画（マルチショット、一貫したアイデンティティ、モーション多用） → Seedance 2.0。 SOTA。
- 強いダイナミクスを必要としない単一平面シーン、Seedance 2.0 より安価 → Kling 3.0
- カットなしの安価できれいなショット → Seedance 1.5 Pro
- シネマグレードの最高忠実度 → Cinema Studio Video 3.0
- 安価で強い物理演算、オーディオ不要 → Minimax Hailuo
- 高速バッチ / 大量処理 → Veo 3.1 Lite
実際に higgsfield generate create に渡す --model ID については、higgsfield model list --json | jq を実行して表示名から ID にマッピングしてください。完全なテーブルについては references/model-catalog.md を参照してください。
メディア入力をフラグに直接渡します。 メディアフラグは、ローカルファイルパス または UUID を受け入れます。CLI はパスを自動的にアップロードし、UUID のジョブとアップロードを自動検出します。事前にアップロードする必要はありません。各モデルは、受け入れられるロール（image、start_image、end_image、video、audio）を宣言します — references/media-inputs.md を参照してください。
素早く検証します。 パラメータが不明な場合は、higgsfield model get <jst> --json を一度実行し、必要なものだけを渡してください。それ以外はスキーマのデフォルト値を使用します。サーバーは、重大でない補正（例：aspect_ratio=99:99 → 最も近い値）に対して adjustments を返し、無効な宣言済みパラメータ値に対しては構造化エラーを返します。
一度に送信して待機します。 higgsfield generate create <jst> --prompt "..." [メディアフラグ] [パラメータフラグ] --wait。端末のステータスになるまでブロックし、stdout に結果 URL を出力します。調整可能：--wait-timeout 20m（デフォルト10m）、--wait-interval 5s（デフォルト3s）。
結果を提供します。 URL と1行の概要（モデル、動画の場合は長さ）を送信します。

後で検査または再実行するには、higgsfield generate list --json および higgsfield generate get <id> --json が使用できます。higgsfield generate wait <id> は、--wait なしで開始されたジョブに再参加する必要がある場合に引き続き使用できます。

メディアフラグ

フラグ	使用目的	受け入れるモデル
`--image <パスまたはID>`	参照画像	ほとんどの画像モデル、`seedance_2_0`、`veo3`、`marketing_studio_video`
`--start-image <パスまたはID>`	画像から動画への遷移の最初のフレーム	`kling3_0`、`kling2_6`、`veo3_1`、`seedance_2_0`、`marketing_studio_video`
`--end-image <パスまたはID>`	遷移の最後のフレーム	`kling3_0`、`seedance_2_0`、`marketing_studio_video`
`--video <パスまたはID>`	参照動画	`seedance_2_0`
`--audio <パスまたはID>`	参照オーディオ（リップシンク、サウンドトラックマッチ）	`seedance_2_0`（これを使用し、`--generate-audio`は使用しないでください）

各フラグは、ローカルファイルパス（自動アップロード）または UUID（higgsfield upload create からのアップロードID、または以前のジョブID）のいずれかを受け入れます。各モデルは MEDIA_ROLES を介して独自のロールセットを宣言します。完全なテーブルについては references/media-inputs.md を参照してください。

共通パラメータ

フラグはモデルスキーマに渡されます。higgsfield model get <jst> を使用して確認してください。

higgsfield generate create gpt_image_2 --prompt "夕暮れのネオンシティ" --aspect_ratio 16:9 --resolution 2k --wait
higgsfield generate create nano_banana_2 --prompt "アニメキャラクターのコンセプト、表現豊かなポーズ" --image ./ref.png --wait
higgsfield generate create seedance_2_0 --prompt "カメラがドリーインする" --start-image ./first.png --duration 8 --wait
higgsfield generate create text2image_soul_v2 --prompt "..." --soul-id <soul_ref_id> --quality 2k --wait

機械可読な出力（チェーンされたパイプライン、エージェントコンテキスト）の場合は、--json を追加してください。--wait --json を使用すると、最終的なジョブオブジェクト配列が取得されます。--wait なしでは、ジョブIDが取得されます。

標準入力からのプロンプト：echo "..." | higgsfield generate create z_image --wait。

Soul 画像品質：text2image_soul_v2 および soul_cinematic の場合、--quality 1.5k または --quality 2k を渡してください。これらは UI 向けの階層であり、バックエンドはそれらを 720p/1080p および選択された --aspect_ratio に基づくモデル固有の寸法にマッピングします。soul_location には品質セレクターがありません。アスペクト比ごとに固定の寸法を使用します。

マーケティングスタジオ

ブランド画像/動画生成：アバター + 商品 + オプションのセットアップフック/設定 + 広告スタイルモード。モデル marketing_studio_video および marketing_studio_image を使用します。

概念

アバター — プレゼンターの顔。厳選された preset（higgsfield marketing-studio avatars list で参照）または custom（higgsfield marketing-studio avatars create でアップロードした写真）。UGC モードの場合、指示書に人物が明確に言及されている場合はアバターはオプションです。バックエンドが自動的に Soul Character を作成できます。ユーザーが特定のプレゼンターを望む場合はアバターを渡してください。
商品 — タイトルと参照画像を含むブランドアイテム。URL からインポート（higgsfield marketing-studio products fetch --url ...）またはアップロードした画像から作成（higgsfield marketing-studio products create）。
Web商品 — App Store / ウェブページバージョン。App Store URL を取得する際に自動ルーティングされます。
フック — 再利用可能なオープニングアングル / 広告フック。higgsfield marketing-studio hooks list で参照。フックテキストはユーザーのプロンプトの前に追加されます。--prompt を置き換えるものではありません。
設定 — 再利用可能な環境 / シーンコンテキスト。higgsfield marketing-studio settings list で参照。

検出コマンド

ユーザーが既存のものを尋ねた場合は、以下の正確な一覧表示コマンドを使用してください：

higgsfield marketing-studio avatars list --json
higgsfield marketing-studio products list --json
higgsfield marketing-studio hooks list --json
higgsfield marketing-studio settings list --json

--hook_id および --setting_id は marketing_studio_video のみでサポートされています。これらを marketing_studio_image に渡さないでください。

UX ルール（追加）

各フェーズで一度に一つの質問をしてください。商品+アバター+モードを一度に尋ねないでください。

ワークフロー — クイック広告動画

商品を取得します。
- 既存の商品 → higgsfield marketing-studio products list --json
- URL → higgsfield marketing-studio products fetch --url <url> --wait（インポートが完了するまでポーリング）
- ローカル画像 → higgsfield upload create <写真>... 次に higgsfield marketing-studio products create --title "..." --image <id>... 商品 ID を取得します。--hook_id を使用する場合は、強く --product_ids を渡すことを推奨します。フックは商品に焦点を当てるように設計されており、商品コンテキストなしではうまく機能しません。
必要に応じてアバターを選択します。
- デフォルト：higgsfield marketing-studio avatars list でブランドの声に合ったプリセットを選択します。
- カスタム：higgsfield marketing-studio avatars create --name "..." --image <アップロードID>。 UGC モードの場合、特定のプレゼンターが不要で指示書に人物が言及されている場合は、--avatars を省略しても構いません。バックエンドが Soul Character を合成できます。
オプションでセットアップ項目を選択します。
- フック：higgsfield marketing-studio hooks list --json
- 設定：higgsfield marketing-studio settings list --json 選択した ID を --hook_id <hook_id> および --setting_id <setting_id> として marketing_studio_video にのみ渡します。ユーザーが明示的に同じ文言を強調したい場合を除き、フックのプロンプトを --prompt にコピーしないでください。
必要に応じてモードを選択します。 デフォルトは ugc です。--hook_id が存在するからといって --mode が必須になるわけではありません。その他の現在のスラッグ：ugc_how_to、ugc_unboxing、product_showcase、product_review、tv_spot、wild_card、ugc_virtual_try_on、virtual_try_on。references/marketing-modes.md を参照してください。
生成（ワンショット）。
```
PRODUCT_IDS_JSON=$(mktemp)
AVATARS_JSON=$(mktemp)
printf '["<product_id>"]' > "$PRODUCT_IDS_JSON"
printf '[{"id":"<avatar_id>","type":"preset"}]' > "$AVATARS_JSON"

higgsfield generate create marketing_studio_video \
  --prompt "..." \
  --avatars @"$AVATARS_JSON" \
  --product_ids @"$PRODUCT_IDS_JSON" \
  --mode ugc \
  --duration 15 \
  --resolution 720p \
  --aspect_ratio 9:16 \
  --wait
```
セットアップのフック/設定が選択された場合は、--hook_id <hook_id> や --setting_id <setting_id> を追加します。 product_ids と avatars は JSON 配列です。@/path/to/file.json で渡してください。--product_ids にベア UUID を渡さないでください。解像度は 480p または 720p です。アスペクト比は auto/21:9/16:9/4:3/1:1/3:4/9:16 のいずれかです。ここでは --generate-audio true がサポートされています（seedance_2_0 とは異なります）。--wait は完了するまでブロックします。長時間の広告実行の場合は --wait-timeout 30m に引き上げてください。
結果を提供します。 URL + 1行の概要（モード、長さ）。

ワンクリック広告ショートカット（URL駆動）

ユーザーが商品 URL を提供し、一度にマーケティング動画を希望する場合：

# 1. フェッチをトリガー（商品IDを返し、バックグラウンドスクレイピングを開始）
higgsfield marketing-studio products fetch --url https://shop.example.com/sneakers --wait

# 2. 同じURLに対してマーケティング動画を生成 — バックエンドがエンティティを再利用
higgsfield generate create marketing_studio_video \
  --url https://shop.example.com/sneakers \
  --mode ugc \
  --duration 15 \
  --aspect_ratio 9:16 \
  --wait

バックエンドは URL で重複排除するため、繰り返し実行すると再フェッチせずに既存のエンティティを再利用します。

ワークフロー — マーケティング画像

上記と同様ですが、marketing_studio_image モデルを使用します：

higgsfield generate create marketing_studio_image \
  --prompt "..." \
  --aspect_ratio 1:1 \
  --resolution 2k \
  --wait

エラー

Missing required params: prompt → ユーザーがプロンプトを提供していません。尋ねてください。
Invalid values: aspect_ratio=99:99 (allowed: ...) → 無効な enum。許可されているものから選択してください。
Unknown params: foo → スキーマがそのフラグを受け入れません。higgsfield model get <jst> で確認してください。hook_id または setting_id でこれが発生した場合、選択されたモデル/ジョブセットタイプはマーケティングスタジオのセットアップ項目をサポートしていません。
Session expired → higgsfield auth login。

詳細については references/troubleshooting.md を参照してください。

リファレンスドキュメント

必要に応じて読み込んでください：

references/model-catalog.md — タスクに適したモデルの選択
references/prompt-engineering.md — 効果的なプロンプトの書き方
references/media-inputs.md — 画像/動画参照フロー
references/troubleshooting.md — よくあるエラーと解決策
references/marketing-avatars.md — プリセット vs カスタムアバター
references/marketing-products.md — URL フェッチ vs 手動商品作成
references/marketing-setup-items.md — フック/設定の検出と使用法
references/marketing-modes.md — すべてのマーケティングスタジオモード

Higgsfield Generate