Veo 3.1 影片生成 API
使用 Google Veo 3.1 模型生成影片的 API,支援文字生成影片、參考圖片和首尾幀模式。支援多鏡頭長影片,最長 168 秒。
線上體驗: https://nanophoto.ai/veo-3
| 方法 | 路徑 | 說明 |
|---|
| POST | /api/veo-3/generate | 生成影片 |
| POST | /api/veo-3/check-status | 查詢任務狀態 |
Authorization: Bearer YOUR_API_KEY
| 解析度 | 鏡頭數 | 點數 |
|---|
| 720p | 每個鏡頭 | 10 |
| 1080p | 僅限 1 個鏡頭 | 14 |
| 4K | 僅限 1 個鏡頭 | 30 |
每個鏡頭生成 8 秒影片片段,多鏡頭影片自動拼接。
每次請求最多 21 個鏡頭(總計 168 秒)。1080p 和 4K 僅支援單鏡頭生成。
| Header | 值 |
|---|
Content-Type | application/json |
Authorization | Bearer YOUR_API_KEY |
| 參數 | 類型 | 必填 | 說明 |
|---|
shots | object[] | 是 | 鏡頭物件陣列(最多 21 個) |
shots[].id | string | 是 | 鏡頭唯一識別碼 |
shots[].prompt | string | 是 | 影片生成提示詞 |
shots[].generationType | string | 是 | TEXT_2_VIDEO、FIRST_AND_LAST_FRAMES_2_VIDEO 或 REFERENCE_2_VIDEO |
shots[].aspectRatio | string | 是 | 16:9 或 9:16 |
shots[].imageUrls | string[] | 條件必填 | 公開圖片 URL(按生成類型要求) |
resolution | string | 否 | 720p(預設)、1080p 或 4k(僅單鏡頭) |
| 類型 | 說明 | 圖片要求 |
|---|
TEXT_2_VIDEO | 文字生成影片 | 無(不可傳圖片) |
FIRST_AND_LAST_FRAMES_2_VIDEO | 首尾幀生成影片 | 1-2 張圖片 |
REFERENCE_2_VIDEO | 參考圖片生成影片 | 1-3 張圖片 |
API 呼叫僅接受 imageUrls(公開 URL),不支援 Base64 圖片上傳。
curl -X POST "https://nanophoto.ai/api/veo-3/generate" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
--data-raw '{
"shots": [
{
"id": "shot-1",
"prompt": "一隻金毛犬在日落時分的海灘上奔跑,電影級光影",
"generationType": "TEXT_2_VIDEO",
"aspectRatio": "16:9"
}
],
"resolution": "720p"
}'
curl -X POST "https://nanophoto.ai/api/veo-3/generate" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
--data-raw '{
"shots": [
{
"id": "shot-1",
"prompt": "畫中的人物動起來,穿越魔法森林",
"generationType": "REFERENCE_2_VIDEO",
"aspectRatio": "16:9",
"imageUrls": ["https://static.nanophoto.ai/demo/nano-banana-pro.webp"]
}
],
"resolution": "720p"
}'
curl -X POST "https://nanophoto.ai/api/veo-3/generate" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
--data-raw '{
"shots": [
{
"id": "shot-1",
"prompt": "城市天際線的黎明全景,金色的陽光",
"generationType": "TEXT_2_VIDEO",
"aspectRatio": "16:9"
},
{
"id": "shot-2",
"prompt": "窗台上的咖啡杯特寫,蒸氣升騰",
"generationType": "TEXT_2_VIDEO",
"aspectRatio": "16:9"
},
{
"id": "shot-3",
"prompt": "一個人穿過公園,秋葉飄落",
"generationType": "TEXT_2_VIDEO",
"aspectRatio": "16:9"
}
],
"resolution": "720p"
}'
async function generateVideo() {
// 第一步:提交生成任務
const response = await fetch("https://nanophoto.ai/api/veo-3/generate", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: "Bearer YOUR_API_KEY",
},
body: JSON.stringify({
shots: [
{
id: "shot-1",
prompt: "一隻金毛犬在日落時分的海灘上奔跑",
generationType: "TEXT_2_VIDEO",
aspectRatio: "16:9",
},
],
resolution: "720p",
}),
});
const data = await response.json();
if (data.status === "failed") {
console.error("生成失敗:", data.error);
return;
}
// 第二步:輪詢任務狀態
const taskIds = data.shots.map((shot: any) => ({
shotId: shot.shotId,
taskId: shot.taskId,
}));
while (true) {
await new Promise((resolve) => setTimeout(resolve, 5000)); // 等待 5 秒
const statusRes = await fetch(
"https://nanophoto.ai/api/veo-3/check-status",
{
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: "Bearer YOUR_API_KEY",
},
body: JSON.stringify({ taskIds, resolution: "720p" }),
}
);
const status = await statusRes.json();
if (status.status === "completed") {
for (const shot of status.shots) {
console.log(`鏡頭 ${shot.shotId} 影片網址:`, shot.videoUrl);
}
return;
}
if (status.status === "failed") {
console.error("生成失敗:", status.shots);
return;
}
console.log("處理中...");
}
}
generateVideo();
{
"status": "processing",
"shots": [
{
"shotId": "shot-1",
"taskId": "task_abc123",
"status": "processing"
}
],
"creditsUsed": 10
}
收到 status: "processing" 時,請每隔 5-10 秒輪詢 check-status 端點。
{
"error": "Insufficient credits",
"errorCode": "INSUFFICIENT_CREDITS",
"requiredCredits": 10
}
POST /api/veo-3/check-status
| Header | 值 |
|---|
Content-Type | application/json |
Authorization | Bearer YOUR_API_KEY |
| 參數 | 類型 | 必填 | 說明 |
|---|
taskIds | object[] | 是 | 生成端點返回的任務 ID 陣列 |
taskIds[].shotId | string | 是 | 鏡頭 ID |
taskIds[].taskId | string | 是 | 生成端點返回的任務 ID |
resolution | string | 否 | 720p(預設)、1080p 或 4k |
curl -X POST "https://nanophoto.ai/api/veo-3/check-status" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
--data-raw '{
"taskIds": [
{"shotId": "shot-1", "taskId": "task_abc123"}
],
"resolution": "720p"
}'
{
"status": "processing",
"shots": [
{
"shotId": "shot-1",
"taskId": "task_abc123",
"status": "processing"
}
]
}
{
"status": "completed",
"shots": [
{
"shotId": "shot-1",
"taskId": "task_abc123",
"status": "completed",
"videoUrl": "https://video.nanophoto.ai/veo/...",
"generationTime": 90
}
]
}
{
"status": "failed",
"shots": [
{
"shotId": "shot-1",
"taskId": "task_abc123",
"status": "failed",
"error": "Video generation failed"
}
]
}
- 每 5-10 秒 輪詢一次
/api/veo-3/check-status
- 典型生成時間:每個鏡頭約 2-5 分鐘
- 多鏡頭影片因順序生成需要更長時間
- 生成失敗時點數會自動退還
| errorCode | HTTP 狀態碼 | 說明 |
|---|
LOGIN_REQUIRED | 401 | 需要認證 |
API_KEY_RATE_LIMIT_EXCEEDED | 429 | 超出頻率限制(100 次/小時) |
INSUFFICIENT_CREDITS | 402 | 點數不足 |
SHOTS_REQUIRED | 400 | 缺少鏡頭陣列 |
PROMPT_REQUIRED | 400 | 鏡頭缺少提示詞 |
INVALID_IMAGE_COUNT | 400 | 圖片數量不符合生成類型要求 |
IMAGE_URLS_REQUIRED | 400 | API 呼叫需要 imageUrls(不支援 base64) |
GENERATION_FAILED | 500 | 影片生成失敗 |
TASK_IDS_REQUIRED | 400 | 缺少任務 ID |
TASK_NOT_FOUND | 404 | 任務不存在或無權存取 |
INTERNAL_ERROR | 500 | 內部伺服器錯誤 |