はじめに
<Picture 1>、<Video 1>、<Audio 1> で素材の役割を割り当て、全種類合わせて 12 件以内に収めます。16:9 または 9:16 を選び、参照動画の動きや舞台の影響が強い場合は、人物の同一性を注意して確認してください。
| 項目 | 値 |
|---|---|
| 入力 | テキスト |
| 出力 | 動画 |
| 開発元とモデル | HeyGen — HeyGen Video 1.0、API 名 heygen-video-1 |
| 公開エンドポイント名 | heygen/video-1/text-to-video; heygen/video-1/image-to-video; heygen/video-1/reference-to-video |
| 指定できる尺 | 3 つのエンドポイントで 5〜15 秒 |
| テキスト生成の解像度 | 480p または 768p、AAC ステレオ音声付き |
| 写真のアニメーション解像度 | 480p、768p、1080p、2k のネイティブ解像度 |
| 画像入力時の出力サイズ実測 | 480p で 832×480、1080p で 1890×1080、2k で 2688×1536 |
| 参照生成の出力設定 | 480p または 768p、画面比率 16:9 または 9:16 |
| 参照入力の上限 | 合計 12 件まで。参照動画は合計 15 秒まで |
| プロンプトの書き換えモード | disabled, turbo, quality |
| ファイル尺の測定値 | 5 秒の指定から 5.18〜5.26 秒が返り、課金は指定した 5 秒分 |
| 課金単位 | 指定した出力秒数。参照動画の秒数も加算し、画像は 3 枚目から 1 枚ごとに追加課金 |
主な機能とハイライト
文章のシーンを動画にする
テキストから動画は、音声付きの 5〜15 秒のシーンを 480p または 768p で作ります。480p・5 秒の実測では、約 10 秒の処理で AAC ステレオ音声付きの 832×480・24 fps が返りました。これは 1 回の観測で、完了時間の約束ではありません。
元の人物を映像に引き継ぐ
画像から動画は image_url と動きの prompt で、入力写真を動かします。480p、1080p、2k のテストでは元の人物と構図を保ち、2k は 2688×1536 ピクセルでした。特定の写真との連続性が重要な場合に選ぶ入力方法です。
人物と物を別々に指定する
参照から動画では、画像、動画、音声を合計 12 件まで組み合わせられます。ポートレートとボトルの画像 2 枚のテストでは、その男性が指定のボトルを持つ縦型ショットが生成されました。別の混合参照では動画に強く従って写真の顔が失われたため、各入力の目的を明確にしてください。
設定を揃えてプロンプトを変える
seed と prompt_optimization_mode は修正案の比較に役立ちます。seed を固定して 1 つの変更を比べられますが、同一の結果を保証するものではありません。書き換えを避けるなら disabled、モデルに指示文を書き換えさせるなら turbo または quality を選びます。
リクエストパラメーター
| パラメーター | 必須 | 説明 |
|---|---|---|
prompt | はい | メディアのトークンで各参照を呼び、担う役割を示します。人物と商品の組み合わせなら、<Picture 1> の人物が <Picture 2> の物を持つと記載してください。 1 文字以上 · 32000 文字以内 |
reference_image_urls | いいえ | シーンに取り入れたい人物、物、舞台の画像を指定します。合計 12 件の枠に数え、3 枚目からは 1 枚ごとに追加課金します。 1 件以上 · 9 件以内 |
reference_video_urls | いいえ | 参照動画の長さは合計 15 秒以内にし、各動画を合計 12 件の枠に数えます。動画の秒数も課金対象です。 1 件以上 · 3 件以内 |
reference_audio_urls | いいえ | <Audio 1> などのトークンで音声の役割を指定し、利用する権利のある録音を使います。音声も合計 12 件の参照上限に含めます。 1 件以上 · 3 件以内 |
aspect_ratio | いいえ | 横長なら 16:9、縦長なら 9:16 を選びます。男性とボトルの参照テストでは 9:16 を使い、両方の画像を取り込みました。 |
resolution | いいえ | 参照生成で選べるのは 480p または 768p です。 |
duration_seconds | いいえ | 参照として渡す映像とは別に、出力を 5〜15 秒で指定します。課金は出力秒数と参照動画の秒数を合算します。 |
prompt_optimization_mode | いいえ | disabled は指示文の書き換えを避け、turbo と quality は許可します。各参照がシーンに与える影響を調べる間は、モードを固定してください。 |
seed | いいえ | 比較のために参照を追加・削除するときは seed を固定します。同じ seed でも動画が同一になるとは限らず、特定の顔を維持する保証もありません。 |
料金
表示単価で、指定した出力秒数と参照動画の秒数を合わせて課金します。参照画像は 2 枚まで含まれ、3 枚目からは 1 枚ごとに追加料金がかかります。
| 仕様 | 料金 |
|---|---|
| $0.102 / 秒 |
| $0.144 / 秒 |
ユースケース
撮影前にシーンを試す
日差しの入る工房で、キャンバス地のエプロンを着た 30 代の陶芸家が棚を振り向く場面を文章で送ります。480p・5 秒の指定で音声付きのコンセプト動画を作り、撮影前に確認できます。
小さなしぐさを加えたポートレート
窓辺でイブニングドレスを着た 30 代の女性の、利用許可のある写真を用意し、振り向きとゆっくりしたカメラの動きを指示します。画像から動画では、その写真を基に短いアニメーションが返ります。元画像と人物や構図を照合してください。
指定の商品を持つ出演者
男性のポートレートを <Picture 1>、スポイトボトルの写真を <Picture 2> として添え、その男性がボトルを持つ 9:16 のショットを依頼します。画像 2 枚のテストは両方の参照を使い、処理に約 158 秒かかりました。
動きを中心にしたコンセプト
ポートレート、4 秒の動作動画、参照音声を渡し、それぞれの役割を prompt に書きます。混合入力の実測では動画の動きと舞台に強く従い、写真の顔は保たれませんでした。顔より動きを重視する場合に検討する組み合わせです。
写真を基に大きなサイズで納品
元写真と控えめな動作の指示を組み合わせ、画像から動画で 1080p または 2k を選びます。5 秒のテストでは、元の人物を保ちながらネイティブの 1890×1080 と 2688×1536 が返りました。
プロンプトガイドと実践のヒント
入力に合うエンドポイントを選ぶ
文章のシーンにはテキストから動画、写真には画像から動画、複数の素材には参照から動画を選びます。1080p と 2k が必要なら写真のアニメーションで利用できます。
焦点を絞ったシーンの指示を作る
人物、服装、舞台、光、目に見える動作を 1 つ説明します。参照を使う場合は <Picture 1> や <Picture 2> で動作と素材を結び付け、利用する権利のある文章、声、肖像を使ってください。
動画生成タスクを送る
https://api.spicyapi.ai/api/v1/jobs/createTask に Bearer 認証で POST します。JSON の例は {"model":"heygen/video-1/text-to-video","input":{"prompt":"A potter in their thirties turns toward a shelf.","
duration_seconds":5,"resolution":"480p"}} です。動画を取得して見直す
data.taskId を保存し、GET /api/v1/jobs/recordInfo?taskId=YOUR_TASK_ID で結果を確認します。返された動画を見た後、seed を固定して修正を 1 つずつ試してください。同じ設定を繰り返しても、同じ結果になる保証はありません。
参照素材から動画を作る HeyGen Video 1.0 API
HeyGen Video 1.0 は、渡した画像、動画、音声の参照を組み合わせ、480p または 768p で 5〜15 秒のシーンを作ります。参照用エンドポイントは合計 12 件までの素材を受け付け、16:9 と 9:16 に対応します。参照動画の長さは合計 15 秒までです。
人物と商品を組み合わせて呼び出す
https://api.spicyapi.ai/api/v1/jobs/createTask への POST で heygen/video-1/reference-to-video を使います。Authorization: Bearer YOUR_SPICY_API_KEY と Content-Type: application/json を付け、仮の画像 URL を両方とも、利用する権利のある素材に置き換えてください。
{
"model": "heygen/video-1/reference-to-video",
"input": {
"prompt": "The man in his thirties from <Picture 1>, in a pale blue shirt, holds the dropper bottle from <Picture 2> beside his face in a softly lit bathroom. Vertical framing, static camera, warm light, composed mood.",
"reference_image_urls": [
"https://example.com/person.jpg",
"https://example.com/bottle.jpg"
],
"duration_seconds": 5,
"resolution": "480p",
"aspect_ratio": "9:16",
"prompt_optimization_mode": "disabled",
"seed": 21
}
}
この提案用リクエストはトークンの使い方を示す例で、実際のテスト時の送信内容ではありません。文章、声、肖像は許可のあるものを使い、実在の人物になりすますことは避けてください。
生成タスクの結果を読み取る
送信後に data.taskId を取得し、GET /api/v1/jobs/recordInfo?taskId=YOUR_TASK_ID でタスクを照会します。以下の省略した JSON は、待機中のタスクと成功時の結果を示します。ID とファイルのリンクは仮の値です。
{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_references_example",
"state": "queued"
}
}
{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_references_example",
"state": "succeeded",
"output": {
"assets": [{"url": "https://example.com/reference-scene.mp4"}]
}
}
}
連携の詳細にはタスクの完全な仕様を使ってください。成功したからといって各入力が等しく残ったと考えず、参照ごとに意図した役割が結果へ反映されたか確認します。
各参照に役割を与える
対応するトークンで各入力を呼び、ショットに何を加えるのか記載します。HeyGen の資料では、各メディアのリストごとに番号が付くと説明されています。画像は <Picture 1>、動画は <Video 1>、音声は <Audio 1> で指定します。
| パラメーター | 使い方と制限 |
|---|---|
prompt | 新しいシーンを描写し、渡した素材をトークンで指します |
reference_image_urls | 人物、商品、舞台の画像です。3 枚目からは各画像に追加料金がかかります |
reference_video_urls | 動きや舞台の参照で、合計 15 秒までです。その秒数も課金します |
reference_audio_urls | <Audio 1> などのトークンで役割を与える音声です |
| 全リストの合計 | 3 種類のメディアを合わせて参照素材 12 件までです |
duration_seconds | 希望する出力尺を 5〜15 秒で指定します |
resolution | 480p または 768p です |
aspect_ratio | 16:9 または 9:16 です |
prompt_optimization_mode | disabled、turbo、quality から選びます。後の 2 つは指示文を書き換える場合があります |
seed | 1 つの修正を比較する間は固定します。同じ映像の再生成を約束するものではありません |
2 つの参照テストから学ぶ
画像 2 枚のテストは男性とスポイトボトルの両方を使い、その男性がそのボトルを持つ 9:16 の結果になりました。処理に約 158 秒かかりましたが、これは実測した 1 回の結果で、参照生成サービスの目標時間ではありません。
混合参照のテストは動画に強く従い、画像の顔を引き継ぎませんでした。入力は画像 1 枚、4 秒の動画、音声でした。特定の写真の人物を重視するなら、影響の強い動作動画は避けてください。画像だけの参照や画像から動画なら、より焦点を絞った出発点として評価できます。
- 必ず映したい要素が人物と商品なら、その 2 枚の画像から始めます。
<Picture 1>と<Picture 2>で役割を明示します。- 動きや舞台が本当に必要な場合に動画を加え、もう一度顔を確認します。
- 変更を比較する間は seed と prompt の書き換え設定を揃えます。
参照素材の料金を数える
参照生成では、このページの表示単価で、指定した出力秒数と参照動画の秒数を合算して課金します。参照画像は 3 枚目から 1 枚ごとに料金が追加されます。5 秒の出力に 4 秒の参照動画を付ける場合は、両方の長さを見込んでください。参照映像が指定出力時間の代わりになるわけではありません。
提供された 5 秒のテストでは、フレーム単位の丸め後に 5.18〜5.26 秒のファイルが返りました。出力部分の課金は指定した 5 秒のままで、参照動画の利用分とは別に数えます。
問題を調べ、他のエンドポイントを選ぶ
参照リクエストを送る前に、合計件数、動画の長さ、出力設定を確認します。12 件を超える素材、15 秒を超える参照映像、16:9・9:16 以外の比率、768p を超える解像度は、このページの対応設定の範囲外です。結果がない理由を人物の同一性の問題と決めつけず、拒否や失敗時には返されたタスクエラーを調べてください。
特定の写真を動かす場合や、ネイティブの 1080p・2k を指定する場合は画像から動画を使います。参照が不要ならテキストから動画を使います。話す写真には HeyGen Avatar IV、翻訳には関連モデルの HeyGen Video Translate を検討してください。
API クイックスタート
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "heygen/video-1/reference-to-video",
"input": {
"aspect_ratio": "16:9",
"duration_seconds": 5,
"prompt": "A slow aerial shot drifting over a misty pine forest at sunrise",
"prompt_optimization_mode": "disabled",
"resolution": "768p",
"reference_image_urls": [
"https://example.com/reference.png"
]
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"
認証、完全なスキーマ、ポーリング、エラー処理は API リファレンスを参照してください。

