動画生成スキル
このスキルは、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 タイプが実際の画像フォーマットと一致していることを確認してください。
# base64 を使用した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);
throw error;
}
}
// 使用例
const status = await checkTaskStatus('task-123');
if (status.success) {
console.log('動画 URL:', status.url);
}
効率的なポーリング
import ZAI from 'z-ai-web-dev-sdk';
async function pollWithBackoff(taskId, maxRetries = 30) {
const zai = await ZAI.create();
let delay = 2000; // 2秒から開始
for (let i = 0; i < maxRetries; i++) {
const result = await zai.async.result.query(taskId);
switch (result.task_status) {
case 'SUCCESS':
const videoUrl = result.video_result?.[0]?.url ||
result.video_url ||
result.url ||
result.video;
return { success: true, url: videoUrl };
case 'FAIL':
return { success: false, error: result.error || 'タスクが失敗しました' };
case 'PROCESSING':
// エクスポネンシャルバックオフで待機(最大30秒)
console.log(`試行 ${i + 1}/${maxRetries}, ${delay/1000}秒待機...`);
await new Promise(resolve => setTimeout(resolve, delay));
delay = Math.min(delay * 1.5, 30000); // 最大30秒まで増加
break;
default:
console.log('不明なステータス:', result.task_status);
return { success: false, error: '不明なステータス' };
}
}
return { success: false, error: '最大再試行回数を超えました' };
}
// 使用例
const result = await pollWithBackoff('task-456');
高度な設定とオプション
利用可能なパラメータ
| パラメータ | 型 | デフォルト | 説明 |
|---|---|---|---|
| prompt | string | なし | 動画のテキスト説明 |
| image_url | string または配列 | なし | 推奨: base64 エンコード画像データ。URL もサポート。2画像のキーフレームには配列を使用。 |
| quality | string | 'speed' | 出力品質: 'speed' または 'quality' |
| with_audio | boolean | false | AI オーディオエフェクトを生成 |
| size | string | '1024x1024' | 動画解像度 (例: '1920x1080') |
| fps | number | 30 | フレームレート: 30 または 60 |
| duration | number | 5 | 再生時間(秒): 5 または 10 |
| model | string | なし | 使用する特定のモデル |
応答オブジェクト
{
id: 'task-xxx',
task_status: 'PROCESSING' | 'SUCCESS' | 'FAIL',
video_result: [{ url: 'https://...' }], // SUCCESS の場合に利用可能
video_url: 'https://...', // 代替フィールド
video: 'https://...', // 別の代替フィールド
error: 'エラーメッセージ', // FAIL の場合に利用可能
created_at: '2024-01-01T00:00:00Z',
updated_at: '2024-01-01T00:00:00Z'
}
ベストプラクティス
-
base64 画像データを優先: 画像入力には、URL よりも base64 エンコード画像データを常に優先してください。信頼性が高く、ネットワークの問題を回避できます。
-
適切な MIME タイプ: base64 データ URI を使用する場合、MIME タイプが実際の画像フォーマット(image/jpeg、image/png、image/webp など)と一致していることを確認してください。不一致はデコードエラーを引き起こす可能性があります。
-
画像サイズ制限: 画像が SDK/API のサイズ制限を超えないようにしてください。大きい画像は、必要に応じて事前に圧縮またはリサイズしてください。
-
バックオフ付きポーリング: ポーリングにはエクスポネンシャルバックオフを実装し、サーバーへの負荷を減らし、レート制限を回避してください。
-
タイムアウト処理: 長時間実行されるタスクのためのタイムアウト処理を常に実装してください。ほとんどの動画生成は完了までに数分かかることがあります。
-
エラーハンドリング: 動画生成 API は、サービス過負荷や一時的な問題によりさまざまなエラーを返す可能性があります。堅牢なエラーハンドリングと再試行ロジックを実装してください。
エラーハンドリング
import ZAI from 'z-ai-web-dev-sdk';
async function robustVideoGeneration(prompt) {
const 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',
with_audio: false
});
// 結果をポーリング...
return await pollWithBackoff(task.id);
} catch (error) {
console.error(`試行 ${attempt} が失敗: ${error.message}`);
if (attempt === maxRetries) {
throw new Error(`最大再試行回数 ${maxRetries} を超えました: ${error.message}`);
}
// 再試行前に待機
const waitTime = Math.pow(2, attempt) * 1000; // 2秒、4秒、8秒
console.log(`${waitTime/1000}秒後に再試行...`);
await new Promise(resolve => setTimeout(resolve, waitTime));
}
}
}
// 使用例
try {
const result = await robustVideoGeneration('踊るロボット');
if (result.success) {
console.log('動画 URL:', result.url);
}
} catch (error) {
console.error('最終エラー:', error.message);
}
トラブルシューティング
一般的な問題
-
base64 デコードエラー:
image_urlデータ URI の MIME タイプが実際の画像フォーマットと一致していることを確認してください。例: JPEG 画像にはdata:image/jpeg;base64,...。 -
画像サイズエラー: 画像ファイルサイズを確認してください。一部のモデルにはサイズ制限がある場合があります。
-
タイムアウト: 動画生成には長い時間がかかることがあります(特に quality モードの場合)。ポーリングパラメータを増やすか、長時間実行されるタスクには非同期コールバックパターンの使用を検討してください。
-
レート制限: 1分あたりのリクエスト数を制限し、429(Too Many Requests)レスポンスを適切に処理するためにレート制限を実装してください。
-
サポートされていない解像度: 使用する解像度がサポートされている解像度のリストにあることを確認してください。サポートされていない値はエラーを引き起こす可能性があります。