HiAPI 商品スポークスパーソンビデオは何をしますか？

ローカル CLI で 3～15 秒の単一ショット商品動画を作成します。有料リクエストの前に必ず --dry-run で見積もりを行ってください。ユーザーが明示的に生成を承認し、コマンドに --spend が含まれている場合にのみ有料タスクを作成します。

シナリオを選択する

以下のシナリオから正確に 1 つ選択します：

シナリオ	モデル	必須入力	P0 デフォルト
`synthetic-spokesperson`	`kling-3.0-omni/text-to-video`	プロンプトと任意のダイアログ	3秒、720p、9:16、音声あり
`talking-head`	`kling-3.0-omni/image-to-video`	許可済み人物画像 1 枚、プロンプト、ダイアログ、同意	3秒、720p、音声あり
`product-intro`	`seedance-2.0-fast`	プロンプトと商品画像 1～9 枚	4秒、480p、9:16、音声あり
`brand-promo`	`seedance-2.0-fast`	プロンプトとブランドまたは商品画像 1～9 枚	4秒、480p、9:16、音声あり

リクエストを作成する前に、ターゲットの尺を確認してください。ユーザーが指定しなかった場合は、動画の秒数を尋ね、サポート範囲（Kling: 3～15 秒、Seedance: 4～15 秒）を伝えてください。表の P0 デフォルトを提案しますが、ユーザーが尺を選択するか、デフォルトを明示的に承諾するまでは --dry-run に進まないでください。

ユーザーが許可を確認し、コマンドに --consent-confirmed が含まれている場合を除き、talking-head の生成を拒否してください。商品の主張、推薦、価格、認証、ブランドに関する事実を捏造しないでください。

支出と機密情報を保護する

最初にゼロコストのチェックを実行します：

node scripts/hiapi-product-spokesperson-video.mjs --check --env-file "D:\path\to\.env.local"

次に、意図したリクエストを --dry-run で実行します。公開価格見積もりがユーザーの制限内であることを確認してから、--dry-run を --spend に置き換えてください。デフォルトのクライアント側見積もり制限は $0.50 です。ユーザーが明示的に承認した予算内でのみ上書きしてください。1 回の呼び出しで作成する有料タスクは最大 1 つとします。

これは見積もりガードであり、サーバー側で強制される最終課金上限ではないものとみなしてください。HiAPI はタスクのプリチャージ時にアカウント固有のグループ比率を適用する場合があります。タスク API がサーバー側の最大コストフィールドをサポートするまで、この制限を有料生成前に開示し、ユーザーの総予算に対して十分な余裕を保ってください。

HIAPI_API_KEY はプロセス環境または --env-file から読み取ってください。キーをプレビュー、アーティファクト、マニフェスト、エラー、ログに出力、返却、永続化、または含めないでください。P0 では一時ストレージを使用します。

インストール後、.env.example を無視された .env にコピーするか、--env-file で既存の無視された環境ファイルを指定してください。入力されたファイルをコミットしないでください。埋め込み画像データとリモート画像 URL の両方をプレビューと保存されたリクエストアーティファクトから編集してください。

ローカルで実行する

支出なしで許可済みトーキングヘッドリクエストを見積もる：

node scripts/hiapi-product-spokesperson-video.mjs `
  --scenario talking-head `
  --image-file "D:\media\authorized-person.jpg" `
  --prompt "固定カメラ、自然なアイコンタクト、控えめな動き" `
  --dialogue "新製品、好評発売中。" `
  --consent-confirmed `
  --env-file "D:\path\to\.env.local" `
  --max-cost-usd 0.50 `
  --dry-run

synthetic-spokesperson の場合は、画像と同意オプションを省略します。商品およびブランドシナリオの場合は、--reference-image-file または --reference-image-url を繰り返します。ローカルの JPEG、PNG、WebP ファイルは data URI に変換され、それぞれ 20 MiB を超えてはなりません。

再支出せずに再開する

CLI は送信前に冪等性キーを出力し、タスク作成直後にタスク ID を出力します。タスク ID が返される前に送信が中断された場合は、同じ --idempotency-key で再試行してください。作成後にポーリングが中断された場合は、--task-id ID、--env-file、および希望する --output-dir のみを実行してください。これにより、元のリクエストを再構築または再送信することなく、ポーリングを再開し、既存の結果をダウンロードできます。

出力パッケージを保存する

--output-dir が指定されていない限り、各成功実行は outputs/ の下に書き込みます。以下を保存します：

final.mp4;
script.md と captions.srt;
埋め込みメディアとリモート画像 URL が編集された prompt.json;
シナリオ、モデル、タスク ID、ステータス、見積もり、リクエストハッシュ、ストレージ、タイムスタンプ、有効期限を含む manifest.json;
音声、リップシンク、一貫性、連続性、クレームの正確性について人間によるレビューが必要とマークされた qc.json。

ターミナルで成功したタスクと使用可能なローカル動画が得られない限り、成功を主張しないでください。

障害処理

HTTP 400、401、402、403 では再試行しないでください。
HTTP 409、429、503 の送信は、元の冪等性キーを使用して最大 3 回再試行してください。
--task-id でポーリングの中断を再開し、自動的に代替を送信しないでください。
品質障害後、別の有料実行の明示的な承認なしに再生成しないでください。
タスク ID、終了ステータス、見積もり、ローカル出力パス、保留中の人間による QC チェックを報告してください。

HiAPI 商品スポークスパーソンビデオ