動画生成スキル
このスキルは、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
カスタム品質と設定
# 品質モード(speed または quality)
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 パラメータには、URLではなくBase64エンコードされた画像データを使用することを強く推奨します。この方法はより信頼性が高く、ネットワークの問題やアクセス制限を回避できます。
注記: データURIのMIMEタイプを実際の画像形式(image/jpeg、image/png、image/webpなど)に合わせて、デコードの問題を避けてください。
# 単一画像から動画を生成(Base64使用、推奨)
# 正しいMIMEタイプで画像をBase64に変換
# 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
開始・終了フレームモード
重要: 最良の信頼性を得るには、URLではなくBase64エンコードされた画像を使用してください。MIMEタイプが実際の画像形式と一致していることを確認してください。
# 2つのフレーム間で動画を生成(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 <テキスト>: オプション - 動画のテキスト説明--image-url, -i <データ>: オプション - できればBase64エンコードされた画像データ(例: "data:image/png;base64,iVBORw...")。URLもサポートされていますが、推奨されません。2つの画像の場合はカンマ区切りで指定。--quality, -q <モード>: オプション - 出力モード:speedまたはquality(デフォルト: speed)--with-audio: オプション - AIオーディオエフェクトを生成(デフォルト: false)--size, -s <解像度>: オプション - 動画解像度(例: "1920x1080")--fps <レート>: オプション - フレームレート: 30 または 60(デフォルト: 30)--duration, -d <秒>: オプション - 再生時間: 5秒または10秒(デフォルト: 5)--model, -m <モデル>: オプション - 使用するモデル名--poll: オプション - タスク完了まで自動ポーリング--poll-interval <秒>: オプション - ポーリング間隔(デフォルト: 5)--max-polls <回数>: オプション - 最大ポーリング試行回数(デフォルト: 60)--output, -o <パス>: オプション - 出力ファイルパス(JSON形式)
サポートされる解像度
1024x1024768x1344864x11521344x7681152x8641440x720720x14401920x1080(およびその他の標準解像度)
後からタスクステータスを確認
--poll なしでタスクを作成した場合、後でステータスを確認できます:
# 初期応答からタスクIDを取得
z-ai async-result --id "task-id-here" --poll
CLIとSDKの使い分け
CLIを使用する場合:
- 簡単な動画生成テスト
- シンプルな一回限りの動画作成
- コマンドライン自動化スクリプト
- さまざまなプロンプトと設定のテスト
SDKを使用する場合:
- カスタムロジックによるバッチ動画生成
- Webアプリケーションとの統合
- カスタムタスクキューの管理
- 複雑なワークフローを伴う本番アプリケーション
動画生成ワークフロー
動画生成は2段階の非同期パターンに従います:
- タスクを作成: 動画生成リクエストを送信し、タスク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('Task ID:', task.id);
console.log('Task Status:', 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('Video 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データ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で動作
'これを生き生きとさせる'
);
開始フレームと終了フレームを使用した画像から動画への生成
重要: キーフレームモードでは、一貫性と信頼性のある動画生成のために、URLよりもBase64エンコードされた画像を強く推奨します。各画像に正しい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('Task Status:', 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('Video 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
[注: オリジナルのSKILL.mdが途中で切れていますが、翻訳可能な部分は翻訳しました。完全な翻訳が必要な場合は、完全なSKILL.mdを提供してください。]