Communitygithub.com

AiCurv/ADBCommander

z-ai-web-dev-sdk を使用した AI 駆動の動画生成機能を実装します。テキストプロンプトや画像から動画を生成したり、プログラムによる動画コンテンツ作成や動画出力を生成するアプリケーション構築が必要な場合に使用します。非同期タスク管理とステータスポーリング、結果取得をサポートします。

ADBCommander とは?

このスキルは、`z-ai-web-dev-sdk` パッケージを利用して、AI モデルがテキストや画像から動画を生成する機能を実装するためのものです。動画生成は非同期タスクモデルを採用しており、タスクを作成した後、結果が完了するまでポーリングして動画 URL を取得します。このスキルは、シンプルなテキスト→動画生成から、複数のキーフレーム間のスムーズな遷移、AI によるオーディオ生成、さらには解像度やフレームレート、品質モードなどの細かなパラメータ調整までサポートしています。CLI インターフェースと SDK の両方を提供しており、CLI はテストや簡単な自動化に、SDK は複雑な本番アプリケーションやカスタムタスク管理に適しています。また、画像をベース64エンコードして送信する方法を強く推奨しており、これによりネットワーク関連の問題を回避し、信頼性の高い動画生成を実現します。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/AiCurv/ADBCommander/tree/HEAD/skills/video-generation

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

動画生成スキル

このスキルは、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 形式)

サポートされる解像度

  • 1024x1024
  • 768x1344
  • 864x1152
  • 1344x768
  • 1152x864
  • 1440x720
  • 720x1440
  • 1920x1080(およびその他の標準解像度)

後でタスクステータスを確認

--poll なしでタスクを作成した場合、後でステータスを確認できます。

# 初期レスポンスからタスク ID を取得
z-ai async-result --id "task-id-here" --poll

CLI と SDK の使い分け

CLI を使用するケース:

  • クイック動画生成テスト
  • シンプルな単発動画作成
  • コマンドライン自動化スクリプト
  • さまざまなプロンプトと設定のテスト

SDK を使用するケース:

  • カスタムロジックによるバッチ動画生成
  • Web アプリケーションとの統合
  • カスタムタスクキューの管理
  • 複雑なワークフローを伴う本番アプリケーション

動画生成ワークフロー

動画生成は以下の 2 段階の非同期パターンに従います。

  1. タスクを作成: 動画生成リクエストを送信し、タスク ID を受け取る
  2. 結果をポーリング: タスクステータスを完了までクエリし、動画 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 パラメータリファレンス

動画生成パラメータ

パラメータ型デフォルト説明
promptstring必須動画のテキスト説明
image_urlstring | string[]任意base64 画像データまたは URL。複数の画像には配列を使用
quality'speed' | 'quality''speed'出力品質モード
with_audiobooleanfalseAI オーディオ効果を含める
sizestring'1024x1024'動画解像度
fpsnumber30フレームレート(30 または 60)
durationnumber5動画の長さ(5 または 10 秒)
modelstring任意使用するモデル名

レスポンスフィールド

フィールド型説明
idstringタスクの一意識別子
task_statusstring現在のタスクステータス(PROCESSING、SUCCESS、FAIL)
video_resultArray動画結果オブジェクトの配列(成功時)
video_result[].urlstring生成された動画の URL
video_urlstring動画 URL(代替フィールド)
urlstring動画 URL(代替フィールド)
videostring動画 URL(代替フィールド)

ベストプラクティス

  1. 画像には base64 を使用: image_url パラメータには常に base64 エンコード画像を使用し、URL は避けてください。そうすることで、ネットワーク関連の問題が防止され、より信頼性の高い動画生成が保証されます。

  2. MIME タイプを一致させる: base64 データ URI 内の MIME タイプが実際の画像形式と一致していることを確認し、デコードの問題を防いでください。例: PNG 画像には data:image/png;base64,...、JPEG には data:image/jpeg;base64,...。

  3. 適切なポーリング間隔: ポーリング間隔は少なくとも 5 秒に設定し、API レート制限を回避しながら、結果をポーリングするのに十分な速さを確保します。

  4. 進行状況を監視: 長時間実行されるタスクの場合は、ポーリングの進行状況をログに記録して、タスクがスタックしていないことを確認します。

  5. バグの処理: 特にキーフレーム使用時には、不完全またはエラーのある結果を適切に処理します。

  6. リトライロジック: 一時的な障害に対しては、指数バックオフを使用したリトライロジックを実装します。

  7. 対応する解像度: サポートされている解像度を使用して、期待される結果が得られるようにします。カスタムのアスペクト比には 1024x1024 が適切なデフォルトです。

  8. パフォーマンスを考慮: quality を 'speed' に設定すると、'quality' に比べて一般的に処理が速くなります。アプリケーションのニーズに基づいて選択します。

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

AiCurv/ADBCommander

Generate a single-file Chinese atelier-style portfolio website (horizontal-row list + hover-reveal thumb interaction, art lishu typography "Alimama DaoLiTi" via CDN, light/dark theme, hash-routed detail pages). Takes a natural-language description of the studio (name, director, discipline, works) and outputs ONE working .html file. Runs in BOTH Claude Code (writes to ~/Desktop) and GLM / online chat (outputs HTML inline). Trigger phrases include "做个中式工作室作品集", "做个隶书作品集", "lishu-portfolio-gen ...", "做个白屋风格的作品集", or when user drags this skill folder into chat asking for an atelier-style site.

AiCurv/ADBCommander

Premium calm-tech SaaS landing template — bilingual (CN/EN) literary voice over a dark forest-night palette with warm gold accent, Cormorant + Noto Serif SC, Three.js procedural forest hero, station-based scrolling narrative, custom cursor. Built for ambient-AI / creative-tool / philosophical SaaS, not loud commercial launch.

AiCurv/ADBCommander

Pro-camera HUD mockup template — full-viewport black canvas wrapping a real video with monospace overlays (corner brackets, top status bar, side AF/exposure columns, bottom timecode + aperture/shutter/ISO row, vertical 8-filter wheel, animated reticle). For cinematographer portfolios, camera-app demos, LUT pack previews, filter-look auditions. NOT a TikTok/Reels mockup, NOT a storyboard, NOT a shot list, NOT a script document. The chrome wraps real footage — never a div placeholder.

AiCurv/ADBCommander

Premium pre-launch waitlist page template — dark charcoal canvas with subtle vignette, drifting portrait video-thumbnail cards, fade-up cascades, glass nav, live-updating join counter, single email form with success/error states. Built for creative-tool / AI / niche-SaaS invite-only launches with hushed exclusive tone, not loud growth-marketing.

AiCurv/ADBCommander

Route design-related HTML artifact tasks to the right artifact skill, reference, design system generation, or export skill.

AiCurv/ADBCommander

Implement text-to-speech (TTS) capabilities using the z-ai-web-dev-sdk. Use this skill when the user needs to convert text into natural-sounding speech, create audio content, build voice-enabled applications, or generate spoken audio files. Supports multiple voices, adjustable speed, and various audio formats.

AiCurv/ADBCommander

Implement specialized video understanding capabilities using the z-ai-web-dev-sdk. Use this skill when the user needs to analyze video content, understand motion and temporal sequences, extract information from video frames, describe video scenes, or perform video-based AI analysis. Optimized for MP4, AVI, MOV, and other common video formats.

関連スキル