動画生成スキル
このスキルは、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 タイプを使用
# 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 つのフレーム間の動画を生成(推奨)
# 各画像に正しい 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 もサポートされていますが、非推奨です。2 枚の画像にはカンマ区切り値を使用します。--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 を使用するケース:
- カスタムロジックによるバッチ動画生成
- 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('タスク 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 データ 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('タスクステータス:', 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.error('タスクステータスの確認に失敗しました:', error.message);
return { success: false, status: 'error', message: error.message };
}
}
// 使用例
const status = await checkTaskStatus('your-task-id-here');
if (status.success) {
console.log('動画 URL:', status.url);
// 動画をダウンロードまたは表示
}
ポーリングによる完了待機
import ZAI from 'z-ai-web-dev-sdk';
async function waitForCompletion(taskId) {
const zai = await ZAI.create();
let result = await zai.async.result.query(taskId);
let pollCount = 0;
const maxPolls = 60;
const pollInterval = 5000; // 5 秒
while (result.task_status === 'PROCESSING' && pollCount < maxPolls) {
pollCount++;
console.log(`${pollCount} 回目のポーリング: ステータス = ${result.task_status}`);
await new Promise(resolve => setTimeout(resolve, pollInterval));
result = await zai.async.result.query(taskId);
}
if (result.task_status === 'SUCCESS') {
// 動画 URL を抽出
const videoUrl = result.video_result?.[0]?.url ||
result.video_url ||
result.url ||
result.video;
return {
success: true,
videoUrl: videoUrl,
taskId: taskId,
pollsUsed: pollCount
};
}
return {
success: false,
status: result.task_status,
taskId: taskId,
pollsUsed: pollCount
};
}
高度な機能
カスタム結果の処理
// エラーのある不完全な結果を処理
if (result.task_status === 'SUCCESS' && result.video_result) {
const videos = result.video_result;
videos.forEach((video, index) => {
if (video.url) {
console.log(`動画 ${index + 1}: ${video.url}`);
} else {
console.warn(`動画 ${index + 1}: URL が見つかりません`);
}
});
}
バッチ処理
import ZAI from 'z-ai-web-dev-sdk';
async function generateMultipleVideos(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) {
const result = await waitForCompletion(task.id);
results.push(result);
console.log(`タスク ${task.id} の結果:`, result.success ? '成功' : '失敗');
}
return results;
}
エラー処理
import ZAI from 'z-ai-web-dev-sdk';
async function generateVideoWithRetry(prompt, maxRetries = 3) {
for (let attempt = 1; attempt <= maxRetries; attempt++) {
try {
const zai = await ZAI.create();
const task = await zai.video.generations.create({
prompt: prompt,
quality: 'speed',
duration: 5,
fps: 30
});
const result = await waitForCompletion(task.id);
if (result.success) {
return result;
}
console.warn(`試行 ${attempt} が失敗しました。ステータス: ${result.status}`);
} catch (error) {
console.error(`試行 ${attempt} でエラー:`, error.message);
if (attempt === maxRetries) {
throw new Error(`動画生成に失敗しました (${maxRetries} 回試行): ${error.message}`);
}
// 再試行前に待機(指数バックオフ)
await new Promise(resolve => setTimeout(resolve, 1000 * Math.pow(2, attempt)));
}
}
}
// 使用例
try {
const result = await generateVideoWithRetry('踊るロボット');
console.log('動画 URL:', result.videoUrl);
} catch (error) {
console.error('最終エラー:', error.message);
}
SDK パラメータリファレンス
動画生成パラメータ
| パラメータ | 型 | デフォルト | 説明 |
|---|---|---|---|
prompt | string | 必須 | 動画のテキスト説明 |
image_url | string | string[] | 任意 | base64 画像データまたは URL。複数の画像には配列を使用 |
quality | 'speed' | 'quality' | 'speed' | 出力品質モード |
with_audio | boolean | false | AI オーディオ効果を含める |
size | string | '1024x1024' | 動画解像度 |
fps | number | 30 | フレームレート(30 または 60) |
duration | number | 5 | 動画の長さ(5 または 10 秒) |
model | string | 任意 | 使用するモデル名 |
レスポンスフィールド
| フィールド | 型 | 説明 |
|---|---|---|
id | string | タスクの一意識別子 |
task_status | string | 現在のタスクステータス(PROCESSING、SUCCESS、FAIL) |
video_result | Array | 動画結果オブジェクトの配列(成功時) |
video_result[].url | string | 生成された動画の URL |
video_url | string | 動画 URL(代替フィールド) |
url | string | 動画 URL(代替フィールド) |
video | string | 動画 URL(代替フィールド) |
ベストプラクティス
-
画像には base64 を使用:
image_urlパラメータには常に base64 エンコード画像を使用し、URL は避けてください。そうすることで、ネットワーク関連の問題が防止され、より信頼性の高い動画生成が保証されます。 -
MIME タイプを一致させる: base64 データ URI 内の MIME タイプが実際の画像形式と一致していることを確認し、デコードの問題を防いでください。例: PNG 画像には
data:image/png;base64,...、JPEG にはdata:image/jpeg;base64,...。 -
適切なポーリング間隔: ポーリング間隔は少なくとも 5 秒に設定し、API レート制限を回避しながら、結果をポーリングするのに十分な速さを確保します。
-
進行状況を監視: 長時間実行されるタスクの場合は、ポーリングの進行状況をログに記録して、タスクがスタックしていないことを確認します。
-
バグの処理: 特にキーフレーム使用時には、不完全またはエラーのある結果を適切に処理します。
-
リトライロジック: 一時的な障害に対しては、指数バックオフを使用したリトライロジックを実装します。
-
対応する解像度: サポートされている解像度を使用して、期待される結果が得られるようにします。カスタムのアスペクト比には
1024x1024が適切なデフォルトです。 -
パフォーマンスを考慮:
qualityを'speed'に設定すると、'quality'に比べて一般的に処理が速くなります。アプリケーションのニーズに基づいて選択します。