Skip to main content
POST
Image-to-video: submit a generation task from a reference image
右側のインタラクティブなプレイグラウンドは、ライブデバッグをサポートしています。Authorization に API Key を入力し(形式 Bearer sk-xxx)、参照画像をアップロードして、prompt を入力し、model / seconds / resolution を選択してから送信してください。Default グループで動作します — 専用のグループ切り替えは不要です
範囲: このページでは「参照画像から動画を生成する」方法を扱います。1 枚の画像を視覚的なアンカー / 開始フレームとしてアップロードし、静止コンテンツをアニメーション化します。参照画像が不要な場合は、テキストから動画のエンドポイント を使用してください(同じエンドポイント、JSON ボディ)。
⚠️ 画像から動画への制約
  • Content-Type は multipart/form-data でなければなりません(JSON ではありません)
  • サポートされる参照画像は 1 枚のみです。フィールド名は input_reference に固定されています。複数画像を送信しても、最初の 1 枚だけが保持されます
  • リモート URL は受け付けられません。ファイルアップロードまたは Base64 が必要です
  • 対応形式: image/jpeg / image/png / image/webp
  • 長さフィールド名は seconds です(duration ではありません)。また、文字列 "4" / "6" / "8" でなければなりません。これを duration として指定すると静かに無視され、デフォルトの 4 秒にフォールバックします。数値を渡すと失敗します
  • 1080p / 4k では、seconds"8" でなければなりません
Google の upstream Veo 3.1 は multi-reference / first-last-frame / video extension をサポートしていますが、この公式チャネルではまだそれらは公開されていません。first/last frame には、VEO 3.1 (Reverse) -fl シリーズを使用してください。

コードサンプル

Python (OpenAI SDK · ローレベル client.post)

Python(requests + マルチパート)

cURL (マルチパートアップロード)

Node.js(ネイティブ fetch + FormData)

ブラウザ JavaScript(file input アップロード)

task_id をすでにお持ちですか? 2つのコピペ用cURLコマンド

すでに task_id をお持ちの場合(タスクを送信したときに返されるか、コンソールログに表示されます)、下の 2 つのプレースホルダーを置き換えて実行してください:
  • sk-your-api-key → あなたの APIYI キー
  • task_xxxxxxxxxxxxxxxx → あなたのタスク ID

1. タスクステータスを確認

JSON 応答に status: "completed" と表示されたらダウンロードできます。in_progress と表示された場合は、数秒待ってからもう一度確認してください。

2. 動画をダウンロード(output.mp4 として保存されます)

/content エンドポイントには Authorization ヘッダーが必要です — URL をブラウザのアドレスバーに直接開くと 401 が返ります。--retry 3 は、statuscompleted に切り替わった直後にまれに発生する 400 をカバーしています(CDN の同期遅延)。

パラメータ参照

JSONモードとのフィールド名の違い:
  • JSONモードでは metadata.* の下にネストされます(例: metadata.resolution
  • マルチパートモードではフォームフィールドとしてフラットになります(resolution / aspectRatio / seed を直接指定)
  • 上のコードサンプルはすでにマルチパートの慣例を使っています
よくあるミス:
  • input_reference を JSON ボディ内で Base64 文字列として送信する — マルチパートのファイルフィールドを使う必要があります
  • フィールド名を image / reference / input_image にする — 正確に input_reference である必要があります
  • 画像を2枚送る — サーバーは最初の1枚しか保持せず、2枚目は黙って破棄されます
  • リモートURL(https://cdn.../img.png)を送る — 受け付けません。ファイルまたは Base64 である必要があります

レスポンス形式

レスポンス構造は テキストから動画 と同じです。ステップ 1 では task_id + status: "queued" を返し、ステップ 2 のポーリングでは status + 大まかな progress を返し、ステップ 3 では /content から MP4 バイナリをダウンロードします。
⚠️ レスポンスフィールドの注意点
  • task_idid と一致します。下流側は task_id に統一してください
  • video_url フィールドはありません; GET /v1/videos/{task_id}/content からダウンロードしてください
  • progress は 0 / 50 / 100 の間だけで変化し、線形ではありません
  • /contentstatuscompleted に切り替わった直後に 400 を返すことがあります。4秒後に再試行してください
  • 画像から動画へのタスクは、対応するテキストから動画タスクより通常 10–30% 長くかかります(画像エンコードの追加ステップのため)
このエンドポイントは非同期タスクのエントリです。課金は、タスクが completed に達した時点で発生し、モデル名ごとにリクエスト単位で課金されますinput_reference が指定されているかどうかにかかわらず適用されます。高速 $0.3 / 標準 $1.2)。POST 送信、ポーリング、ダウンロード自体は 課金されません。失敗したタスクも 課金されません

承認

Authorization
string
header
必須

API Key from APIYI console (Default group + Pay-per-request or Pay-as-you-go Priority Token; pure Pay-as-you-go not supported)

ボディ

multipart/form-data
model
enum<string>
デフォルト:veo-3.1-fast-generate-preview
必須

Model ID (per-request billing):

  • veo-3.1-fast-generate-preview — $0.3/request
  • veo-3.1-generate-preview — $1.2/request
利用可能なオプション:
veo-3.1-fast-generate-preview,
veo-3.1-generate-preview
prompt
string
必須

Video generation prompt. Focus on how the scene should animate: camera motion, object action, lighting, audio atmosphere. Do not pass generateAudio — audio intent goes in the prompt.

:

"Camera slowly rises from the base of the lighthouse to the top, dusk lighting, waves lapping the rocks"

input_reference
file
必須

Reference image file. Field name is fixed as input_reference, only 1 image supported.

Accepted formats: image/jpeg / image/png / image/webp. Remote URLs not accepted — must be a file upload or Base64.

seconds
enum<string>
デフォルト:8

Video length. The field name is seconds (not duration), a string enum: "4" / "6" / "8". Sending duration is silently ignored and falls back to the default 4 sec. Must be "8" at 1080p / 4k.

利用可能なオプション:
4,
6,
8
size
enum<string>
デフォルト:1280x720

Output pixel dimensions; lower precedence than resolution

利用可能なオプション:
1280x720,
720x1280,
1920x1080,
1080x1920,
3840x2160,
2160x3840
resolution
enum<string>
デフォルト:720p

Resolution tier (multipart mode flattens this as a top-level form field; higher precedence than size)

利用可能なオプション:
720p,
1080p,
4k
aspectRatio
enum<string>
デフォルト:16:9

Aspect ratio: 16:9 landscape (default) or 9:16 portrait

利用可能なオプション:
16:9,
9:16
seed
string

Random seed (multipart form field; string-encoded number is fine). Fixed seed clusters outputs in style but does not byte-reproduce.

:

"20260521"

negativePrompt
string

Negative prompt; recommended "blurry, watermark, distorted, low quality"

:

"blurry, watermark, distorted, low quality"

レスポンス

Task submitted; returns task_id and queued status

id
string

Task ID (matches task_id; downstream should standardize on task_id)

:

"task_xxxxxxxxxxxxxxxx"

task_id
string

Task ID for subsequent polling and download

:

"task_xxxxxxxxxxxxxxxx"

object
string

Object type, fixed to video

:

"video"

model
string

Model ID used for this task

:

"veo-3.1-fast-generate-preview"

status
enum<string>

Task status:

  • queued — submitted, awaiting processing
  • in_progress — generating
  • completed — done, downloadable (/v1/videos/{task_id}/content)
  • failed — failed (not billed), retry possible
利用可能なオプション:
queued,
in_progress,
completed,
failed
:

"queued"

progress
integer

Generation progress (coarse-grained, jumps only between 0 / 50 / 100)

:

0

created_at
integer

Task creation Unix timestamp (seconds)

:

1775025000

completed_at
integer

Task completion Unix timestamp (seconds); only present for completed status

:

1775025090