はじめに
image_url と、加えたい動きを説明する prompt を送ります。480p、1080p、2k の写真テストでは元の人物と構図を維持しました。納品サイズに合わせてネイティブ解像度を選んでください。
| 項目 | 値 |
|---|---|
| 入力 | 画像 |
| 出力 | 動画 |
| 開発元とモデル | 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 文字以内 |
image_url | はい | 動かしたい人物と構図の元写真を指定します。動きを説明する前に、目的のショットに合うフレーミングになっているか確かめてください。 |
resolution | いいえ | 480p、768p、1080p、または小文字の 2k を選びます。テストの出力サイズは、480p が 832×480、1080p が 1890×1080、2k が 2688×1536 でした。 |
duration_seconds | いいえ | 希望尺は 5〜15 秒に設定します。フレーム単位の丸めでファイルが少し長くなっても、課金単位は指定した尺に従います。 |
prompt_optimization_mode | いいえ | disabled は指示文の書き換えを避け、turbo または quality は書き換えを許可します。解像度を変える前に、モードを固定した状態で動きを比べてください。 |
seed | いいえ | seed を固定すると、動作の prompt を 1 か所ずつ変えて評価できます。比較の補助であり、返される動画が同一になる保証ではありません。 |
料金
選んだネイティブ解像度の表示単価で、指定した出力秒数ごとに課金します。フレームの丸めで増えた再生時間は、課金する出力秒数に加算しません。
| 仕様 | 料金 |
|---|---|
| $0.03 / 秒 |
| $0.054 / 秒 |
| $0.144 / 秒 |
| $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 は入力写真を 5〜15 秒の動画にし、ネイティブ解像度で 480p、768p、1080p、2k を選べます。画像テストでは元の人物と構図を保ちました。写真ですでにショットが決まっている場合に、試し始めやすいエンドポイントです。
写真と動きの指示を送る
以下の JSON を https://api.spicyapi.ai/api/v1/jobs/createTask に送り、heygen/video-1/image-to-video を指定します。Authorization: Bearer YOUR_SPICY_API_KEY と Content-Type: application/json を付け、写真の URL を自分の画像に置き換えてください。
{
"model": "heygen/video-1/image-to-video",
"input": {
"image_url": "https://example.com/portrait.jpg",
"prompt": "The woman in her thirties in the supplied portrait, wearing a cream blouse, turns gently toward the window. Retain the source person and composition, soft morning light, calm mood, static camera.",
"duration_seconds": 5,
"resolution": "1080p",
"prompt_optimization_mode": "disabled",
"seed": 7
}
}
このサンプルはポートレートを動かす提案で、追加のテスト結果ではありません。利用する権利のある写真と肖像を使います。
返された動画を取得する
送信するとタスク ID が返ります。GET /api/v1/jobs/recordInfo?taskId=YOUR_TASK_ID で結果を取得してください。以下の省略したレスポンス例は、関係するフィールドに説明用の値を入れたもので、新たな実行結果ではありません。
{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_photo_example",
"state": "queued"
}
}
{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_photo_example",
"state": "succeeded",
"output": {
"assets": [{"url": "https://example.com/animated-portrait.mp4"}]
}
}
}
完全な構造は SpicyAPI のタスク資料にあります。返されたファイルを保存し、動いている人物とフレーミングを入力写真と比べてください。
アニメーションのパラメーターを設定する
prompt とともに image_url を渡し、長さとネイティブ解像度を選びます。以下の設定は、入力する写真と、モデルに加えさせたい動きを明確に分けています。
| パラメーター | 指定する内容 |
|---|---|
image_url | 人物と構図を決める元写真です |
prompt | 動作、カメラの動き、照明、シーンの演出です |
duration_seconds | 希望する出力尺を 5〜15 秒で指定します |
resolution | 480p、768p、1080p、2k から選びます。JSON では小文字の 2k を使います |
prompt_optimization_mode | disabled は書き換えを避け、turbo と quality は許可します |
seed | 修正案を比較するための設定です。同一の結果を約束するものではありません |
写真で決まっている要素を保つ
シーン全体を文章で作り直すよりも、元のポーズからの小さな変化を記載します。振り向きや視線の移動なら、人物と構図を静止画に照らし合わせながら、動作を明確に判断できます。
HeyGen の説明では、画像から動画は入力画像から始まります。prompt のガイドは控えめなカメラの動きと、しぐさの接触点を明示することを推奨しています。これらは開発元の説明です。ここでの実測の根拠は、提供されたテストに記録された写真との連続性と、ネイティブの出力サイズです。
- 残したい人物と舞台が写る写真を選びます。
- 動きの指示を 1 つ書き、重視する視覚要素を伝えます。
- 480p の試行で人物の見た目と動作を確かめます。
- シーンの演出が目的に合ったら 1080p または 2k を試し、比較のため seed を固定します。
出力サイズの実測を比べる
5 秒の写真テストでは、指定したネイティブ解像度で出力され、元の人物が保たれました。以下はテストした写真の構図における測定値であり、どの写真にも共通のピクセル数を示すものではありません。
| 指定した解像度 | 実測した出力 |
|---|---|
480p | 832×480 |
1080p | 1890×1080 |
2k | 2688×1536 |
768p も対応していますが、その解像度の画像テストのサイズは記録がありません。画像から動画への処理時間も測定していないため、テキスト生成の約 10 秒をこのエンドポイントの所要時間の目安にしないでください。
課金を見積もり、尺を確認する
写真のアニメーションは、選んだ解像度のこのページの表示単価で、指定した出力秒数に課金します。各テストの 5 秒指定ファイルは、フレーム単位の丸めにより 5.18〜5.26 秒でしたが、課金対象の出力尺は 5 秒のままでした。ピクセル数を増やすのは納品サイズへの対応です。再生成を決める前に、動作は別に確認してください。
入力の問題と別の選択肢を確認する
リクエストが拒否された場合は image_url、prompt、解像度の綴りを確認します。長さを 5〜15 秒に収め、該当の解像度には 2k を使ってください。フィールドを変える前に、現在のスキーマと返されたタスクエラーを参照します。タスクが成功していても、大事なしぐさが変わった場合は映像の確認が必要です。
元写真を使わず、文章からシーンを作りたい場合はテキストから動画を選びます。ポートレートと商品に別々の役割を与えるなら参照から動画を使えますが、動画入力が人物の同一性に強く影響する場合があります。写真を話すアバターにしたい場合は HeyGen Avatar IV を検討してください。
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/image-to-video",
"input": {
"duration_seconds": 5,
"image_url": "https://example.com/reference.png",
"prompt": "A slow aerial shot drifting over a misty pine forest at sunrise",
"prompt_optimization_mode": "disabled",
"resolution": "768p"
}
}'
# 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 リファレンスを参照してください。

