aicentos 経由で Google Veo 動画生成モデルを呼び出す — テキストからの動画生成、画像からの動画生成、先頭・末尾フレーム、参照画像

この記事は開発者向けに、aicentos 経由で Google Veo 動画生成モデルを呼び出す方法を説明します。インターフェースは OpenAI 動画 API 互換形式（OpenAI Videos API）で、下流から接続する際はチャネルタイプに openai を指定するだけで済みます。

モデルの能力

課金は動画生成時間（秒）に基づきます。具体的な単価は aicentos コンソールの表示が優先され、最終的な課金はシステムの実際の課金記録に基づきます。

公式の能力と aicentos の公開範囲

モデル	対応秒数	対応解像度	アスペクト比	音声	説明
`veo-3.1-generate-preview`	4、6、8	720p、1080p、4k	16:9、9:16	ネイティブで音声付き	1080p と 4k は 8 秒のみ対応。参照画像や先頭・末尾フレームなどの画像機能を使う場合は 8 秒を推奨。
`veo-3.1-fast-generate-preview`	4、6、8	720p、1080p、4k	16:9、9:16	ネイティブで音声付き	1080p と 4k は 8 秒のみ対応。参照画像や先頭・末尾フレームなどの画像機能を使う場合は 8 秒を推奨。

参考ドキュメント：

アスペクト比

モデル	16:9 横向き	9:16 縦向き	デフォルト比	推奨
`veo-3.1-generate-preview`	対応	対応	16:9	4K は必ず 8 秒。動画拡張は現在未対応。
`veo-3.1-fast-generate-preview`	対応	対応	16:9	4K は必ず 8 秒。動画拡張は現在未対応。

リクエストでは metadata.aspectRatio またはフォームフィールドの aspectRatio でアスペクト比を指定できます：

{
  "metadata": {
    "aspectRatio": "9:16"
  }
}

aspectRatio を明示的に渡さない場合、システムはまず size から比率を推定します。たとえば 1280x720 は 16:9、720x1280 は 9:16 と推定されます。size も渡されていない場合は、上流のデフォルトである 16:9 が使用されます。

音声について

モデル	公式の音声能力	generateAudio 対応	推奨
`veo-3.1-generate-preview`	ネイティブで音声付き	非対応	`generateAudio` は渡さないでください。効果音が必要な場合は prompt に記述します。
`veo-3.1-fast-generate-preview`	ネイティブで音声付き	非対応	`generateAudio` は渡さないでください。効果音が必要な場合は prompt に記述します。

Veo 3.1 シリーズはネイティブで音声付きの動画モデルですが、現在の Gemini API の Veo パラメーターテーブルでは generateAudio が制御可能なパラメーターとして公開されていません。このフィールドを渡すと、上流から INVALID_ARGUMENT が返される可能性があります。

音声の内容を制御したい場合は、prompt にセリフ・環境音・効果音・音楽のスタイルを記述できます。例：

夕暮れの海辺の灯台、波が岩を優しく打ち、遠くで低い風の音と海鳥の声、映画のような光と影、安定したカメラワーク

画像入力の能力

機能	Google 公式 Veo の能力	aicentos インターフェース対応	説明
1 枚の初期画像から動画生成	対応	対応	`input_reference` で画像 1 枚をアップロードし、動画の先頭フレームとして使用します。
先頭・末尾フレーム生成 / フレーム補間	Veo 3.1 シリーズは image + lastFrame に対応	対応	先頭フレームは `input_reference`、末尾フレームは `last_frame` または `lastFrame` を使用します。Veo 3.1 シリーズ・8 秒を推奨。
複数の参照画像	Veo 3.1 シリーズは最大 3 枚の referenceImages に対応	対応	`reference_image`、`reference_images`、`referenceImages` のいずれかでアップロードします。`referenceType` は `asset` のみ対応。8 秒を推奨。
動画拡張	Veo 3.1 / Fast は既存 Veo 動画の拡張に対応	現在未対応	現在の aicentos インターフェースは公式の video 入力を公開していません。

画像の MIME タイプは image/jpeg、image/png、image/webp に対応しています。ファイルまたは Base64 での送信を推奨し、リモート画像 URL の直接指定は非推奨です。
参照画像モードの注意点：現在の上流は参照画像のシナリオで negativePrompt に対応しておらず、渡すと Negative prompt is not supported in your use case が返されることがあります。参照画像リクエストでは negativePrompt を渡さないでください。
実装上の説明：Gemini API の Veo predictLongRunning の画像パラメーターは bytesBase64Encoded + mimeType を使用し、通常の generateContent の inlineData ではありません。aicentos は multipart でアップロードされた画像を、上流が必要とする形式に変換します。

課金ルール

動画生成時間に基づいて課金され、単位は秒です。上の表にあるモデル対応の秒数を使用し、任意の秒数は渡さないでください。
リクエストで動画の長さが指定されていない場合、システムはデフォルトで 8 秒として課金します。
秒数の認識優先度：metadata.durationSeconds > duration > seconds > デフォルト 8 秒。
解像度の認識優先度：metadata.resolution > size > デフォルト 720p。
720p / 1080p / 4K は同じルールで課金され、解像度による追加料金はありません。
aspectRatio は横向きか縦向きかを制御するだけで、追加料金はありません。
4K は 8 秒のみ対応しています。
具体的な単価は aicentos コンソールの表示が優先されます。

エンドポイント

現在、次の 3 つのエンドポイントの使用を推奨します：

用途	メソッド	パス
タスク作成	POST	`/v1/videos`
ステータス照会	GET	`/v1/videos/{task_id}`
結果のダウンロード	GET	`/v1/videos/{task_id}/content`

照会時に結果の URL を直接取得したい場合は、次も使用できます：

用途	メソッド	パス
ステータスと結果 URL の照会	GET	`/v1/video/generations/{task_id}`

認証

export BASE_URL="https://aicentos.com"
export AICENTOS_API_KEY="sk-xxxxxx"

すべてのリクエストに以下を付けます：

-H "Authorization: Bearer $AICENTOS_API_KEY"

テキストから動画生成タスクの作成

curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-preview",
    "prompt": "夕暮れの海辺の灯台、カメラがゆっくりと前進し、波が岩を優しく打つ、映画のような光と影、安定したカメラワーク",
    "seconds": "8",
    "size": "1280x720",
    "metadata": {
      "negativePrompt": "blurry, watermark, distorted, low quality",
      "resolution": "720p",
      "aspectRatio": "16:9",
      "seed": 20260401
    }
  }'

典型的なレスポンス：

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "veo-3.1-generate-preview",
  "status": "queued",
  "progress": 0,
  "created_at": 1775025000
}

先頭フレームからの動画生成タスクの作成

現在、画像からの動画生成には multipart/form-data の使用を推奨します。先頭フレーム画像のフィールド名は input_reference である必要があります。

curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Accept: application/json" \
  -F "model=veo-3.1-generate-preview" \
  -F "prompt=画面の少女がカメラの方を振り向き、そよ風が髪をなびかせ、背景の街の灯りがかすんでぼやける、カメラは安定して前進する" \
  -F "input_reference=@./first-frame.png;type=image/png" \
  -F "seconds=8" \
  -F "size=1280x720" \
  -F "resolution=720p" \
  -F "aspectRatio=16:9" \
  -F "negativePrompt=blurry, watermark, deformed hands" \
  -F "seed=20260401"

先頭・末尾フレームタスクの作成

先頭・末尾フレームタスクでは、先頭フレームと末尾フレームの両方が必要です。先頭フレームは input_reference、末尾フレームは last_frame または lastFrame を使用します。

curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Accept: application/json" \
  -F "model=veo-3.1-generate-preview" \
  -F "prompt=最初の少女の画面から最後の少年の画面へ自然に移り変わり、カメラは安定して前進し、街の灯りはかすんでぼやけ、髪と服が風でわずかに揺れる、自然でリアルなトランジション" \
  -F "input_reference=@./first-frame.png;type=image/png" \
  -F "last_frame=@./last-frame.png;type=image/png" \
  -F "seconds=8" \
  -F "size=1280x720" \
  -F "resolution=720p" \
  -F "aspectRatio=16:9" \
  -F "negativePrompt=blurry, watermark, distorted face, deformed hands" \
  -F "seed=20260402"

参照画像タスクの作成

参照画像タスクは Veo 3.1 シリーズのみ対応で、最大 3 枚、referenceType は asset のみです。フィールド名は reference_image、reference_images、referenceImages のいずれかを使用できます。参照画像タスクでは negativePrompt を渡さないでください。

curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Accept: application/json" \
  -F "model=veo-3.1-generate-preview" \
  -F "prompt=2 枚の画像の人物の外見と都市の夜景の雰囲気を参考に、映画のような二人の街頭シーンを生成。カメラは安定して前進し、背景の灯りはかすんでぼやけ、人物は自然にカメラを見る" \
  -F "reference_image=@./ref-1.png;type=image/png" \
  -F "reference_image=@./ref-2.png;type=image/png" \
  -F "reference_type=asset" \
  -F "seconds=8" \
  -F "size=1280x720" \
  -F "resolution=720p" \
  -F "aspectRatio=16:9" \
  -F "seed=20260403"

JSON / Base64 も使用できます：

{
  "model": "veo-3.1-generate-preview",
  "prompt": "参照画像の商品の外観を使って広告ショットを生成する",
  "duration": 8,
  "metadata": {
    "resolution": "720p",
    "aspectRatio": "16:9",
    "referenceImages": [
      {
        "image": {
          "bytesBase64Encoded": "BASE64_IMAGE",
          "mimeType": "image/png"
        },
        "referenceType": "asset"
      }
    ]
  }
}

タスクステータスの照会

まず、作成エンドポイントが返した id または task_id を保存します：

export TASK_ID="task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

次にステータスを照会します：

curl -X GET "$BASE_URL/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer $AICENTOS_API_KEY"

処理中の場合の典型的なレスポンス：

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "veo-3.1-generate-preview",
  "status": "in_progress",
  "progress": 50,
  "created_at": 1775025000
}

完了後の典型的なレスポンス：

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "veo-3.1-generate-preview",
  "status": "completed",
  "progress": 100,
  "created_at": 1775025000,
  "completed_at": 1775025068
}

ステータスと結果 URL の照会

照会時にダウンロード可能な URL を直接取得したい場合は、次を呼び出します：

curl -X GET "$BASE_URL/v1/video/generations/$TASK_ID" \
  -H "Authorization: Bearer $AICENTOS_API_KEY"

典型的なレスポンス：

{
  "code": "success",
  "message": "",
  "data": {
    "error": null,
    "format": "mp4",
    "metadata": null,
    "status": "succeeded",
    "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "url": "https://aicentos.com/v1/videos/task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/content"
  }
}

動画結果のダウンロード

タスク完了後、直接ダウンロードします：

curl -L "$BASE_URL/v1/videos/$TASK_ID/content" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -o veo-result.mp4

ステータス一覧

GET /v1/videos/{task_id} が返す主なステータス：

ステータス	説明
`queued`	キュー待ち
`in_progress`	生成中
`completed`	完了
`failed`	失敗

GET /v1/video/generations/{task_id} が返す主なステータス：

ステータス	説明
`queued`	キュー待ち
`processing`	生成中
`succeeded`	成功
`failed`	失敗

接続時の注意点

prompt は必須です。
画像からの動画生成では、画像フィールド名が input_reference である必要があります。
先頭・末尾フレームタスクでは先頭フレームと末尾フレームの両方が必須です。先頭フレームは input_reference、末尾フレームは last_frame または lastFrame を使用します。
参照画像タスクは Veo 3.1 シリーズのみ対応で、最大 3 枚、かつ 8 秒である必要があります。
参照画像タスクでは negativePrompt を渡さないでください。
現在の Gemini 画像からの動画生成では、リモート画像 URL の直接指定は非推奨です。ファイルまたは Base64 での送信を推奨します。
GET /v1/videos/{task_id} をポーリングし、status=completed になってからダウンロードすることを推奨します。
Veo 3.1 シリーズは 4、6、8 秒を指定できます。1080p または 4k を使う場合は必ず 8 秒を指定します。
横向きは aspectRatio=16:9、縦向きは aspectRatio=9:16 を使用します。未指定の場合はデフォルトで 16:9 として処理されます。
generateAudio パラメーターは渡さないでください。Veo 3.1 シリーズはネイティブで音声付きの動画モデルですが、現在の Gemini API では generateAudio パラメーターによる音声のオン/オフに対応していません。このフィールドを渡すと、上流から INVALID_ARGUMENT が返される可能性があります。
音声の内容を制御したい場合は、prompt にセリフ・環境音・効果音・音楽のスタイルを記述してください。
公式の Veo 3.1 は動画拡張に対応していますが、現在の aicentos インターフェースは公式の video 入力をまだ公開していません。

Veo 動画生成

モデルの能力アンカーリンクをコピー

公式の能力と aicentos の公開範囲アンカーリンクをコピー

アスペクト比アンカーリンクをコピー

音声についてアンカーリンクをコピー

画像入力の能力アンカーリンクをコピー

課金ルールアンカーリンクをコピー

エンドポイントアンカーリンクをコピー

認証アンカーリンクをコピー

テキストから動画生成タスクの作成アンカーリンクをコピー

先頭フレームからの動画生成タスクの作成アンカーリンクをコピー

先頭・末尾フレームタスクの作成アンカーリンクをコピー

参照画像タスクの作成アンカーリンクをコピー

タスクステータスの照会アンカーリンクをコピー

ステータスと結果 URL の照会アンカーリンクをコピー

動画結果のダウンロードアンカーリンクをコピー

ステータス一覧アンカーリンクをコピー

接続時の注意点アンカーリンクをコピー

このページの内容