影片生成技能
此技能引導您如何使用 z-ai-web-dev-sdk 套件實作影片生成功能,讓 AI 模型能透過非同步任務處理,從文字描述或圖片建立影片。
技能路徑
技能位置:{project_path}/skills/video-generation
此技能位於您專案中的上述路徑。
參考腳本:您可以在 {Skill Location}/scripts/ 目錄中找到範例測試腳本,供快速測試與參考。請參閱 {Skill Location}/scripts/video.ts 取得可運作的範例。
概覽
影片生成功能讓您能建置可從文字提示或圖片建立影片內容的應用程式,並可自訂解析度、影格率、持續時間與品質設定等參數。API 採用非同步任務模型,您需先建立任務,再輪詢結果。
重要:z-ai-web-dev-sdk 僅能用於後端程式碼,絕不可用於客戶端程式碼。
先決條件
z-ai-web-dev-sdk 套件已預先安裝。請依下列範例所示方式匯入。
CLI 使用方式(適用於簡單任務)
對於簡單的影片生成任務,您可以使用 z-ai CLI 而非撰寫程式碼。CLI 會自動處理任務建立與輪詢,非常適合快速測試與簡單自動化。
基本文字轉影片
# 使用自動輪詢生成影片
z-ai video --prompt "一隻正在玩球的貓" --poll
# 使用短選項
z-ai video -p "美麗的山景" --poll
自訂品質與設定
# 品質模式(速度或品質)
z-ai video -p "夕陽下的海浪" --quality quality --poll
# 自訂解析度與 FPS
z-ai video \
-p "城市縮時攝影" \
--size "1920x1080" \
--fps 60 \
--poll
# 自訂持續時間(5 或 10 秒)
z-ai video -p "煙火表演" --duration 10 --poll
圖片轉影片
重要:對於 image_url 參數,強烈建議使用 base64 編碼的圖片資料,而非 URL。這種方式更可靠,可避免潛在的網路問題或存取限制。
注意:請將 data URI 中的 MIME 類型與實際圖片格式(image/jpeg、image/png、image/webp 等)相符,以避免解碼問題。
# 從單張圖片使用 base64 生成影片(建議使用)
# 將您的圖片轉換為 base64,並使用正確的 MIME 類型
# 針對 PNG 圖片
IMAGE_BASE64=$(base64 -i image.png)
z-ai video \
--image-url "data:image/png;base64,${IMAGE_BASE64}" \
--prompt "讓場景活起來" \
--poll
# 針對 JPEG 圖片
IMAGE_BASE64=$(base64 -i photo.jpg)
z-ai video \
--image-url "data:image/jpeg;base64,${IMAGE_BASE64}" \
--prompt "讓場景活起來" \
--poll
# 針對 WebP 圖片
IMAGE_BASE64=$(base64 -i image.webp)
z-ai video \
--image-url "data:image/webp;base64,${IMAGE_BASE64}" \
--prompt "讓場景活起來" \
--poll
# 使用 URL(較不建議,可能會有可靠性問題)
z-ai video \
-i "https://example.com/photo.jpg" \
-p "為此場景加入動態" \
--poll
首尾影格模式
重要:為確保最佳可靠性,請使用 base64 編碼的圖片而非 URL。請確保 MIME 類型與實際圖片格式相符。
# 使用 base64 在兩個影格之間生成影片(建議使用)
# 確保對每張圖片使用正確的 MIME 類型
# 範例:使用 PNG 圖片
START_BASE64=$(base64 -i start.png)
END_BASE64=$(base64 -i end.png)
z-ai video \
--image-url "data:image/png;base64,${START_BASE64},data:image/png;base64,${END_BASE64}" \
--prompt "影格間的順暢轉場" \
--poll
# 範例:使用 JPEG 圖片
START_BASE64=$(base64 -i start.jpg)
END_BASE64=$(base64 -i end.jpg)
z-ai video \
--image-url "data:image/jpeg;base64,${START_BASE64},data:image/jpeg;base64,${END_BASE64}" \
--prompt "影格間的順暢轉場" \
--poll
# 使用 URL(較不建議)
z-ai video \
--image-url "https://example.com/start.png,https://example.com/end.png" \
--prompt "影格間的順暢轉場" \
--poll
含音效生成
# 生成影片並同時以 AI 產生音效
z-ai video \
-p "暴風雨來臨" \
--with-audio \
--poll
儲存輸出
# 將任務結果儲存為 JSON 檔案
z-ai video \
-p "山頂日出" \
--poll \
-o video_result.json
自訂輪詢參數
# 自訂輪詢行為
z-ai video \
-p "跳舞機器人" \
--poll \
--poll-interval 10 \
--max-polls 30
# 建立任務但不輪詢(取得任務 ID)
z-ai video -p "抽象藝術動畫" -o task.json
CLI 參數
--prompt, -p <text>:選用 - 影片的文字描述--image-url, -i <data>:選用 - 最好是 base64 編碼的圖片資料(例如 "data:image/png;base64,iVBORw...")。也支援 URL,但較不建議。若為兩張圖片,請使用逗號分隔的值。--quality, -q <mode>:選用 - 輸出模式:speed或quality(預設:speed)--with-audio:選用 - 以 AI 產生音效(預設:false)--size, -s <resolution>:選用 - 影片解析度(例如 "1920x1080")--fps <rate>:選用 - 影格率:30 或 60(預設:30)--duration, -d <seconds>:選用 - 持續時間:5 或 10 秒(預設:5)--model, -m <model>:選用 - 要使用的模型名稱--poll:選用 - 自動輪詢直到任務完成--poll-interval <seconds>:選用 - 輪詢間隔(預設:5)--max-polls <count>:選用 - 最大輪詢次數(預設:60)--output, -o <path>:選用 - 輸出檔案路徑(JSON 格式)
支援的解析度
1024x1024768x1344864x11521344x7681152x8641440x720720x14401920x1080(以及其他標準解析度)
稍後檢查任務狀態
如果您建立任務時未使用 --poll,之後仍可檢查其狀態:
# 從初始回應取得任務 ID
z-ai async-result --id "task-id-here" --poll
何時使用 CLI 與 SDK
適用 CLI 的時機:
- 快速測試影片生成
- 簡單的一次性影片建立
- 命令列自動化腳本
- 測試不同的提示與設定
適用 SDK 的時機:
- 批次影片生成,並搭配自訂邏輯
- 與網頁應用程式整合
- 自訂任務佇列管理
- 需要複雜工作流程的生產級應用程式
影片生成工作流程
影片生成遵循兩步驟非同步模式:
- 建立任務:提交影片生成請求,並取得任務 ID
- 輪詢結果:查詢任務狀態,直到完成並取得影片 URL
基本影片生成實作
簡易文字轉影片生成
import ZAI from 'z-ai-web-dev-sdk';
async function generateVideo(prompt) {
try {
const zai = await ZAI.create();
// 建立影片生成任務
const task = await zai.video.generations.create({
prompt: prompt,
quality: 'speed', // 'speed' 或 'quality'
with_audio: false,
size: '1920x1080',
fps: 30,
duration: 5
});
console.log('任務 ID:', task.id);
console.log('任務狀態:', task.task_status);
// 輪詢結果
let result = await zai.async.result.query(task.id);
let pollCount = 0;
const maxPolls = 60;
const pollInterval = 5000; // 5 秒
while (result.task_status === 'PROCESSING' && pollCount < maxPolls) {
pollCount++;
console.log(`輪詢 ${pollCount}/${maxPolls}:狀態為 ${result.task_status}`);
await new Promise(resolve => setTimeout(resolve, pollInterval));
result = await zai.async.result.query(task.id);
}
if (result.task_status === 'SUCCESS') {
// 從多個可能的欄位取得影片 URL
const videoUrl = result.video_result?.[0]?.url ||
result.video_url ||
result.url ||
result.video;
console.log('影片 URL:', videoUrl);
return videoUrl;
} else {
console.log('任務失敗或仍在處理中');
return null;
}
} catch (error) {
console.error('影片生成失敗:', error.message);
throw error;
}
}
// 使用方式
const videoUrl = await generateVideo('一隻貓正在玩球。');
console.log('生成的影片:', videoUrl);
圖片轉影片生成
重要:image_url 參數可接受 base64 編碼的圖片資料與 URL,但強烈建議使用 base64 編碼,以獲得更好的可靠性並避免與網路相關的問題。
關鍵:務必將 base64 data URI 中的 MIME 類型與實際圖片格式相符,以防止解碼錯誤。
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
import path from 'path';
// 輔助函式:從副檔名偵測 MIME 類型
function getMimeType(filePath) {
const ext = path.extname(filePath).toLowerCase();
const mimeTypes = {
'.jpg': 'image/jpeg',
'.jpeg': 'image/jpeg',
'.png': 'image/png',
'.gif': 'image/gif',
'.webp': 'image/webp',
'.bmp': 'image/bmp'
};
return mimeTypes[ext] || 'image/jpeg'; // 若未知則預設為 JPEG
}
async function generateVideoFromImage(imagePath, prompt) {
const zai = await ZAI.create();
// 方法 1:使用 base64 編碼的圖片(建議使用)
// 從副檔名自動偵測 MIME 類型
const imageBuffer = fs.readFileSync(imagePath);
const mimeType = getMimeType(imagePath);
const base64Image = `data:${mimeType};base64,${imageBuffer.toString('base64')}`;
const task = await zai.video.generations.create({
image_url: base64Image, // 帶有正確 MIME 類型的 base64 資料字串
prompt: prompt,
quality: 'quality',
duration: 5,
fps: 30
});
return task;
}
// 方法 2:使用 URL(較不建議)
async function generateVideoFromImageUrl(imageUrl, prompt) {
const zai = await ZAI.create();
const task = await zai.video.generations.create({
image_url: imageUrl, // URL 字串
prompt: prompt,
quality: 'quality',
duration: 5,
fps: 30
});
return task;
}
// 使用範例
const task1 = await generateVideoFromImage(
'./images/photo.jpg', // 可處理 JPEG
'以柔和動態為此場景加入動畫'
);
const task2 = await generateVideoFromImage(
'./images/graphic.png', // 可處理 PNG
'加入動態移動'
);
const task3 = await generateVideoFromImage(
'./images/animation.webp', // 可處理 WebP
'讓它活起來'
);
使用起始與結束影格的圖片轉影片
重要:對於關鍵影格模式,強烈建議使用 base64 編碼的圖片而非 URL,以確保一致且可靠的影片生成。請務必為每張圖片使用正確的 MIME 類型。
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
import path from 'path';
// 輔助函式:從副檔名偵測 MIME 類型
function getMimeType(filePath) {
const ext = path.extname(filePath).toLowerCase();
const mimeTypes = {
'.jpg': 'image/jpeg',
'.jpeg': 'image/jpeg',
'.png': 'image/png',
'.gif': 'image/gif',
'.webp': 'image/webp',
'.bmp': 'image/bmp'
};
return mimeTypes[ext] || 'image/jpeg';
}
async function generateVideoWithKeyframes(startImagePath, endImagePath, prompt) {
const zai = await ZAI.create();
// 方法 1:使用 base64 編碼的圖片(建議使用)
// 為每張圖片自動偵測 MIME 類型
const startBuffer = fs.readFileSync(startImagePath);
const endBuffer = fs.readFileSync(endImagePath);
const startMimeType = getMimeType(startImagePath);
const endMimeType = getMimeType(endImagePath);
const startBase64 = `data:${startMimeType};base64,${startBuffer.toString('base64')}`;
const endBase64 = `data:${endMimeType};base64,${endBuffer.toString('base64')}`;
const task = await zai.video.generations.create({
image_url: [startBase64, endBase64], // 帶有正確 MIME 類型的 base64 字串陣列
prompt: prompt,
quality: 'quality',
duration: 10,
fps: 30
});
console.log('已使用關鍵影格建立任務:', task.id);
return task;
}
// 方法 2:使用 URL(較不建議)
async function generateVideoWithKeyframesUrl(startImageUrl, endImageUrl, prompt) {
const zai = await ZAI.create();
const task = await zai.video.generations.create({
image_url: [startImageUrl, endImageUrl], // URL 字串陣列
prompt: prompt,
quality: 'quality',
duration: 10,
fps: 30
});
console.log('已使用關鍵影格建立任務:', task.id);
return task;
}
// 使用不同格式的範例
const task1 = await generateVideoWithKeyframes(
'./frames/start.jpg', // JPEG 起始影格
'./frames/end.jpg', // JPEG 結束影格
'這些場景之間的順暢轉場'
);
const task2 = await generateVideoWithKeyframes(
'./frames/start.png', // PNG 起始影格
'./frames/end.webp', // WebP 結束影格 - 不同格式也能運作!
'圖片之間的變形效果'
);
非同步結果管理
查詢任務狀態
import ZAI from 'z-ai-web-dev-sdk';
async function checkTaskStatus(taskId) {
try {
const zai = await ZAI.create();
const result = await zai.async.result.query(taskId);
console.log('任務狀態:', result.task_status);
if (result.task_status === 'SUCCESS') {
// 從結果中擷取影片 URL
const videoUrl = result.video_result?.[0]?.url ||
result.video_url ||
result.url ||
result.video;
if (videoUrl) {
console.log('影片 URL:', videoUrl);
return { success: true, url: videoUrl };
}
} else if (result.task_status === 'PROCESSING') {
console.log('任務仍在處理中');
return { success: false, status: 'processing' };
} else if (result.task_status === 'FAIL') {
console.log('任務失敗');
return { success: false, status: 'failed' };
}
} catch (error) {
console.log('查詢任務狀態時發生錯誤:', error.message);
return { success: false, status: 'error', message: error.message };
}
}
// 使用方式
const result = await checkTaskStatus('your-task-id-here');
批次影片生成
import ZAI from 'z-ai-web-dev-sdk';
async function batchGenerateVideos(prompts) {
const zai = await ZAI.create();
const tasks = [];
// 建立所有任務
for (const prompt of prompts) {
const task = await zai.video.generations.create({
prompt: prompt,
quality: 'speed',
duration: 5,
fps: 30
});
tasks.push(task);
console.log(`已建立任務:${task.id} - 提示:${prompt}`);
}
// 輪詢所有任務的結果
const results = [];
for (const task of tasks) {
console.log(`正在處理任務:${task.id}`);
let result = null;
let pollCount = 0;
while (pollCount < 60) {
result = await zai.async.result.query(task.id);
if (result.task_status === 'SUCCESS' || result.task_status === 'FAIL') {
break;
}
pollCount++;
await new Promise(resolve => setTimeout(resolve, 5000));
}
if (result?.task_status === 'SUCCESS') {
const videoUrl = result.video_result?.[0]?.url ||
result.video_url ||
result.url ||
result.video;
results.push({ prompt: task.prompt, url: videoUrl });
console.log(`已完成任務 ${task.id}:${videoUrl}`);
}
}
return results;
}
// 使用方式
const prompts = [
'一隻貓在公園裡奔跑',
'夕陽下的海浪',
'城市鳥瞰圖'
];
const videos = await batchGenerateVideos(prompts);
console.log('批次生成的影片:', videos);
工作流程範例
import ZAI from 'z-ai-web-dev-sdk';
// 建立一個輔助函式來等待任務並擷取 URL
async function waitForVideo(prompt) {
const zai = await ZAI.create();
const task = await zai.video.generations.create({
prompt: prompt,
quality: 'quality',
duration: 10,
fps: 30,
size: '1920x1080',
with_audio: true
});
console.log(`已建立任務,ID:${task.id}`);
let status = 'PROCESSING';
while (status === 'PROCESSING') {
const result = await zai.async.result.query(task.id);
status = result.task_status;
console.log(`狀態:${status}`);
await new Promise(resolve => setTimeout(resolve, 5000));
}
const result = await zai.async.result.query(task.id);
if (result.task_status === 'SUCCESS') {
return result.video_result?.[0]?.url || result.video_url;
}
return null;
}