透過 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 介面支援	說明
單張初始圖生成影片	支援	支援	使用 `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`

如果希望查詢時直接拿到結果位址，也可以使用：

用途	方法	路徑
查詢狀態和結果位址	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=參考兩張圖片中的人物外觀和城市夜景氛圍，生成一段電影感雙人街頭鏡頭，鏡頭平穩推進，背景燈光輕微虛化，人物自然看向鏡頭" \
  -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
}

查詢任務狀態和結果位址

如果想在查詢時直接拿到可下載位址，可以調用：

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 開放口徑复制锚点链接

畫面比例复制锚点链接

音訊說明复制锚点链接

圖片輸入能力复制锚点链接

計費規則复制锚点链接

介面說明复制锚点链接

驗證复制锚点链接

建立文生影片任務复制锚点链接

建立首影格圖生影片任務复制锚点链接

建立首尾影格任務复制锚点链接

建立參考圖任務复制锚点链接

查詢任務狀態复制锚点链接

查詢任務狀態和結果位址复制锚点链接

下載影片結果复制锚点链接

狀態說明复制锚点链接

接入注意事項复制锚点链接

本頁內容