はじめに
prompt に被写体、舞台、動作、希望する音を記載し、duration_seconds と解像度を選びます。seed で修正案を比較し、prompt_optimization_mode で指示文の書き換えを許可するか決められます。
| 項目 | 値 |
|---|---|
| 入力 | テキスト |
| 出力 | 動画 |
| 開発元とモデル | 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 | はい | 誰が登場し、何が動き、どこで撮り、どんな音が聞こえるかを説明します。具体的な動作とカメラの視点を示すと、返されたシーンを評価しやすくなります。 1 文字以上 · 32000 文字以内 |
aspect_ratio | いいえ | 送信前に、このエンドポイントで現在選べる画面比率から選択します。シーンの文章だけで比率を決めようとせず、掲載先に合わせて構図を計画してください。 |
resolution | いいえ | テキスト生成は 480p または 768p を選びます。480p のテストは 832×480 でした。 |
duration_seconds | いいえ | 5〜15 秒を指定します。テストの 5 秒指定ではフレーム単位の丸め後に 5.18〜5.26 秒となり、課金は出力 5 秒分でした。 |
prompt_optimization_mode | いいえ | 指示文の書き換えを避けるには disabled を設定します。turbo と quality はどちらもモデルによる書き換えを許可するため、prompt を比較するときはこの選択を固定してください。 |
seed | いいえ | seed を固定し、シーンの細部を 1 つずつ変えると比較しやすくなります。seed が同じでも、同じ結果になる保証はありません。 |
料金
480p または 768p の表示単価で、指定した出力秒数ごとに課金します。フレーム単位の丸めで、課金対象となる指定尺が増えることはありません。
| 仕様 | 料金 |
|---|---|
| $0.03 / 秒 |
| $0.054 / 秒 |
ユースケース
撮影前にシーンを試す
日差しの入る工房で、キャンバス地のエプロンを着た 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 は、文章で描いたシーンを AAC ステレオ音声付きの 5〜15 秒の動画にし、480p または 768p で返します。画像ではなく prompt を使うエンドポイントなので、写真や映像がまだない段階のコンセプトショットに使えます。
シーンのリクエストを送信する
この JSON を https://api.spicyapi.ai/api/v1/jobs/createTask に POST し、heygen/video-1/text-to-video を呼び出します。Authorization: Bearer YOUR_SPICY_API_KEY と Content-Type: application/json を付けてください。以下のシーンはリクエストの提案で、実測テストを再現したものではありません。
{
"model": "heygen/video-1/text-to-video",
"input": {
"prompt": "A potter in their thirties, wearing a blue work shirt, turns toward a shelf in a sunlit studio. Static medium shot, warm side light, thoughtful mood. Sound: quiet studio ambience, no music.",
"duration_seconds": 5,
"resolution": "480p",
"prompt_optimization_mode": "disabled",
"seed": 42
}
}
タスクのレスポンスを取得する
送信時のレスポンスから data.taskId を読み取り、Bearer キーを付けて GET /api/v1/jobs/recordInfo?taskId=YOUR_TASK_ID を照会します。成功すると、生成ファイルの URL が返ります。以下の例は関係のないフィールドを省略し、ID と URL を仮の値にしています。
{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_text_example",
"state": "queued"
}
}
{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_text_example",
"state": "succeeded",
"output": {
"assets": [{"url": "https://example.com/generated-scene.mp4"}]
}
}
}
完全なリクエストとレスポンスの仕様はタスク API ガイドを参照してください。ファイルの URL を開き、映像と生成された音声を確認できます。
シーンの設定を選ぶ
以下の設定で長さ、画面サイズ、prompt の扱いを指定します。納品形式が決まっている場合は、現在の選択肢から画面比率を選んでください。
| パラメーター | 目的と対応する設定 |
|---|---|
prompt | 被写体、見える動作、舞台、光、希望する音を描写します |
duration_seconds | 出力を 5〜15 秒で指定します |
resolution | 480p または 768p を選びます。このエンドポイントに 1080p はありません |
aspect_ratio | 現在のエンドポイント設定で対応している画面比率を選びます |
prompt_optimization_mode | disabled、turbo、quality から選びます。後の 2 つは書き換えを許可します |
seed | prompt の修正を 1 つ比べる間は固定します。同じ出力を保証するものではありません |
まとまった 1 ショットを演出する
カメラの指示を加える前に、目に見える動作を 1 つ選び、舞台を明確にします。たとえば、短い動画に部屋の案内、しぐさ、場面転換を詰め込む代わりに、棚のほうを振り向く人物を描写します。
HeyGen の説明では、カメラ設定、照明、音の発生源を指示に含めることが推奨されています。まとまりのあるシーンを勧め、複雑な手の動きや画面内の長い文章には制限があるとしています。開発元の指針として捉え、自分の動画でも細部を確認してください。
- 人物、服装、場所、動作の順で指定します。
- 窓明かりのある固定のミディアムショットなど、具体的な画角を加えます。
- 希望する音を描写し、必要なら音楽なしと指定します。
- 他の設定を変える前に、同じ seed と書き換えモードで修正案を比較します。
実測結果を読み解く
ニュートラルなテキストテストでは 480p・5 秒を指定し、AAC ステレオ音声付きの 832×480・24 fps が返りました。この回の処理は約 10 秒でしたが、あらゆるシーンの標準的な完了時間を示すものではありません。
提供された各テストでは、5 秒の指定からフレーム単位に丸めた 5.18〜5.26 秒のファイルが生成されました。タイムライン上で正確な編集点が必要なら、ファイルの尺を調べ、エディターで切り詰めてください。
課金の単位を理解する
テキスト生成は、指定した出力の 1 秒ごとに、選んだ解像度の現在の表示単価で課金します。フレームの丸めで再生時間が少し増えても、5 秒の指定は出力 5 秒として数えます。構図を試すときは 480p を選び、その後で納品に必要な 768p を検討できます。これは制作手順の提案で、実測による画質の順位付けではありません。
制限を確認し、別のタスクを選ぶ
送信前に長さを 5〜15 秒に収め、480p または 768p を選んでください。入力エラーなら、フィールド名と解像度を表や現在のスキーマと照合します。タスクが失敗した場合は errorCode と errorMessage を調べ、未完了のタスクを完成動画として扱わないでください。
特定の写真で人物と構図を決めたい場合や、ネイティブの 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/text-to-video",
"input": {
"prompt": "A slow aerial shot drifting over a misty pine forest at sunrise",
"resolution": "768p",
"aspect_ratio": "16:9",
"duration_seconds": 5,
"prompt_optimization_mode": "disabled"
}
}'
# 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 リファレンスを参照してください。

