本頁面由 Cloud Translation API 翻譯而成。

Vertex AI 影片生成 API 中的 Veo

Veo 是支援影片生成的模型名稱。 Veo 會根據您提供的文字提示或圖片提示生成影片。如要進一步瞭解 Veo，請參閱「Veo 影片生成功能總覽」。

如要在控制台中探索這個模型，請參閱 Model Garden 中的Video Generation模型資訊卡。

在 Vertex AI (Vertex AI Studio) 上試用 Veo

在 Colab 中試用 Veo

支援的機型

Veo API 支援下列模型：

詳情請參閱 Veo 型號。

HTTP 要求

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:predictLongRunning \

-d '{
  "instances": [
    {
      "prompt": string,
      "image": {
        // Union field can be only one of the following:
        "bytesBase64Encoded": string,
        "gcsUri": string,
        // End of list of possible types for union field.
        "mimeType": string
      },
      "lastFrame": {
        // Union field can be only one of the following:
        "bytesBase64Encoded": string,
        "gcsUri": string,
        // End of list of possible types for union field.
        "mimeType": string
      },
      "video": {
        // Union field can be only one of the following:
        "bytesBase64Encoded": string,
        "gcsUri": string,
        // End of list of possible types for union field.
        "mimeType": string
      },
      "mask": {
        // Union field can be only one of the following:
        "bytesBase64Encoded": string,
        "gcsUri": string,
        // End of list of possible types for union field.
        "mimeType": string,
        "maskMode": string
      },
      "referenceImages": [
        // A list of up to three asset images or at most one style image for the
        // model to use when generating videos.
        //
        // referenceImages is supported by the following models in Preview:
        //
        // *   veo-2.0-generate-exp
        // *   veo-3.1-generate-preview
        {
        "image:" {
          // Union field can be only one of the following:
          "bytesBase64Encoded": string,
          "gcsUri": string,
          // End of list of possible types for union field.
          "mimeType": string
        },
        "referenceType": string
        }
      ]
    }
  ],
  "parameters": {
    "aspectRatio": string,
    "compressionQuality": string,
    "durationSeconds": integer,
    "enhancePrompt": boolean,
    "generateAudio": boolean,
    "negativePrompt": string,
    "personGeneration": string,
    "resizeMode": string, // Veo 3 image-to-video only
    "resolution": string, // Veo 3 models only
    "sampleCount": integer,
    "seed": uint32,
    "storageUri": string
  }
}'

執行個體

執行個體
`prompt`	`string` 文字轉影片功能需要這項權限。如果提供輸入圖片提示 (圖片轉影片)，則為選用。引導影片前 8 秒的文字字串。例如：快速追蹤鏡頭拍攝的場景：熱鬧的烏托邦式蔓延景象，明亮的霓虹燈、飛車和霧氣，夜晚，鏡頭光暈，體積照明霓虹燈全像投影：車輛以光速行駛，電影感，細節豐富，體積照明許多點狀水母在水下跳動。身體呈透明狀，在深海中會發光極度特寫，淺景深，街上的水窪反射出繁忙的未來東京城市，明亮的霓虹燈招牌，夜晚，鏡頭光暈北極光在北極夜空中舞動的縮時影片，星星閃爍，白雪覆蓋大地一名牛仔在美麗的日落時分，騎著馬穿越開闊的平原，柔和的光線，溫暖的色彩
`image`	聯集欄位 (選用步驟) 引導影片生成的圖片，可以是編碼圖片的 `bytesBase64Encoded` 字串，也可以是 Cloud Storage 值區位置的 `gcsUri` 字串 URI。
`lastFrame`	聯集欄位 (選用步驟) 影片第一格的圖片，填滿兩者之間的空間。`lastFrame` 可以是編碼圖片的 `bytesBase64Encoded` 字串，也可以是 Cloud Storage bucket 位置的 `gcsUri` 字串 URI。 `lastFrame` 支援預先發布版中的下列模型： `veo-2.0-generate-001` `veo-3.0-generate-exp` `veo-3.1-generate-preview` `veo-3.1-fast-generate-preview`
`video`	聯集欄位 (選用步驟) 要延長長度的 Veo 生成影片，可以是編碼影片的 `bytesBase64Encoded` 字串，也可以是 Cloud Storage bucket 位置的 `gcsUri` 字串 URI。 `video` 支援預先發布版中的下列模型： `veo-2.0-generate-001` `veo-3.0-generate-exp`
`mask`	聯集欄位 (選用步驟) 要套用至影片的遮罩圖片，用於在影片中新增或移除物件。`mask` 可以是編碼圖片的 `bytesBase64Encoded` 字串，也可以是 Cloud Storage bucket 位置的 `gcsUri` 字串 URI。 `mask` 支援預先發布版的 `veo-2.0-generate-preview`。
`referenceImages`	`list[referenceImages]` (選用步驟) 最多三張素材資源圖片或一張風格圖片，用來描述模型生成影片時使用的`referenceImages`。重要事項：Veo 3.1 型號不支援 `referenceImages.style`。使用樣式圖片時，請使用 `veo-2.0-generate-exp`。 `referenceImages` 支援下列預先發布版模型： `veo-2.0-generate-exp` `veo-3.1-generate-preview`
`referenceImages.image`	聯集欄位 (選用步驟) 包含 `veo-2.0-generate-exp` 的參考圖片，可做為主題輸入內容。每張圖片可以是編碼圖片的 `bytesBase64Encoded` 字串，也可以是 Cloud Storage 值區位置的 `gcsUri` 字串 URI。
`referenceImages.referenceType`	`string` `referenceImages` 物件中為必填欄位。指定提供的參考圖片類型。支援的值如下： `"asset"`：參照圖片會為生成的影片提供素材資源，例如場景、物件或角色。 `"style"`：參考圖片會提供生成影片的風格資訊，例如場景顏色、光線或紋理。重要事項：Veo 3.1 型號不支援 `referenceImages.style`。使用風格圖片時，請使用 `veo-2.0-generate-exp`。
`bytesBase64Encoded`	`string` 圖片或影片檔案的位元組 Base64 編碼字串。適用於下列物件： `image` `video` `lastFrame` `referenceImages.image`
`gcsUri`	`string` Cloud Storage 值區位置的字串 URI。適用於下列物件： `image` `video` `lastFrame` `referenceImages.image`
`mimeType`	`string` 下列物件必須提供這個屬性： `image` `video` `mask` `lastFrame` `referenceImages.image` 指定影片或圖片的 MIME 類型。圖片可接受的 MIME 類型如下： `image/jpeg` `image/png` `image/webp` 影片可接受的 MIME 類型如下： `video/mov` `video/mpeg` `video/mp4` `video/mpg` `video/avi` `video/wmv` `video/mpegps` `video/flv`

參數

參數
`aspectRatio`	`string` (選用步驟) 指定生成的影片顯示比例。系統接受下列值： `"16:9"` `"9:16"` 預設值為 `"16:9"`。
`compressionQuality`	`string` (選用步驟) 指定所產生影片的壓縮品質。可接受的值為 `"optimized"` 或 `"lossless"`。預設值為 `"optimized"`。
`durationSeconds`	`integer` 這是必要旗標，要生成的影片長度 (以秒為單位)。系統接受下列值： Veo 2 模型： `5`-`8`。預設為 `8`。 Veo 3 型號： `4`、`6` 或 `8`。預設值為 `8`。使用 `referenceImages` 時： `8`。詳情請參閱 Veo 模型。
`enhancePrompt`	`boolean` (選用步驟) 使用 Gemini 強化提示。可接受的值為 `true` 或 `false`。預設值為 `true`。
`generateAudio`	`boolean` Veo 3 機型必須使用這項功能。生成影片音訊。可接受的值為 `true` 或 `false`。 `generateAudio` 不支援 `veo-2.0-generate-001` 或 `veo-2.0-generate-exp`。如要進一步瞭解可用的 Veo 模型，請參閱 Veo 模型。
`negativePrompt`	`string` (選用步驟) 文字字串，說明您希望模型避免生成任何內容。例如：頭頂照明、鮮豔色彩人、動物多輛車、風
`personGeneration`	`string` (選用步驟) 這項安全設定可控管是否允許生成人物或臉孔。可使用下列其中一個值： `"allow_adult"` (預設值)：只允許生成成人內容 `"dont_allow"`：禁止在圖片中加入人物/臉部
`resizeMode`	`string` (選用步驟) 僅限 Veo 3 模型，搭配 `image` 使用，可將圖片轉換成影片。模型用來調整影片大小的縮放模式。可接受的值為 `"pad"` (預設) 或 `"crop"`。
`resolution`	`string` (選用步驟) 僅限 Veo 3 模型。生成影片的解析度。可接受的值為 `"720p"` (預設值) 或 `"1080p"`。
`sampleCount`	`int` (選用步驟) 要求的輸出影片數量。可接受的值為 `1`-`4`。
`seed`	`uint32` (選用步驟) 用於要求生成確定性影片的數字。在要求中加入種子號碼，但未變更其他參數，模型就會產生相同的影片。可接受的範圍為 `0` 到 `4,294,967,295`。
`storageUri`	`string` (選用步驟) 儲存輸出影片的 Cloud Storage 值區 URI，格式為 `gs://BUCKET_NAME/SUBDIRECTORY`。如果未提供 Cloud Storage 值區，系統會在回應中傳回 Base64 編碼的影片位元組。

要求範例

請參考下列範例，建立自己的影片要求：

文字轉影片生成要求

REST

如要使用 Vertex AI Veo API 測試文字提示，請將 POST 要求傳送至發布者模型端點。

使用任何要求資料之前，請先替換以下項目：

PROJECT_ID：代表您 Google Cloud 專案 ID 的字串。
MODEL_ID：代表要使用的模型 ID 的字串。可接受的值如下：
- Veo 2： "veo-2.0-generate-001"
- Veo 3："veo-3.0-generate-001"
- Veo 3："veo-3.0-fast-generate-001"
- Veo 3："veo-3.0-generate-preview" (預先發布版)
- Veo 3："veo-3.0-fast-generate-preview" (預先發布版)
- Veo 3.1： "veo-3.1-generate-preview"
- Veo 3.1： "veo-3.1-fast-generate-preview"
TEXT_PROMPT：用來引導影片生成的文字提示。
OUTPUT_STORAGE_URI：選用：代表 Cloud Storage 值區的字串，用於儲存輸出影片。如果未提供，回應中會傳回影片位元組。例如： "gs://video-bucket/output/"。
RESPONSE_COUNT：要生成的影片檔案數量。可接受的值範圍為 1 到 4。
DURATION：代表生成影片檔案長度的整數。以下是各個模型可接受的值：
- Veo 2 模型：5-8。預設為 8。
- Veo 3 型號：4、6 或 8。預設值為 8。
其他選用參數

請視用途使用下列選用變數。在 "parameters": {} 物件中新增下列部分或所有參數。
```
"parameters": {
  "aspectRatio": "ASPECT_RATIO",
  "negativePrompt": "NEGATIVE_PROMPT",
  "personGeneration": "PERSON_SAFETY_SETTING",
  // "resolution": RESOLUTION, // Veo 3 models only
  "sampleCount": RESPONSE_COUNT,
  "seed": SEED_NUMBER
}
```
- ASPECT_RATIO：選用：描述生成影片顯示比例的字串值。你可以使用下列值：
  - "16:9" 橫向
  - "9:16" 直向
  預設值為 "16:9"
- NEGATIVE_PROMPT：選用：字串值，說明您要禁止模型生成哪些內容。
- PERSON_SAFETY_SETTING：選用：控制生成人物或臉部安全設定的字串值。你可以使用下列值：
  - "allow_adult"：只允許生成成人人物和臉孔。
  - "disallow"：不會生成人物或臉部。
  預設值為 "allow_adult"。
- RESOLUTION：選用：控制生成影片解析度的字串值。僅支援 Veo 3 模型。你可以使用下列值：
  - "720p"
  - "1080p"
  預設值為 "720p"。
- RESPONSE_COUNT：選用。整數值，說明要生成的影片數量。可接受的值範圍為 1 到 4。
- SEED_NUMBER：選用。模型用來生成確定性影片的 uint32 值。在要求中指定種子號碼，但不變更其他參數，即可引導模型生成相同的影片。可接受的值範圍為 0 到 4294967295。

HTTP 方法和網址：

POST https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID:predictLongRunning

JSON 要求主體：

{
  "instances": [
    {
      "prompt": "TEXT_PROMPT"
    }
  ],
  "parameters": {
    "storageUri": "OUTPUT_STORAGE_URI",
    "sampleCount": "RESPONSE_COUNT"
  }
}

如要傳送要求，請選擇以下其中一個選項：

curl

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell，自動登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID:predictLongRunning"

PowerShell

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID:predictLongRunning" | Select-Object -Expand Content

這項要求會傳回完整作業名稱和專屬作業 ID。使用這個完整作業名稱輪詢影片生成要求的狀態。

{
  "name": "projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID/operations/a1b07c8e-7b5a-4aba-bb34-3e1ccb8afcc8"
}

以圖片生成影片的要求

REST

如要使用 Vertex AI Veo API 測試文字提示，請將 POST 要求傳送至發布者模型端點。

使用任何要求資料之前，請先替換以下項目：

PROJECT_ID：代表您 Google Cloud 專案 ID 的字串。
MODEL_ID：代表要使用的模型 ID 的字串。可接受的值如下：
- Veo 2：veo-2.0-generate-001
- Veo 3：veo-3.0-generate-001
- Veo 3.1：veo-3.1-generate-preview
- Veo 3.1：veo-3.1-fast-generate-preview
TEXT_PROMPT：用來引導影片生成的文字提示。
INPUT_IMAGE：代表輸入圖片的 Base64 編碼字串。為確保最佳品質，建議輸入圖片的解析度為 720p (1280 x 720 像素) 以上，且長寬比為 16:9 或 9:16。上傳其他顯示比例或大小的圖片時，系統可能會調整圖片大小或從中間裁剪。
MIME_TYPE：代表輸入圖片 MIME 類型的字串。系統僅支援下列 MIME 類型的圖片：
- "image/jpeg"
- "image/png"
OUTPUT_STORAGE_URI：選用：代表 Cloud Storage 值區的字串，用於儲存輸出影片。如果未提供，回應中會傳回影片位元組。例如： "gs://video-bucket/output/"。
RESIZE_MODE：代表要使用的調整大小模式的字串。可接受的值如下：
- "crop"：裁剪影片，使其符合新尺寸。
- "pad"：在影片周圍加上邊框，配合新尺寸。
RESPONSE_COUNT：要生成的影片檔案數量。可接受的值範圍為 1 到 4。
DURATION：代表生成影片檔案長度的整數。以下是各個模型可接受的值：
- Veo 2 模型：5-8。預設為 8。
- Veo 3 型號：4、6 或 8。預設值為 8。
其他選用參數

請視用途使用下列選用變數。在 "parameters": {} 物件中新增下列部分或所有參數。
```
"parameters": {
  "aspectRatio": "ASPECT_RATIO",
  "negativePrompt": "NEGATIVE_PROMPT",
  "personGeneration": "PERSON_SAFETY_SETTING",
  // "resolution": RESOLUTION, // Veo 3 models only
  "sampleCount": RESPONSE_COUNT,
  "seed": SEED_NUMBER
}
```
- ASPECT_RATIO：選用：描述生成影片顯示比例的字串值。你可以使用下列值：
  - "16:9" 橫向
  - "9:16" 直向
  預設值為 "16:9"
- NEGATIVE_PROMPT：選用：字串值，說明您要禁止模型生成哪些內容。
- PERSON_SAFETY_SETTING：選用：控制生成人物或臉部安全設定的字串值。你可以使用下列值：
  - "allow_adult"：只允許生成成人人物和臉孔。
  - "disallow"：不會生成人物或臉部。
  預設值為 "allow_adult"。
- RESOLUTION：選用：控制生成影片解析度的字串值。僅支援 Veo 3 模型。你可以使用下列值：
  - "720p"
  - "1080p"
  預設值為 "720p"。
- RESPONSE_COUNT：選用。整數值，說明要生成的影片數量。可接受的值範圍為 1 到 4。
- SEED_NUMBER：選用。模型用來生成確定性影片的 uint32 值。在要求中指定種子號碼，但不變更其他參數，即可引導模型生成相同的影片。可接受的值範圍為 0 到 4294967295。

HTTP 方法和網址：

POST https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID:predictLongRunning

JSON 要求主體：

{
  "instances": [
    {
      "prompt": "TEXT_PROMPT",
      "image": {
        "bytesBase64Encoded": "INPUT_IMAGE",
        "mimeType": "MIME_TYPE"
      }
    }
  ],
  "parameters": {
    "storageUri": "OUTPUT_STORAGE_URI",
    "sampleCount": RESPONSE_COUNT
    "resizeMode": "RESIZE_MODE"
  }
}

如要傳送要求，請選擇以下其中一個選項：

curl

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID:predictLongRunning"

PowerShell

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID:predictLongRunning" | Select-Object -Expand Content

這項要求會傳回完整作業名稱和專屬作業 ID。使用這個完整作業名稱輪詢影片生成要求的狀態。

{
  "name": "projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID/operations/a1b07c8e-7b5a-4aba-bb34-3e1ccb8afcc8"
}

使用素材資源圖片的影片要求

REST

如要使用 Vertex AI Veo API 測試文字提示，請將 POST 要求傳送至發布者模型端點。

使用任何要求資料之前，請先替換以下項目：

PROJECT_ID：您的 Google Cloud 專案 ID。
MODEL_ID：代表要使用的模型 ID 的字串。可接受的值如下：
- Veo 2：veo-2.0-generate-exp
- Veo 3：veo-3.1-generate-preview
TEXT_PROMPT：用於引導影片生成的文字提示。
BASE64_ENCODED_IMAGE：採用 base64 位元組編碼的主體圖片。您可以重複這個欄位和 mimeType，最多指定三張主體圖片。
IMAGE_MIME_TYPE：輸入圖片的 MIME 類型。只能是下列其中一項：
- image/jpeg
- image/png
您可以重複這個欄位和 bytesBase64Encoded，最多指定三張主體圖片。
OUTPUT_STORAGE_URI：選用：用於儲存輸出影片的 Cloud Storage bucket。如果未提供，回應中會傳回 Base64 位元組編碼的影片。例如：gs://video-bucket/output/。
RESPONSE_COUNT：要生成的影片檔案數量。接受的整數值：1 到 4。
其他選用參數

請視用途使用下列選用變數。在 "parameters": {} 物件中新增下列部分或所有參數。
```
"parameters": {
  "aspectRatio": "ASPECT_RATIO",
  "negativePrompt": "NEGATIVE_PROMPT",
  "personGeneration": "PERSON_SAFETY_SETTING",
  // "resolution": RESOLUTION, // Veo 3 models only
  "sampleCount": RESPONSE_COUNT,
  "seed": SEED_NUMBER
}
```
- ASPECT_RATIO：選用：描述生成影片顯示比例的字串值。你可以使用下列值：
  - "16:9" 橫向
  - "9:16" 直向
  預設值為 "16:9"
- NEGATIVE_PROMPT：選用：字串值，說明您要禁止模型生成哪些內容。
- PERSON_SAFETY_SETTING：選用：控制生成人物或臉部安全設定的字串值。你可以使用下列值：
  - "allow_adult"：只允許生成成人人物和臉孔。
  - "disallow"：不會生成人物或臉部。
  預設值為 "allow_adult"。
- RESOLUTION：選用：控制生成影片解析度的字串值。僅支援 Veo 3 模型。你可以使用下列值：
  - "720p"
  - "1080p"
  預設值為 "720p"。
- RESPONSE_COUNT：選用。整數值，說明要生成的影片數量。可接受的值範圍為 1 到 4。
- SEED_NUMBER：選用。模型用來生成確定性影片的 uint32 值。在要求中指定種子號碼，但不變更其他參數，即可引導模型生成相同的影片。可接受的值範圍為 0 到 4294967295。

HTTP 方法和網址：

POST https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID:predictLongRunning

JSON 要求主體：

{
  "instances": [
    {
      "prompt": "TEXT_PROMPT",
      // The following fields can be repeated for up to three total
      // images.
      "referenceImages": [
        {
          "image": {
            "bytesBase64Encoded": "BASE64_ENCODED_IMAGE",
            "mimeType": "IMAGE_MIME_TYPE"
          },
          "referenceType": "asset"
        }
      ]
    }
  ],
  "parameters": {
    "durationSeconds": 8,
    "storageUri": "OUTPUT_STORAGE_URI",
    "sampleCount": RESPONSE_COUNT
  }
}

如要傳送要求，請選擇以下其中一個選項：

curl

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID:predictLongRunning"

PowerShell

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID:predictLongRunning" | Select-Object -Expand Content

這項要求會傳回完整作業名稱和專屬作業 ID。使用這個完整作業名稱輪詢影片生成要求的狀態。

{
  "name":
  "projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID/operations/a1b07c8e-7b5a-4aba-bb34-3e1ccb8afcc8"
}

使用樣式圖片的影片要求

REST

如要使用 Vertex AI Veo API 測試文字提示，請將 POST 要求傳送至發布者模型端點。

使用任何要求資料之前，請先替換以下項目：

PROJECT_ID：您的 Google Cloud 專案 ID。
MODEL_ID：代表要使用的模型 ID 的字串。請使用下列值： veo-2.0-generate-exp。

重要事項：Veo 3.1 型號不支援 referenceImages.style。使用樣式圖片時，請使用 veo-2.0-generate-exp。
TEXT_PROMPT：用於引導影片生成的文字提示。
BASE64_ENCODED_IMAGE：採用 base64 位元組編碼的樣式圖片。
IMAGE_MIME_TYPE：輸入圖片的 MIME 類型。下列其中一項：
- image/jpeg
- image/png
OUTPUT_STORAGE_URI：選用：用於儲存輸出影片的 Cloud Storage bucket。如果未提供，回應中會傳回影片位元組。例如： gs://video-bucket/output/。
RESPONSE_COUNT：要生成的影片檔案數量。接受的整數值：1 到 4。
其他選用參數

請視用途使用下列選用變數。在 "parameters": {} 物件中新增下列部分或所有參數。
```
"parameters": {
  "aspectRatio": "ASPECT_RATIO",
  "negativePrompt": "NEGATIVE_PROMPT",
  "personGeneration": "PERSON_SAFETY_SETTING",
  // "resolution": RESOLUTION, // Veo 3 models only
  "sampleCount": RESPONSE_COUNT,
  "seed": SEED_NUMBER
}
```
- ASPECT_RATIO：選用：描述生成影片顯示比例的字串值。你可以使用下列值：
  - "16:9" 橫向
  - "9:16" 直向
  預設值為 "16:9"
- NEGATIVE_PROMPT：選用：字串值，說明您要禁止模型生成哪些內容。
- PERSON_SAFETY_SETTING：選用：控制生成人物或臉部安全設定的字串值。你可以使用下列值：
  - "allow_adult"：只允許生成成人人物和臉孔。
  - "disallow"：不會生成人物或臉部。
  預設值為 "allow_adult"。
- RESOLUTION：選用：控制生成影片解析度的字串值。僅支援 Veo 3 模型。你可以使用下列值：
  - "720p"
  - "1080p"
  預設值為 "720p"。
- RESPONSE_COUNT：選用。整數值，說明要生成的影片數量。可接受的值範圍為 1 到 4。
- SEED_NUMBER：選用。模型用來生成確定性影片的 uint32 值。在要求中指定種子號碼，但不變更其他參數，即可引導模型生成相同的影片。可接受的值範圍為 0 到 4294967295。

HTTP 方法和網址：

POST https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID:predictLongRunning

JSON 要求主體：

{
  "instances": [
    {
      "prompt": "TEXT_PROMPT",
      "referenceImages": [
        {
          "image": {
            "bytesBase64Encoded": "BASE64_ENCODED_IMAGE",
            "mimeType": "IMAGE_MIME_TYPE"
          },
          "referenceType": "style"
        }
      ]
    }
  ],
  "parameters": {
    "durationSeconds": 8,
    "storageUri": "OUTPUT_STORAGE_URI",
    "sampleCount": RESPONSE_COUNT
  }
}

如要傳送要求，請選擇以下其中一個選項：

curl

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID:predictLongRunning"

PowerShell

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID:predictLongRunning" | Select-Object -Expand Content

這項要求會傳回完整作業名稱和專屬作業 ID。使用這個完整作業名稱輪詢影片生成要求的狀態。

{
  "name":
  "projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID/operations/a1b07c8e-7b5a-4aba-bb34-3e1ccb8afcc8"
}

輪詢影片生成長時間執行作業的狀態

檢查影片生成長時間執行作業的狀態。

REST

使用任何要求資料之前，請先替換以下項目：

PROJECT_ID：您的 Google Cloud 專案 ID。
MODEL_ID：要使用的模型 ID。
OPERATION_ID：原始生成影片要求中傳回的專屬作業 ID。

HTTP 方法和網址：

POST https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID:fetchPredictOperation

JSON 要求主體：

{
  "operationName": "projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID/operations/OPERATION_ID"
}

如要傳送要求，請選擇以下其中一個選項：

curl

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID:fetchPredictOperation"

PowerShell

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID:fetchPredictOperation" | Select-Object -Expand Content

這項要求會傳回作業相關資訊，包括作業是否仍在執行中或已完成。

回應

{
  "name": "projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID/operations/OPERATION_ID",
  "done": true,
  "response": {
    "raiMediaFilteredCount": 0,
    "@type": "type.googleapis.com/cloud.ai.large_models.vision.GenerateVideoResponse",
    "videos": [
      {
        "gcsUri":"gs://BUCKET_NAME/TIMESTAMPED_FOLDER/sample_0.mp4",
        "mimeType": "video/mp4"
      }
    ]
  }
}

回應主體 (生成影片要求)

傳送文字轉影片或圖像轉影片要求後，系統會傳回下列回應：

{
  "name": string
}

回應元素	說明
`name`	在傳送影片生成要求後開始執行的長期作業完整名稱。

回覆範例 (生成影片要求)

{
  "name": "projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID/operations/OPERATION_ID"
}

回應主體 (輪詢長時間執行的作業)

輪詢原始影片生成長時間執行的作業狀態，會傳回類似以下的回應：

{
   "name": string,
   "done": boolean,
   "response":{
      "@type":"type.googleapis.com/cloud.ai.large_models.vision.GenerateVideoResponse",
      "raiMediaFilteredCount": integer,
      "videos":[
         {
           "gcsUri": string,
           "mimeType": string
         },
         {
           "gcsUri": string,
           "mimeType": string
         },
         {
           "gcsUri": string,
           "mimeType": string
         },
         {
           "gcsUri": string,
           "mimeType": string
         },
      ]
   }
}

回應元素	說明
`bytesBase64Encoded`	代表影片物件的 Base64 位元組編碼字串。
`done`	表示作業是否完成的布林值。
`encoding`	影片編碼類型。
`gcsUri`	生成影片的 Cloud Storage URI。
`name`	傳送影片生成要求後開始的長期執行作業完整名稱。
`raiMediaFilteredCount`	傳回 Veo 根據負責任的 AI 政策篩除的影片數量。如果沒有篩選任何影片，傳回的計數為 `0`。
`raiMediaFilteredReasons`	列出因負責任的 AI 技術政策而遭篩除的 Veo 影片原因。詳情請參閱「安全篩選器程式碼類別」。
`response`	長時間執行作業的回應內容。
`video`	生成的影片。

範例回應 (輪詢長時間執行的作業)

{
   "name": "projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID/operations/OPERATION_ID",
   "done":true,
   "response":{
      "@type":"type.googleapis.com/cloud.ai.large_models.vision.GenerateVideoResponse",
      "raiMediaFilteredCount": 0,
      "videos":[
        {
          "gcsUri":"gs://STORAGE_BUCKET/TIMESTAMPED_SUBDIRECTORY/sample_0.mp4",
          "mimeType":"video/mp4"
        },
        {
          "gcsUri":"gs://STORAGE_BUCKET/TIMESTAMPED_SUBDIRECTORY/sample_1.mp4",
          "mimeType":"video/mp4"
        },
        {
          "gcsUri":"gs://STORAGE_BUCKET/TIMESTAMPED_SUBDIRECTORY/sample_2.mp4",
          "mimeType":"video/mp4"
        },
        {
          "gcsUri":"gs://STORAGE_BUCKET/TIMESTAMPED_SUBDIRECTORY/sample_3.mp4",
          "mimeType":"video/mp4"
        }
      ]
   }
}

後續步驟

請參閱 Google DeepMind 的 Veo 模型資訊。
請參閱「Veo 和 Imagen 3：在 Vertex AI 上推出全新影片和圖片生成模型」網誌文章。
請參閱「New generative media models and tools, built with and for creators」網誌文章。

Vertex AI 影片生成 API 中的 Veo

支援的機型

HTTP 要求

執行個體

參數

要求範例

文字轉影片生成要求

REST

curl

PowerShell

以圖片生成影片的要求

REST

curl

PowerShell

使用素材資源圖片的影片要求

REST

curl

PowerShell

使用樣式圖片的影片要求

REST

curl

PowerShell

輪詢影片生成長時間執行作業的狀態

REST

curl

PowerShell

回應

回應主體 (生成影片要求)

回覆範例 (生成影片要求)

回應主體 (輪詢長時間執行的作業)

範例回應 (輪詢長時間執行的作業)

更多資訊

後續步驟